CreateDIBitmap

3.0

The CreateDIBitmap function creates a device-specific memory bitmap from a device-independent bitmap (DIB) specification and optionally sets bits in the bitmap.

Parameters

hdc

Identifies the device context.

lpbmih

Points to a BITMAPINFOHEADER structure that describes the size and format of the device-independent bitmap. The BITMAPINFOHEADER structure has the following form:

typedef struct tagBITMAPINFOHEADER {    /* bmih */
    DWORD   biSize;
    LONG    biWidth;
    LONG    biHeight;
    WORD    biPlanes;
    WORD    biBitCount;
    DWORD   biCompression;
    DWORD   biSizeImage;
    LONG    biXPelsPerMeter;
    LONG    biYPelsPerMeter;
    DWORD   biClrUsed;
    DWORD   biClrImportant;
} BITMAPINFOHEADER;

For a full description of this structure, see the Microsoft Windows Programmer's Reference, Volume 3.

dwInit

Specifies whether the memory bitmap is initialized. If this value is CBM_INIT, the function initializes the bitmap with the bits specified by the lpvBits and lpbmi parameters.

lpvBits

Points to a byte array that contains the initial bitmap values. The format of the bitmap values depends on the biBitCount member of the BITMAPINFOHEADER structure identified by the lpbmi parameter.

lpbmi

Points to a BITMAPINFO structure that describes the dimensions and color format of the lpvBits parameter. The BITMAPINFO structure contains a BITMAPINFOHEADER structure and an array of RGBQUAD structures specifying the colors in the bitmap. The BITMAPINFO structure has the following form:

typedef struct tagBITMAPINFO {  /* bmi */
    BITMAPINFOHEADER    bmiHeader;
    RGBQUAD             bmiColors[1];
} BITMAPINFO;

For a full description of the BITMAPINFO and RGBQUAD structures, see the Microsoft Windows Programmer's Reference, Volume 3.

fnColorUse

Specifies whether the bmiColors member of the BITMAPINFO structure contains explicit red, green, blue (RGB) values or indices into the currently realized logical palette. The fnColorUse parameter must be one of the following values:

Return Value

The return value is the handle of the bitmap if the function is successful. Otherwise, it is NULL.

When it has finished using a bitmap created by CreateDIBitmap, an application should select the bitmap out of the device context and then remove the bitmap by using the DeleteObject function.

Example

The following example initializes an array of bits and an array of RGBQUAD structures, allocates memory for the bitmap header and color table, fills in the required members of a BITMAPINFOHEADER structure, and calls the CreateDIBitmap function to create a handle of the bitmap:

HANDLE hloc;
PBITMAPINFO pbmi;
HBITMAP hbm;

BYTE aBits[] = { 0x00, 0x00, 0x00, 0x00,    /* bottom row */
                 0x01, 0x12, 0x22, 0x11,
                 0x01, 0x12, 0x22, 0x11,
                 0x02, 0x20, 0x00, 0x22,
                 0x02, 0x20, 0x20, 0x22,
                 0x02, 0x20, 0x00, 0x22,
                 0x01, 0x12, 0x22, 0x11,
                 0x01, 0x12, 0x22, 0x11 };  /* top row    */

RGBQUAD argbq[] = {{ 255, 0, 0, 0 },        /* blue       */
                   { 0, 255, 0, 0 },        /* green      */
                   { 0, 0, 255, 0 }};       /* red        */

hloc = LocalAlloc(LMEM_ZEROINIT | LMEM_MOVEABLE,
    sizeof(BITMAPINFOHEADER) + (sizeof(RGBQUAD) * 16));
pbmi = (PBITMAPINFO) LocalLock(hloc);


pbmi->bmiHeader.biSize = sizeof(BITMAPINFOHEADER);
pbmi->bmiHeader.biWidth = 8;
pbmi->bmiHeader.biHeight = 8;
pbmi->bmiHeader.biPlanes = 1;
pbmi->bmiHeader.biBitCount = 4;
pbmi->bmiHeader.biCompression = BI_RGB;

memcpy(pbmi->bmiColors, argbq, sizeof(RGBQUAD) * 3);

hbm = CreateDIBitmap(hdcLocal, (BITMAPINFOHEADER FAR*) pbmi, CBM_INIT,
    aBits, pbmi, DIB_RGB_COLORS);
LocalFree(hloc);
    .
    . /* Use the bitmap handle. */
    .
DeleteObject(hbm);

See Also

CreateBitmap, CreateBitmapIndirect, CreateCompatibleBitmap, CreateDiscardableBitmap, DeleteObject