CreateDIBSection

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This function creates a device-independent bitmap (DIB) that applications can write to directly. The function returns a handle to the bitmap.

HBITMAP
CreateDIBSection( HDC
hdc
, const
BITMAPINFO
*
pbmi
, UINT
iUsage
, void
*
ppvBits
, HANDLE
hSection
, DWORD
dwOffset
);

Parameters

hdc

[in] Handle to a device context. If the value of iUsageis DIB_PAL_COLORS, the function uses this device context's logical palette to initialize the device-independent bitmap's colors.

pbmi

[in] Pointer to a BITMAPINFOstructure that specifies various attributes of the device-independent bitmap, including the bitmap's dimensions and colors.

iUsage

[in] Specifies the type of data contained in the bmiColorsarray member of the BITMAPINFOstructure pointed to by pbmi(either logical palette indexes or literal RGB values). The following values are defined.

Value	Description
DIB_RGB_COLORS	The BITMAPINFOstructure contains an array of literal RGB values. Specify this value except when an 8 bpp bitmap is used.
DIB_PAL_COLORS	Specify this value when an 8 bbp bitmap is used. When DIB_PAL_COLORS is used, the system ignores the bmiColorsmember of the BITMAPINFOstructure and the dwOffsetparameter. Set dwOffsetto zero and the hSectionparameter to NULL.

ppvBits

[in] Pointer to a variable that receives a pointer to the location of the device-independent bitmap's bit values.

hSection

[in] Unsupported; set to NULL.

dwOffset

[in] Ignored.

Return Values

A handle to the newly created device-independent bitmap indicates success, and * ppvBitspoints to the bitmap's bit values.

NULL indicates failure, and * ppvBitsis NULL.

To get extended error information, call GetLastError.

Remarks

As noted above, if hSectionis NULL, the system allocates memory for the device-independent bitmap. The system closes the handle to that memory when you later delete the device-independent bitmap by calling the DeleteObjectfunction. If hSectionis not NULL, you must close the hSectionmemory handle yourself after calling DeleteObjectto delete the bitmap.

In Windows CE versions 2.0 and later, the BITMAPINFOstructure must include a color table if the images are palettized (usually 1,2,4, and 8 bpp formats). For 16bpp or 32bpp non-palettized images, the color table must be three entries long; the entries must specify the values of the red, green, and blue bitmasks. Also, the biCompressionfield in the BITMAPINFOHEADERstructure should be set to BI_BITFIELDS. BI_RBG is not supported for these bit depths. GDI ignores the color table for 24 bpp images; their pixels must be stored in Blue-Green-Red (BGR) format. Windows CE does not support 332 bitfields devices.

In Windows CE versions 1.0 and 1.01, the BITMAPINFOstructure pointed to by the pbmiparameter must specify 1 or 2 bits per pixel.

Requirements

Runs on	Versions	Defined in	Include	Link to
Windows CE OS	1.0 and later	Wingdi.h		Mgdi_c.lib, Mgdibsec.lib

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.