Export (0) Print
Expand All

CreateBitmap function

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

Syntax


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

Parameters

nWidth [in]

The bitmap width, in pixels.

nHeight [in]

The bitmap height, in pixels.

cPlanes [in]

The number of color planes used by the device.

cBitsPerPel [in]

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

lpvBits [in]

A 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 contents of the new bitmap is undefined.

Return value

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

If the function fails, the return value is NULL.

This function can return the following value.

Return codeDescription
ERROR_INVALID_BITMAP

The calculated size of the bitmap is less than zero.

 

Remarks

The CreateBitmap function creates a device-dependent bitmap.

After a bitmap is created, it can be selected into a device context by calling the SelectObject function. However, the bitmap can only be selected into a device context if the bitmap and the DC have the same format.

The CreateBitmap function can be used to create color bitmaps. However, for performance reasons applications should use CreateBitmap to create monochrome bitmaps and CreateCompatibleBitmap to create color bitmaps. Whenever a color bitmap returned from CreateBitmap is selected into a device context, the system checks that the bitmap matches the format of the device context it is being selected into. Because CreateCompatibleBitmap takes a device context, it returns a bitmap that has the same format as the specified device context. Thus, subsequent calls to SelectObject are faster with a color bitmap from CreateCompatibleBitmap 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.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Wingdi.h (include Windows.h)

Library

Gdi32.lib

DLL

Gdi32.dll

See also

Bitmaps Overview
Bitmap Functions
CreateBitmapIndirect
CreateCompatibleBitmap
CreateDIBitmap
DeleteObject
GetBitmapBits
SelectObject
SetBitmapBits

 

 

Community Additions

ADD
Show:
© 2014 Microsoft