The CreateDIBSection function creates a device-independent bitmap (DIB) that applications can write to directly. The function gives you a pointer to the location of the bitmap's bit values. You can supply a handle to a file mapping object that the function will use to create the bitmap, or you can let the system allocate the memory for the bitmap.
HBITMAP CreateDIBSection(
HDC hdc, // handle to device context
CONST BITMAPINFO *pbmi,
// pointer to structure containing bitmap size,
// format, and color data
UINT iUsage, // color data type indicator: RGB values or
// palette indexes
VOID *ppvBits, // pointer to variable to receive a pointer to
// the bitmap's bit values
HANDLE hSection, // optional handle to a file mapping object
DWORD dwOffset // offset to the bitmap bit values within the
// file mapping object
);
| Value | Meaning |
|---|---|
| DIB_PAL_COLORS | The bmiColors member is an array of 16-bit indexes into the logical palette of the device context specified by hdc. |
| DIB_RGB_COLORS | The BITMAPINFO structure contains an array of literal RGB values. |
If hSection is not NULL, it must be a handle to a file mapping object created by calling the CreateFileMapping function with the PAGE_READWRITE or PAGE_WRITECOPY flag. Read-only DIB sections are not supported. Handles created by other means will cause CreateDIBSection to fail.
If hSection is not NULL, the CreateDIBSection function locates the bitmap's bit values at offset dwOffset in the file mapping object referred to by hSection. An application can later retrieve the hSection handle by calling the GetObject function with the HBITMAP returned by CreateDIBSection.
If hSection is NULL, the system allocates memory for the device-independent bitmap. In this case, the CreateDIBSection function ignores the dwOffset parameter. An application cannot later obtain a handle to this memory. The dshSection member of the DIBSECTION structure filled in by calling the GetObject function will be NULL.
If the function succeeds, the return value is a handle to the newly created device-independent bitmap, and *ppvBits points to the bitmap's bit values.
If the function fails, the return value is NULL, and *ppvBits is NULL.
Windows NT: To get extended error information, call GetLastError.
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 DeleteObject function. If hSection is not NULL, you must close the hSection memory handle yourself after calling DeleteObject to delete the bitmap.
Windows NT: You need to guarantee that the GDI subsystem has completed any drawing to a bitmap created by CreateDIBSection before you draw to the bitmap yourself. Access to the bitmap must be synchronized. Do this by calling the GdiFlush function. This applies to any use of the pointer to the bitmap's bit values, including passing the pointer in calls to functions such as SetDIBits.
ICM: If the bmiHeader member of BITMAPINFO (pointed to by pbmi) does not contain BITMAPV4HEADER or BITMAPV5HEADER, no color management is done. Otherwise, color management is enabled, and the specified color space is associated with the bitmap.
Windows CE: Set the iUsage parameter to DIB_RGB_COLORS, except when an 8 bpp bitmap is used, in which case you set iUsage to DIB_PAL_COLORS. However, if DIB_PAL_COLORS is used, Windows CE ignores the values in the bmiColors array member of the BITMAPINFO structure. In addition, you should set the hSection parameter to NULL. Windows CE ignores the dwOffset parameter; set it to zero.
In Windows CE version 1.0, the BITMAPINFO structure pointed to by the pbmi parameter must specify 1 or 2 bits per pixel.
In Windows CE version 2.0, 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 non-palettized images, the color table must be three entries long; the entries must specify the values of the red, green, and blue bitmasks. GDI ignores the color table for 24 bpp images; their pixels must be stored in Blue-Green-Red (BGR) format.
Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.
Bitmaps Overview, Bitmap Functions, BITMAPINFO, CreateFileMapping, DeleteObject, DIBSECTION, GetDIBColorTable, GetObject, GdiFlush, HBITMAP, SetDIBits, SetDIBColorTable