Subroutines (C++ API)

void convert_and_scale_down_weighted()

Pre-process and scale down input image.

Converts the input image to float, and the input mask to binary (stored as uint8_t). If no input mask is provided (nullptr), the last color channel of the input image is used as the mask (e.g. “A” for an RGBA image).

Image and mask are scaled down to half their size, using the mask-weighted average for the image, and a threshold for the mask (i.e. if any of the 4 mask pixels to be scaled is 1, the scaled pixel becomes 1).

The input mask is initially processed using the coverage_threshold parameter, which defaults to 0.999f (anything above 0.999f becomes 1, all other values become 0).

The last image channel can optionally be scaled unweighted (regular box filtering). This can be useful when e.g. the alpha channel should reflect the average opacity, as opposed to becoming 1.0f through weighted scaling in cases where the alpha channel is identical to the coverage mask.

Template Parameters:

InputT

:

uint8_t/uint16_t/float

InputMaskT

:

uint8_t/uint16_t/float

Parameters:

const uint_fast16_t output_width

,:

Output image width in pixels (must be power of 2)

const uint_fast16_t output_height_or_end_row

,:

Output image height in pixels (must be power of 2), or end row for partial processing

const uint_fast8_t channel_stride

,:

Number of total channels in image data

const InputT* input_image

,:

Pointer to input image, InputT*

const InputMaskT* input_mask

,:

(optional) Pointer to input mask, InputT* or nullptr

float* output_image

,:

Pointer to pre-allocated output image, float*

uint8_t* output_mask

,:

Pointer to pre-allocated output mask, uint8_t*

const float coverage_threshold = 0.999f

,:

(optional) Threshold to use for binarizing the input mask. Defaults to 0.999f.

const bool convert_srgb_to_linear = false

,:

(optional) Convert sRGB to linear for correct scaling of sRGB textures?

const bool is_normal_map = false

,:

(optional) Perform processing for normal maps. Will re-normalize vectors to unit length at the moment, Slerp is planned.

const uint8_t channel_mask = 0

,:

(optional) Bit mask of channels to process, 0 = all channels. You can use channel_mask_from_array() to generate a mask from an array of booleans.

const bool scale_alpha_unweighted = false

,:

(optional) Scale the last channel without coverage weighting? i.e. regular box filtering

const uint_fast16_t start_row = 0

:

(optional) Start row for partial processing

void convert_and_scale_down_weighted_threaded()

Pre-process and scale down input image (threaded version)

Converts the input image to float, and the input mask to binary (stored as uint8_t). If no input mask is provided (nullptr), the last color channel of the input image is used as the mask (e.g. “A” for an RGBA image).

Image and mask are scaled down to half their size, using the mask-weighted average for the image, and a threshold for the mask (i.e. if any of the 4 mask pixels to be scaled is 1, the scaled pixel becomes 1).

The input mask is initially processed using the coverage_threshold parameter, which defaults to 0.999f (anything above 0.999f becomes 1, all other values become 0).

The last image channel can optionally be scaled unweighted (regular box filtering). This can be useful when e.g. the alpha channel should reflect the average opacity, as opposed to becoming 1.0f through weighted scaling in cases where the alpha channel is identical to the coverage mask.

Template Parameters:

InputT

:

uint8_t/uint16_t/float

InputMaskT

:

uint8_t/uint16_t/float

Parameters:

const uint_fast16_t output_width

,:

Output image width in pixels (must be power of 2)

const uint_fast16_t output_height

,:

Output image height in pixels (must be power of 2)

const uint_fast8_t channel_stride

,:

Number of total channels in image data

const InputT* input_image

,:

Pointer to input image, InputT*

const InputMaskT* input_mask

,:

(optional) Pointer to input mask, InputT* or nullptr

float* output_image

,:

Pointer to pre-allocated output image, float*

uint8_t* output_mask

,:

Pointer to pre-allocated output mask, uint8_t*

const float coverage_threshold = 0.999f

,:

(optional) Threshold to use for binarizing the input mask. Defaults to 0.999f.

const bool convert_srgb_to_linear = false

,:

(optional) Convert sRGB to linear for correct scaling of sRGB textures?

const bool is_normal_map = false

,:

(optional) Perform processing for normal maps. Will re-normalize vectors to unit length at the moment, Slerp is planned.

const uint8_t channel_mask = 0

,:

(optional) Bit mask of channels to process, 0 = all channels. You can use channel_mask_from_array() to generate a mask from an array of booleans.

const bool scale_alpha_unweighted = false

,:

(optional) Scale the last channel without coverage weighting? i.e. regular box filtering

const uint_fast8_t max_threads = 0

:

(optional) Number of threads to use. 0 = auto (half of available threads, which amounts to number of hardware cores for machines with SMT/HyperThreading)

void scale_down_weighted()

Scale down mip level.

Input mip level and mask are scaled down to half their size, using the mask-weighted average for the mip, and a threshold for the mask (i.e. if any of the 4 mask pixels to be scaled is 1, the scaled pixel becomes 1).

The last image channel can optionally be scaled unweighted (regular box filtering). This can be useful when e.g. the alpha channel should reflect the average opacity, as opposed to becoming 1.0f through weighted scaling in cases where the alpha channel is identical to the coverage mask.

Use this function in a loop after convert_and_scale_down_weighted() to generate the remaining mip levels.

Parameters:

const uint_fast16_t output_width

,:

Output mip level width in pixels (must be power of 2)

const uint_fast16_t output_height_or_end_row

,:

Output mip level height in pixels (must be power of 2), or end row for partial processing

const uint_fast8_t channel_stride

,:

Number of total channels in image data

const float* input_image

,:

Pointer to input mip level, float*

const uint8_t* input_mask

,:

Pointer to input mip mask, uint8_t*

float* output_image

,:

Pointer to pre-allocated output mip level, float*

uint8_t* output_mask

,:

Pointer to pre-allocated output mip mask, uint8_t*

const bool is_normal_map = false

,:

(optional) Perform processing for normal maps. Will re-normalize vectors to unit length at the moment, Slerp is planned.

const uint8_t channel_mask = 0

,:

(optional) Bit mask of channels to process, 0 = all channels. You can use channel_mask_from_array() to generate a mask from an array of booleans.

const bool scale_alpha_unweighted = false

,:

(optional) Scale the last channel without coverage weighting? i.e. regular box filtering

const uint_fast16_t start_row = 0

:

(optional) Start row for partial processing

void scale_down_weighted_threaded()

Scale down mip level (threaded version)

Input mip level and mask are scaled down to half their size, using the mask-weighted average for the mip, and a threshold for the mask (i.e. if any of the 4 mask pixels to be scaled is 1, the scaled pixel becomes 1).

The last image channel can optionally be scaled unweighted (regular box filtering). This can be useful when e.g. the alpha channel should reflect the average opacity, as opposed to becoming 1.0f through weighted scaling in cases where the alpha channel is identical to the coverage mask.

Use this function in a loop after convert_and_scale_down_weighted() to generate the remaining mip levels.

Parameters:

const uint_fast16_t output_width

,:

Output mip level width in pixels (must be power of 2)

const uint_fast16_t output_height

,:

Output mip level height in pixels (must be power of 2)

const uint_fast8_t channel_stride

,:

Number of total channels in image data

const float* input_image

,:

Pointer to input mip level, float*

const uint8_t* input_mask

,:

Pointer to input mip mask, uint8_t*

float* output_image

,:

Pointer to pre-allocated output mip level, float*

uint8_t* output_mask

,:

Pointer to pre-allocated output mip mask, uint8_t*

const bool is_normal_map = false

,:

(optional) Perform processing for normal maps. Will re-normalize vectors to unit length at the moment, Slerp is planned.

const uint8_t channel_mask = 0

,:

(optional) Bit mask of channels to process, 0 = all channels. You can use channel_mask_from_array() to generate a mask from an array of booleans.

const bool scale_alpha_unweighted = false

,:

(optional) Scale the last channel without coverage weighting? i.e. regular box filtering

const uint_fast8_t max_threads = 0

:

(optional) Number of threads to use. 0 = auto (half of available threads, which amounts to number of hardware cores for machines with SMT/HyperThreading)

void composite_up()

Composite mip levels (small to large)

The smaller (“input”) mip is scaled up using nearest neighbor filtering and composited into the larger mip (“output”). This fills/”floods” areas outside the coverage mask.

Use this in a loop, smallest to largest mips, after generating the mip levels using scale_down_weighted().

Parameters:

const uint_fast16_t input_width

,:

Width in pixels of the smaller mip (must be power of 2).

const uint_fast16_t input_height_or_end_row

,:

Height in pixels of the smaller mip (must be power of 2), or end row for partial processing.

const uint_fast8_t channel_stride

,:

Number of total channels in image data

const float* input_image

,:

Pointer to smaller mip, float*

float* output_image

,:

Pointer to larger mip (output), float*

const uint8_t* output_mask

,:

Pointer to larger mip mask, uint8_t*

const uint8_t channel_mask = 0

,:

(optional) Bit mask of channels to process, 0 = all channels. You can use channel_mask_from_array() to generate a mask from an array of booleans.

const uint_fast16_t start_row = 0

:

(optional) Start row for partial processing

void composite_up_threaded()

Composite mip levels (small to large) (threaded version)

The smaller (“input”) mip is scaled up using nearest neighbor filtering and composited into the larger mip (“output”). This fills/”floods” areas outside the coverage mask.

Use this in a loop, smallest to largest mips, after generating the mip levels using scale_down_weighted().

Parameters:

const uint_fast16_t input_width

,:

Width in pixels of the smaller mip (must be power of 2).

const uint_fast16_t input_height

,:

Height in pixels of the smaller mip (must be power of 2)

const uint_fast8_t channel_stride

,:

Number of total channels in image data

const float* input_image

,:

Pointer to smaller mip, float*

float* output_image

,:

Pointer to larger mip (output), float*

const uint8_t* output_mask

,:

Pointer to larger mip mask, uint8_t*

const uint8_t channel_mask = 0

,:

(optional) Bit mask of channels to process, 0 = all channels. You can use channel_mask_from_array() to generate a mask from an array of booleans.

const uint_fast8_t max_threads = 0

:

(optional) Number of threads to use. 0 = auto (half of available threads, which amounts to number of hardware cores for machines with SMT/HyperThreading)

void final_composite_and_convert()

Composite largest mip with original image.

The largest (“input”) mip is scaled up using nearest neighbor filtering, converted into the output format, and composited into the original image.

This fills/”floods” areas outside the coverage mask.

If no mask is provided (nullptr), the last color channel of the output image is used as the mask (e.g. “A” for an RGBA image). The mask is initially processed using the coverage_threshold parameter, which defaults to 0.999f (anything above 0.999f becomes 1, all other values become 0).

Use this after compositing the mip levels using composite_up().

Set a custom channel mask if you want to preserve any of the original image’s channels, e.g. the alpha channel in an RGBA image.

Template Parameters:

OutputT

:

Output image type, uint8/uint16/float

MaskT

:

Mask type, uint8/uint16/float

Parameters:

const uint_fast16_t input_width

,:

Width in pixels of the largest mip (must be power of 2, and half the width of the original image)

const uint_fast16_t input_height_or_end_row

,:

Height in pixels of the largest mip (must be power of 2, and half the height of the original image), or end row for partial processing.

const uint_fast8_t channel_stride

,:

Number of total channels in image data

const float* input_image

,:

Pointer to largest mip, float*

OutputT* output_image

,:

Pointer to output image (expected to contain original image), ImageT*

const MaskT* mask

,:

(optional) Pointer to mask, MaskT* or nullptr

const float coverage_threshold = 0.999f

,:

(optional) Threshold to use for binarizing the mask. Defaults to 0.999f.

const bool convert_linear_to_srgb = false

,:

(optional) Convert linear to sRGB

const uint8_t channel_mask = 0

,:

(optional) Bit mask of channels to process, 0 = all channels. You can use channel_mask_from_array() to generate a mask from an array of booleans.

const uint_fast16_t start_row = 0

:

(optional) Start row for partial processing

void final_composite_and_convert_threaded()

Composite largest mip with original image (threaded version)

The largest (“input”) mip is scaled up using nearest neighbor filtering, converted into the output format, and composited into the original image.

This fills/”floods” areas outside the coverage mask.

If no mask is provided (nullptr), the last color channel of the output image is used as the mask (e.g. “A” for an RGBA image). The mask is initially processed using the coverage_threshold parameter, which defaults to 0.999f (anything above 0.999f becomes 1, all other values become 0).

Use this after compositing the mip levels using composite_up().

Set a custom channel mask if you want to preserve any of the original image’s channels, e.g. the alpha channel in an RGBA image.

Template Parameters:

OutputT

:

Output image type, uint8/uint16/float

MaskT

:

Mask type, uint8/uint16/float

Parameters:

const uint_fast16_t input_width

,:

Width in pixels of the largest mip (must be power of 2, and half the width of the original image)

const uint_fast16_t input_height

,:

Height in pixels of the largest mip (must be power of 2, and half the height of the original image)

const uint_fast8_t channel_stride

,:

Number of total channels in image data

const float* input_image

,:

Pointer to largest mip, float*

OutputT* output_image

,:

Pointer to output image (expected to contain original image), ImageT*

const MaskT* mask

,:

(optional) Pointer to mask, MaskT* or nullptr

const float coverage_threshold = 0.999f

,:

(optional) Threshold to use for binarizing the mask. Defaults to 0.999f.

const bool convert_linear_to_srgb = false

,:

(optional) Convert linear to sRGB

const uint8_t channel_mask = 0

,:

(optional) Bit mask of channels to process, 0 = all channels. You can use channel_mask_from_array() to generate a mask from an array of booleans.

const uint_fast8_t max_threads = 0

:

(optional) Number of threads to use. 0 = auto (half of available threads, which amounts to number of hardware cores for machines with SMT/HyperThreading)