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.
A version of this page is also available for
4/8/2010

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

Syntax 

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 bit masks or a palette depending on the value of the biCompressionmember of the structure. These values are used when rendering the bitmap.

This value can be specified along with any bit count.

DIB_PAL_COLORS

The BITMAPINFO.bmiColorsarray is ignored, and the destination palette is used when rendering the bitmap.

This value can only be specified with an 8-bpp bitmap.
ppvBits

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

hSection

[in] Set this parameter to NULL.

dwOffset

[in] Ignored.

Return Value

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

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.

In Windows CE 2.0 and later, the BITMAPINFOstructure must include a color table if the images are palletized (usually 1-, 2-, 4-, and 8-bpp formats).

For 16-bpp or 32-bpp non-palletized images, the color table must be three entries long; the entries must specify the values of the red, green, and blue bitmasks.

Also, the biCompressionmember in the BITMAPINFOHEADERstructure should be set to BI_BITFIELDS. BI_RGB 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 Embedded CE does not support 332 bitfields devices.

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

The memory of a DIBSECTION is DWORD-aligned by row.

Requirements

Header windows.h
Library coredll.lib
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also