Gdi::CreatePermanentDIBSection (Windows Embedded CE 6.0)

1/6/2010

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

Syntax

static HBITMAP WINAPI CreatePermanentDIBSection(
  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, the function uses the logical palette for this device context to initialize colors of the device-independent bitmap.

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

• iUsage
  [in] Unsigned integer that specifies the type of data contained in the bmiColors array member of the BITMAPINFO structure pointed to by pbmi, in either logical palette indexes or literal RGB values.

  The following table shows the possible values.

  Value	Description
  DIB_RGB_COLORS	The BITMAPINFO structure 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 bpp bitmap is used. When DIB_PAL_COLORS is used, the system ignores the bmiColors member of the BITMAPINFO structure and the dwOffset parameter. Set dwOffset to zero and the hSection parameter to NULL.

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

• hSection
  [in] Unsupported; set to NULL.

• dwOffset
  [in] Ignored.

Return Value

A handle to the newly created device-independent bitmap indicates success. When the method succeeds, ppvBits points to the bit values for the bitmap.

NULL indicates failure. When the method fails, ppvBits is NULL.

To get extended error information, call GetLastError.

Remarks

As noted above, if hSection is 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 Gdi::DeleteObject_I method.

If hSection is not NULL, you must close the hSection memory handle yourself after calling Gdi::DeleteObject_I to delete the bitmap.

The BITMAPINFO structure must include a color table if the images are palettized (usually 1, 2, 4, and 8 bpp formats).

For 16 bpp or 32 bpp nonpalettized images, the color table must be three entries long; the entries must 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_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 Embedded CE does not support 332 bitfields devices.

Requirements

See Also

Reference

Gdi
CreateDIBSection
BITMAPINFO
BITMAPINFOHEADER