CreateDIBSection (Compact 2013)

3/28/2014

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 iUsage is DIB_PAL_COLORS, this handle must be valid. In this case, the function initializes the colors of the device-independent bitmap by using this device context's logical palette.

  If the value of iUsage is DIB_RGB_COLORs, this handle is not required. In this case, the function initializes the colors by using an array of RGBQUAD structures.

  This value can be NULL if iUsage is DIB_RGB_COLORS.

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

• iUsage
  [in] Specifies the type of color data contained in the bmiColors array member of the BITMAPINFO structure pointed to by pbmi.

  Set this value to one of the following:

  Value	Description
  DIB_RGB_COLORS	Indicates that the BITMAPINFO structure you specified in pbmi contains a color table that consists of literal RGB values. This is an array of bit masks or a palette, depending on the value of the biCompression member of the structure. These values are used when rendering the bitmap. Use this value for a bitmap with a bit count greater than 8 bpp.
  DIB_PAL_COLORS	Indicates that the BITMAPINFO structure you specified in pbmi contains a color table that consists of an array of 16-bit indices into the logical palette of the currently-selected device context. The destination palette is used when rendering the bitmap. Use this value only for a bitmap with a bit count of 8-bpp or less.

• ppvBits
  [in] Address of 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. Set this parameter to 0.

Return Value

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

NULL indicates failure, and *ppvBits is 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 DeleteObject function.

For palletized color-display devices (usually 1-bpp, 2-bpp, 4-bpp, and 8-bpp formats), this function uses the color palette coded directly into their display card. The color table in the BITMAPINFO structure contains an array of 16-bit indices into the logical palette of the currently-selected device context.

For 16-bpp or 32-bpp non-palletized devices, the BITMAPINFO structure must contain color table entries that specify the values of the red, green, and blue bitmasks. Also, the biCompression member in the BITMAPINFOHEADER structure 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 Compact does not support devices that use 332 bit fields.

Requirements

See Also

Reference

GDI Functions
DeleteObject
GetObject
SelectObject
BITMAPINFO
BITMAPINFOHEADER