CreateCompatibleBitmap

2.x

HBITMAP CreateCompatibleBitmap(hdc, nWidth, nHeight)
HDC hdc;	/* handle of device context	*/
int nWidth;	/* bitmap width, */
int nHeight;	/* bitmap height, */

The CreateCompatibleBitmap function creates a bitmap that is compatible with the given device.

Parameters

hdc

Identifies the device context.

nWidth

Specifies the width, in bits, of the bitmap.

nHeight

Specifies the height, in bits, of the bitmap.

Return Value

The return value is the handle of the bitmap if the function is successful. Otherwise, it is NULL.

Comments

The bitmap created by the CreateCompatibleBitmap function has the same number of color planes or the same bits-per-pixel format as the given device. It can be selected as the current bitmap for any memory device that is compatible with the one identified by hdc.

If hdc identifies a memory device context, the bitmap returned has the same format as the currently selected bitmap in that device context. A memory device context is a memory object that represents a screen surface. It can be used to prepare images in memory before copying them to the screen surface of the compatible device.

When a memory device context is created, the graphics device interface (GDI) automatically selects a monochrome stock bitmap for it.

Since a color memory device context can have either color or monochrome bitmaps selected, the format of the bitmap returned by the CreateCompatibleBitmap function is not always the same; however, the format of a compatible bitmap for a non–memory device context is always in the format of the device.

When it has finished using a bitmap created by CreateCompatibleBitmap, an application should select the bitmap out of the device context and then remove the bitmap by using the DeleteObject function.

Example

The following example shows a function named DuplicateBitmap that accepts the handle of a bitmap, duplicates the bitmap, and returns a handle of the duplicate. This function uses the CreateCompatibleDC function to create source and destination device contexts and then uses the GetObject function to retrieve the dimensions of the source bitmap. The CreateCompatibleBitmap function uses these dimensions to create a new bitmap. When each bitmap has been selected into a device context, the BitBlt function copies the bits from the source bitmap to the new bitmap. (Although an application could use the GetDIBits and SetDIBits functions to duplicate a bitmap, the method illustrated in this example is much faster.)

HBITMAP PASCAL DuplicateBitmap(HBITMAP hbmpSrc)
{
    HBITMAP hbmpOldSrc, hbmpOldDest, hbmpNew;
    HDC     hdcSrc, hdcDest;
    BITMAP  bmp;

    hdcSrc = CreateCompatibleDC(NULL);
    hdcDest = CreateCompatibleDC(hdcSrc);

    GetObject(hbmpSrc, sizeof(BITMAP), &bmp);

    hbmpOldSrc = SelectObject(hdcSrc, hbmpSrc);

    hbmpNew = CreateCompatibleBitmap(hdcSrc, bmp.bmWidth,
        bmp.bmHeight);

    hbmpOldDest = SelectObject(hdcDest, hbmpNew);

    BitBlt(hdcDest, 0, 0, bmp.bmWidth, bmp.bmHeight, hdcSrc, 0, 0,
        SRCCOPY);

    SelectObject(hdcDest, hbmpOldDest);
    SelectObject(hdcSrc, hbmpOldSrc);

    DeleteDC(hdcDest);
    DeleteDC(hdcSrc);

    return hbmpNew;
}