Initializes the format converter.
HRESULT Initialize( IWICBitmapSource *pISource, REFWICPixelFormatGUID dstFormat, WICBitmapDitherType dither, IWICPalette *pIPalette, double alphaThresholdPercent, WICBitmapPaletteType paletteTranslate );
The input bitmap to convert
The destination pixel format GUID.
The WICBitmapDitherType used for conversion.
The palette to use for conversion.
The alpha threshold to use for conversion.
The palette translation type to use for conversion.
If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
If you do not have a predefined palette, you must first create one. Use InitializeFromBitmap to create the palette object, then pass it in along with your other parameters.
dither, pIPalette, alphaThresholdPercent, and paletteTranslate are used to mitigate color loss when converting to a reduced bit-depth format. For conversions that do not need these settings, the following parameters values should be used: dither set to WICBitmapDitherTypeNone, pIPalette set to NULL, alphaThresholdPercent set to 0.0f, and paletteTranslate set to WICBitmapPaletteTypeCustom.
The basic algorithm involved when using an ordered dither requires a fixed palette, found in the WICBitmapPaletteType enumeration, in a specific order. Often, the actual palette provided for the output may have a different ordering or some slight variation in the actual colors. This is the case when using the Microsoft Windows palette which has slight differences among versions of Windows. To provide for this, a palette and a palette translation are given to the format converter. The pIPalette is the actual destination palette to be used and the paletteTranslate is a fixed palette. Once the conversion is complete, the colors are mapped from the fixed palette to the actual colors in pIPalette using a nearest color matching algorithm.
If colors in <i>pIPalette</i> do not closely match those in <i>paletteTranslate</i>, the mapping may produce undesireable results.
WICBitmapDitherTypeOrdered4x4 can be useful in format conversions from 8-bit formats to 5- or 6-bit formats as there is no way to accurately convert color data.
WICBitmapDitherTypeErrorDiffusion selects the error diffusion algorithm and may be used with any palette. If an arbitrary palette is provided, WICBitmapPaletteCustom should be passed in as the paletteTranslate. Error diffusion often provides superior results compared to the ordered dithering algorithms especially when combined with the optimized palette generation functionality on the IWICPalette.
When converting a bitmap which has an alpha channel, such as a Portable Network Graphics (PNG), to 8bpp, the alpha channel is normally ignored. Any pixels which were transparent in the original bitmap show up as black in the final output because both transparent and black have pixel values of zero in the respective formats.
Some 8bpp content can contains an alpha color; for instance, the Graphics Interchange Format (GIF) format allows for a single palette entry to be used as a transparent color. For this type of content, alphaThresholdPercent specifies what percentage of transparency should map to the transparent color. Because the alpha value is directly proportional to the opacity (not transparency) of a pixel, the alphaThresholdPercent indicates what level of opacity is mapped to the fully transparent color. For instance, 9.8% implies that any pixel with an alpha value of less than 25 will be mapped to the transparent color. A value of 100% maps all pixels which are not fully opaque to the transparent color. Note that the palette should provide a transparent color. If it does not, the 'transparent' color will be the one closest to zero - often black.
The following example converts an image frame to a 32bppPBGRA format with no dithering or alpha threshold. Direct2D requires bitmap sources to be in the a 32bppPBGRA format for rendering. For a full sample demonstrating the use of the IWICFormatConverter, see the WIC Image Viewer Using Direct2D Sample.
HRESULT hr = S_OK;
|Minimum supported client||Windows XP with SP2, Windows Vista [desktop apps | UWP apps]|
|Minimum supported server||Windows Server 2008 [desktop apps | UWP apps]|