CreateDIBitmap function (wingdi.h)

Article
11/19/2022

The CreateDIBitmap function creates a compatible bitmap (DDB) from a DIB and, optionally, sets the bitmap bits.

Syntax

HBITMAP CreateDIBitmap(
  [in] HDC                    hdc,
  [in] const BITMAPINFOHEADER *pbmih,
  [in] DWORD                  flInit,
  [in] const VOID             *pjBits,
  [in] const BITMAPINFO       *pbmi,
  [in] UINT                   iUsage
);

Parameters

[in] hdc

A handle to a device context.

[in] pbmih

A pointer to a bitmap information header structure, BITMAPV5HEADER.

If fdwInit is CBM_INIT, the function uses the bitmap information header structure to obtain the desired width and height of the bitmap as well as other information. Note that a positive value for the height indicates a bottom-up DIB while a negative value for the height indicates a top-down DIB. Calling CreateDIBitmap with fdwInit as CBM_INIT is equivalent to calling the CreateCompatibleBitmap function to create a DDB in the format of the device and then calling the SetDIBits function to translate the DIB bits to the DDB.

[in] flInit

Specifies how the system initializes the bitmap bits. The following value is defined.

Value	Meaning
CBM_INIT	If this flag is set, the system uses the data pointed to by the lpbInit and lpbmi parameters to initialize the bitmap bits. If this flag is clear, the data pointed to by those parameters is not used.

If fdwInit is zero, the system does not initialize the bitmap bits.

[in] pjBits

A pointer to an array of bytes containing the initial bitmap data. The format of the data depends on the biBitCount member of the BITMAPINFO structure to which the lpbmi parameter points.

[in] pbmi

A pointer to a BITMAPINFO structure that describes the dimensions and color format of the array pointed to by the lpbInit parameter.

[in] iUsage

Specifies whether the bmiColors member of the BITMAPINFO structure was initialized and, if so, whether bmiColors contains explicit red, green, blue (RGB) values or palette indexes. The fuUsage parameter must be one of the following values.

Value	Meaning
DIB_PAL_COLORS	A color table is provided and consists of an array of 16-bit indexes into the logical palette of the device context into which the bitmap is to be selected.
DIB_RGB_COLORS	A color table is provided and contains literal RGB values.

Return value

If the function succeeds, the return value is a handle to the compatible bitmap.

If the function fails, the return value is NULL.

Remarks

The DDB that is created will be whatever bit depth your reference DC is. To create a bitmap that is of different bit depth, use CreateDIBSection.

For a device to reach optimal bitmap-drawing speed, specify fdwInit as CBM_INIT. Then, use the same color depth DIB as the video mode. When the video is running 4- or 8-bpp, use DIB_PAL_COLORS.

The CBM_CREATDIB flag for the fdwInit parameter is no longer supported.

When you no longer need the bitmap, call the DeleteObject function to delete it.

ICM: No color management is performed. The contents of the resulting bitmap are not color matched after the bitmap has been created.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	wingdi.h (include Windows.h)
Library	Gdi32.lib
DLL	Gdi32.dll