Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function creates a bitmap with the specified width, height, and bit depth.

Syntax 

HBITMAP CreateBitmap(
  int 
nWidth, 
  int 
nHeight, 
  UINT 
cPlanes, 
  UINT 
cBitsPerPel, 
  CONST VOID* 
lpvBits
);

Parameters

nWidth

[in] Specifies the bitmap width, in pixels.

nHeight

[in] Specifies the bitmap height, in pixels.

cPlanes

[in] Specifies the number of color planes used by the device.

The value of this parameter must be 1.

cBitsPerPel

[in] Specifies the number of bits required to identify the color of a single pixel.

lpvBits

[in] Long void pointer to an array of color data used to set the colors in a rectangle of pixels.

Each scan line in the rectangle must be word aligned (scan lines that are not word aligned must be padded with zeros).

If this parameter is NULL, the new bitmap is undefined.

Return Value

A handle to a bitmap indicates success.

NULL indicates failure.

To get extended error information, call GetLastError.

Code Example

The following code example uses CreateBitmapto make a copy of a bitmap.

Note:
To make the following code example easier to read, error checking is not included. This code example should not be used in a release configuration unless it has been modified to include secure error handling.
Copy Code 
HBITMAP CopyBitmap( HBITMAP hbm) {
	HDC hdcSrc = CreateCompatibleDC(NULL);
	HDC hdcDst = CreateCompatibleDC(NULL);
	HBITMAP hbmOld, hbmOld2, hbmNew;
	BITMAP bm;
	GetObject(hbm, sizeof(bm), &bm);
	hbmOld = SelectObject(hdcSrc, hbm);
	hbmNew = CreateBitmap( bm.bmWidth, bm.bmHeight, bm.bmPlanes,
bm.bmBitsPixel,
			NULL);
	hbmOld2 = SelectObject(hdcDst, hbmNew);
	BitBlt(hdcDst, 0, 0, bm.bmWidth, bm.bmHeight, hdcSrc, 0, 0,
SRCCOPY);
	SelectObject(hdcSrc, hbmOld);
	DeleteDC(hdcSrc);
	DeleteDC(hdcDst);
	return hbmNew;
}

Remarks

After a bitmap is created, it can be selected into a device context by calling the SelectObjectfunction.

While the CreateBitmapfunction can be used to create color bitmaps, for performance reasons applications should use CreateBitmapto create monochrome bitmaps and CreateCompatibleBitmapto create color bitmaps.

When a color bitmap returned from CreateBitmapis selected into a device context, the system must ensure that the bitmap matches the format of the device context it is being selected into.

Because CreateCompatibleBitmaptakes a device context, it returns a bitmap that has the same format as the specified device context. Because of this, subsequent calls to SelectObjectare faster than with a color bitmap returned from CreateBitmap.

If the bitmap is monochrome, zeros represent the foreground color and ones represent the background color for the destination device context.

If an application sets the nWidthor nHeightparameters to zero, CreateBitmapreturns the handle to a 1- by 1-pixel, monochrome bitmap.

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

Requirements

Header windows.h
Library coredll.lib
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also