PredefinedColorsQuantizerArgb8888 Method

Gets a PredefinedColorsQuantizer instance that can quantize colors to the 32-bit ARGB color space.

Definition

Namespace: KGySoft.Drawing.Imaging
Assembly: KGySoft.Drawing.Core (in KGySoft.Drawing.Core.dll) Version: 9.0.0

public static PredefinedColorsQuantizer Argb8888(
	Color32 backColor = default,
	byte alphaThreshold = 128
)

Public Shared Function Argb8888 ( 
	Optional backColor As Color32 = Nothing,
	Optional alphaThreshold As Byte = 128
) As PredefinedColorsQuantizer

C++

public:
static PredefinedColorsQuantizer^ Argb8888(
	Color32 backColor = Color32(), 
	unsigned char alphaThreshold = 128
)

static member Argb8888 : 
        ?backColor : Color32 * 
        ?alphaThreshold : byte 
(* Defaults:
        let _backColor = defaultArg backColor new Color32()
        let _alphaThreshold = defaultArg alphaThreshold 128
*)
-> PredefinedColorsQuantizer

Parameters

backColor Color32 (Optional): Determines the BackColor property of the returned quantizer. Considering that this quantizer can return alpha colors it has effect only when the returned quantizer is used with a ditherer that does not support partial transparency. The Color32.A field of the background color is ignored. This parameter is optional.
Default value:The default value of the Color32 type, which has the same RGB values as Color.Black.
alphaThreshold Byte (Optional): Specifies a threshold value for the Color32.A field, under which a quantized color is considered completely transparent. If 0, then the quantized colors will preserve their original alpha value. This parameter is optional.
Default value: 128.

Return Value

PredefinedColorsQuantizer
A PredefinedColorsQuantizer instance that can quantize colors to the 32-bit ARGB color space.

Remarks

If alphaThreshold is zero, then the returned PredefinedColorsQuantizer instance is practically just a pass-through filter in the 32-bit color space, and it is effective only for some bitmap data operations (eg. Clone), which could possibly preserve wide color information (KnownPixelFormats with more than 32 bpp) without specifying a quantizer.

If alphaThreshold is not zero, then every partially transparent pixel with lower Color.A value than the threshold will turn completely transparent.

This quantizer fits well for the Format32bppArgb pixel format.

Examples

The following example demonstrates how to use the quantizer returned by this method:

public static IReadWriteBitmapData ToArgb8888(IReadWriteBitmapData source, Color32 backColor = default,
    byte alphaThreshold = 128, IDitherer ditherer = null)
{
    IQuantizer quantizer = PredefinedColorsQuantizer.Argb8888(backColor, alphaThreshold);

    // a.) this solution returns a new bitmap data and does not change the original one:
    return source.Clone(KnownPixelFormat.Format32bppArgb, quantizer, ditherer);

    // b.) when converting to Format32bppArgb format without dithering, this produces the same result:
    if (ditherer == null && alphaThreshold == 0)
        return source.Clone(KnownPixelFormat.Format32bppArgb);

    // c.) alternatively, you can perform the quantizing directly on the source bitmap data:
    if (ditherer == null)
        source.Quantize(quantizer);
    else
        source.Dither(quantizer, ditherer);
    return source;
}

The example above may produce the following results:

Original image	Quantized image
Color hues with alpha gradient	Default optional parameter values (black background, alpha threshold = 128). The top-half of the image preserved the original transparency, while bottom half turned completely transparent. Without dithering the back color is irrelevant. Silver background, alpha threshold = 1. Only the bottom line is completely transparent, otherwise the image preserved its original transparency, so the result is practically the same as the original image. Without dithering the back color is irrelevant. Silver background, alpha threshold = 1, Bayer 8x8 dithering. As dithering does not support partial transparency only the bottom line is transparent, otherwise the image was blended with back color. No dithering pattern appeared in the result due to the auto strength calibration. This also demonstrates why dithering is practically useless for true color results.
Shield icon with transparency	Default optional parameter values (black background, alpha threshold = 128). Without dithering the back color is irrelevant but pixels with alpha < 128 turned completely transparent. Silver background, alpha threshold = 1. Practically the same as the original image. Without dithering the back color is irrelevant. Silver background, alpha threshold = 1, Floyd-Steinberg dithering. As dithering does not support partial transparency alpha pixels were blended with back color. No dithering pattern appeared in the result as there was no quantizing error during the process. This also demonstrates why dithering is practically useless for true color results.

Original image

Quantized image

Color hues with alpha gradient

Color hues with ARGB8888 pixel format, black background and default alpha threshold
Default optional parameter values (black background, alpha threshold = 128). The top-half of the image preserved the original transparency, while bottom half turned completely transparent. Without dithering the back color is irrelevant.

Color hues with ARGB8888 pixel format, silver background and alpha threshold = 1
Silver background, alpha threshold = 1. Only the bottom line is completely transparent, otherwise the image preserved its original transparency, so the result is practically the same as the original image. Without dithering the back color is irrelevant.

Color hues with ARGB8888 pixel format, silver background, alpha threshold = 1, using Bayer 8x8 ordered dithering
Silver background, alpha threshold = 1, Bayer 8x8 dithering. As dithering does not support partial transparency only the bottom line is transparent, otherwise the image was blended with back color. No dithering pattern appeared in the result due to the auto strength calibration. This also demonstrates why dithering is practically useless for true color results.

Shield icon with transparent background
Shield icon with transparency

Shield icon with ARGB8888 pixel format, black background and default alpha threshold
Default optional parameter values (black background, alpha threshold = 128). Without dithering the back color is irrelevant but pixels with alpha < 128 turned completely transparent.

Shield icon with ARGB8888 pixel format, silver background and alpha threshold = 1
Silver background, alpha threshold = 1. Practically the same as the original image. Without dithering the back color is irrelevant.

Shield icon with ARGB8888 pixel format, silver background, alpha threshold = 1, using Floyd-Steinberg dithering
Silver background, alpha threshold = 1, Floyd-Steinberg dithering. As dithering does not support partial transparency alpha pixels were blended with back color. No dithering pattern appeared in the result as there was no quantizing error during the process. This also demonstrates why dithering is practically useless for true color results.