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
Points 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.
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, Windows 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 of a 1- by 1-pixel, monochrome bitmap.
When you no
longer need the bitmap, call the DeleteObjectY31AVA function to delete it.
See Also