CreateBitmap

The CreateBitmap function creates a bitmap with the specified width, height, and color format (color planes and bits per pixel).

HBITMAP CreateBitmap(
  int nWidth,         // bitmap width, in pixels
  int nHeight,        // bitmap height, in pixels
  UINT cPlanes,       // number of color planes used by device
  UINT cBitsPerPel,   // number of bits required to identify a color
  CONST VOID *lpvBits // pointer to array containing color data
);
 

Parameters

nWidth

Specifies the bitmap width, in pixels.

nHeight

Specifies the bitmap height, in pixels.

cPlanes

Specifies the number of color planes used by the device.

cBitsPerPel

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

lpvBits

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 Values

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

If the function fails, the return value is NULL.

Windows NT: To get extended error information, call GetLastError.

Remarks

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

While the CreateBitmap function can be used to create color bitmaps, for performance reasons applications should use CreateBitmap to create monochrome bitmaps and CreateCompatibleBitmap to create color bitmaps. When a color bitmap returned from CreateBitmap is selected into a device context, the system must ensure that the bitmap matches the format of the device context it is being selected into. Since CreateCompatibleBitmap takes a device context, it returns a bitmap that has the same format as the specified device context. Because of this, subsequent calls to SelectObject are 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 nWidth or nHeight parameters to zero, CreateBitmap returns the handle to a 1- by 1-pixel, monochrome bitmap.

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

Windows CE: The cPlanes parameter must be 1.

QuickInfo

  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.

See Also

Bitmaps Overview, Bitmap Functions, CreateBitmapIndirect, CreateCompatibleBitmap, CreateDIBitmap, DeleteObject, GetBitmapBits, SelectObject, SetBitmapBits