[The feature associated with this page, DrawDib, is a legacy feature. It has been superseded by MediaComposition class. MediaComposition class has been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaComposition class instead of DrawDib, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The DrawDib functions require that an application respond to two palette-oriented messages: WM_QUERYNEWPALETTE and WM_PALETTECHANGED. If your application is not palette-aware, you will need to add a handler for each of these messages. For more information about processing the WM_QUERYNEWPALETTE and WM_PALETTECHANGED messages, see Adding Palette Message Handlers.

You can realize the current DrawDib palette to the DC by using the DrawDibRealize function. You should realize the palette in response to the WM_QUERYNEWPALETTE or WM_PALETTECHANGED message, or when you prepare to display an image sequence by using the DrawDibDraw function.

You can draw an image mapped to another palette by using the DrawDibSetPalette function. This function forces the DrawDib DC to use the specified palette, which can affect the image quality. For example, an application that is palette-aware might have realized a palette and needs to prevent DrawDib from realizing its own palette. The application can use DrawDibSetPalette to notify DrawDib of the palette to use.

You can obtain a handle of the current foreground palette by using the DrawDibGetPalette function. If your application uses the current foreground palette, it does not have exclusive use of the palette and another application can invalidate the palette handle. Your application should not free the palette when you finish using it. Freeing the palette could invalidate the palette handle for another application.

You can prepare DrawDib to receive new color values for its palette by using the DrawDibChangePalette function. In the code following DrawDibChangePalette, you assign new values for the palette color table. If the DDF_ANIMATE flag is not set in the DrawDib DC when you call DrawDibChangePalette, you can enact the palette changes by using DrawDibRealize to realize the palette. You can then use DrawDibDraw to redraw the image. If the DDF_ANIMATE flag is set in the DrawDib DC, you can animate the palette and the colors of the displayed bitmap by using DrawDibDraw or DrawDibRealize. You can update the DDF_ANIMATE flag by using the DrawDibEnd and DrawDibBegin functions.


If you free the DrawDib palette while it is selected by a DC, a graphics device interface (GDI) error can result when the DC uses the palette. Instead, your application should use DrawDibSetPalette to change the DrawDib DC to use the default palette or another palette.


The DrawDibEnd, DrawDibClose, and DrawDibBegin functions can free the DrawDib palette. However, these functions should be used only when the palette has not been selected by the DC. The DrawDibDraw function can also free the palette when it uses the same DrawDib DC, but specifies different drawing parameters (lpbi, dxDst, dyDst, dxSrc, or dySrc) or a different format.

Image Rendering