IWICPalette interface (wincodec.h)

Article
10/06/2021

Exposes methods for accessing and building a color table, primarily for indexed pixel formats.

Inheritance

The IWICPalette interface inherits from the IUnknown interface. IWICPalette also has these types of members:

Methods

The IWICPalette interface has these methods.


IWICPalette::GetColorCount Retrieves the number of colors in the color table.
IWICPalette::GetColors Fills out the supplied color array with the colors from the internal color table. The color array should be sized according to the return results from GetColorCount.
IWICPalette::GetType Retrieves the WICBitmapPaletteType that describes the palette.
IWICPalette::HasAlpha Indicates whether the palette contains an entry that is non-opaque (that is, an entry with an alpha that is less than 1).
IWICPalette::InitializeCustom Initializes a palette to the custom color entries provided.
IWICPalette::InitializeFromBitmap Initializes a palette using a computed optimized values based on the reference bitmap.
IWICPalette::InitializeFromPalette Initialize the palette based on a given palette.
IWICPalette::InitializePredefined Initializes the palette to one of the pre-defined palettes specified by WICBitmapPaletteType and optionally adds a transparent color.
IWICPalette::IsBlackWhite Retrieves a value that describes whether the palette is black and white.
IWICPalette::IsGrayscale Retrieves a value that describes whether a palette is grayscale.

Remarks

If the WICBitmapPaletteType is not WICBitmapPaletteCustom, then the colors are automatically generated based on the table above. If the user subsequently changes a color palette entry the WICBitmapPalette is set to Custom by that action.

InitializeFromBitmap's fAddTransparentColor parameter will add a transparent color to the end of the color collection if its size if less than 256, otherwise index 255 will be replaced with the transparent color. If a pre-defined palette type is used, it will change to BitmapPaletteTypeCustom since it no longer matches the predefined palette.

The palette interface is an auxiliary imaging interface in that it does not directly concern bitmaps and pixels; rather it provides indexed color translation for indexed bitmaps. For an indexed pixel format with M bits per pixels: (The number of colors in the palette) greater than 2^M.

Traditionally the basic operation of the palette is to provide a translation from a byte (or smaller) index into a 32bpp color value. This is often accomplished by a 256 entry table of color values.

Examples

    IWICImagingFactory *pFactory = NULL;
    IWICBitmapDecoder *pDecoder = NULL;
    IWICBitmapFrameDecode *pBitmapFrameDecode = NULL;
    IWICPalette *pPalette = NULL;

    UINT uiFrameCount = 0;

    HRESULT hr = CoCreateInstance(
        CLSID_WICImagingFactory,
        NULL,
        CLSCTX_INPROC_SERVER,
        IID_IWICImagingFactory,
        (LPVOID*)&pFactory
        );

    if (SUCCEEDED(hr))
    {
        hr = pFactory->CreateDecoderFromFilename(
                           L"test.gif",
                           NULL,
                           GENERIC_READ,
                           &pDecoder);
    }

    if (SUCCEEDED(hr))
    {
        hr = pDecoder->GetFrameCount(&uiFrameCount);
    }

    if (SUCCEEDED(hr) && (uiFrameCount > 0))
    {
        hr = pDecoder->GetFrame(0, &pBitmapFrameDecode);

        if (SUCCEEDED(hr))
        {
            hr = pFactory->CreatePalette(&pPalette);
        }

        if (SUCCEEDED(hr))
        {
            hr = pBitmapFrameDecode->CopyPalette(pPalette);
        }

        if (SUCCEEDED(hr))
        {
            UINT uiColorCount = 0;
            UINT uiActualColorCount = 0;
            WICColor *pColors = NULL;

            hr = pPalette->GetColorCount(&uiColorCount);

            if (SUCCEEDED(hr) && (uiColorCount > 0))
            {
                pColors = new WICColor[uiColorCount];

                if (pColors)
                {
                    hr = pPalette->GetColors(uiColorCount, pColors, &uiActualColorCount);

                    // Do something with the colors here...

                    delete[] pColors;
                }
                else
                {
                    hr = E_OUTOFMEMORY;
                }
            }
        }
    }

    if (pPalette)
    {
        pPalette->Release();
    }

    if (pBitmapFrameDecode)
    {
        pBitmapFrameDecode->Release();
    }

    if (pDecoder)
    {
        pDecoder->Release();
    }

    if (pFactory)
    {
        pFactory->Release();
    }

    return hr;

In this example code, WICColor is defined as a UINT32 value with this layout:

0xAARRGGBB

The wincodec.h header type-defines WICColor as UINT32.

Requirements

Requirement	Value
Minimum supported client	Windows XP with SP2, Windows Vista [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 [desktop apps \| UWP apps]
Target Platform	Windows
Header	wincodec.h

Share via