Gdi::CreateBitmap_I

  • Article

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

static WINGDIAPI HBITMAP WINAPI CreateBitmap_I(
  int nWidth, 
  int nHeight, 
  UINT cPlanes, 
  UINT cBitsPerPel, 
  CONST VOID* lpvBits
);

Parameters

  • nWidth
    [in] Integer that specifies the bitmap width, in pixels.
  • nHeight
    [in] Integer that specifies the bitmap height, in pixels.
  • cPlanes
    [in] Unsigned integer that specifies the number of color planes used by the device. The value of this parameter must be 1.
  • cBitsPerPel
    [in] Unsigned integer that 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 Values

A handle to a bitmap indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

This method is an internal version of the CreateBitmap function.

After you create a bitmap, you can select the bitmap into a device context by calling the Gdi::SelectObject_I method.

While applications can use the Gdi::CreateBitmap_I method to create color bitmaps, applications should use Gdi::CreateBitmap_I to create monochrome bitmaps and Gdi::CreateCompatibleBitmap_I to create color bitmaps, for performance reasons. When you select a color bitmap returned from Gdi::CreateBitmap_I into a device context, the system must ensure that the bitmap matches the format of the device context into which you select the bitmap. Because Gdi::CreateCompatibleBitmap_I takes a device context, Gdi::CreateCompatibleBitmap_I returns a bitmap that has the same format as the specified device context. Because of these differences, subsequent calls to Gdi::SelectObject_I are faster than with a color bitmap returned from Gdi::CreateBitmap_I.

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, Gdi::CreateBitmap_I returns the handle to a 1 x 1 pixel monochrome bitmap.

When you no longer need the bitmap, call the Gdi::DeleteObject_I method to delete the bitmap.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Gdi.hpp.

See Also

CreateBitmap | Gdi::CreateCompatibleBitmap_I | Gdi::DeleteObject_I | Gdi::SelectObject_I

Last updated on Wednesday, April 13, 2005

© 2005 Microsoft Corporation. All rights reserved.