WinGCreateBitmap

Creates a WinGBitmap for the given WinGDC using the specified header information.

HBITMAP WinGCreateBitmap( HDC hWinGDC, BITMAPINFO far *pHeader, void far *far *ppBits )

Parameters

hWinGDC	Identifies the WinG device context.
pHeader	Points to a BITMAPINFO structure specifying the width, height, and color table for the new WinGBitmap.
ppBits	If not 0, points to a pointer to receive the address of the new WinGDC DIB surface.

Return Value

Returns a handle to the new WinGBitmap DIB surface or 0 if it is unsuccessful.

Comments

Currently, under Windows 3.1 and Win32s, WinGCreateBitmap will only create 8-bit-per-pixel surfaces.

If ppBits is 0, the address of the newly created bitmap will not be returned. WinGGetDIBPointer will return this information if you choose to ignore it here.

pHeader must point to enough memory to hold a BITMAPINFOHEADER and a complete color table of RGBQUAD entries. The biClrUsed field of the BITMAPINFOHEADER specifies the number of colors in the color table; if it is zero, the maximum number of colors according to biBitCount are used if biBitCount is less than 24. For example, if biBitCount is 8 and biClrUsed is 0, 256 palette entries are expected. See the BITMAPINFOHEADER description in the Windows 3.1 SDK Reference for more information.

When an application has finished using a WinGBitmap, it should select the bitmap out of its WinGDC and remove the bitmap by calling DeleteObject.

The pointer to the WinGBitmap DIB surface returned by WinGCreateBitmap must not be freed by the caller. The allocated memory will be freed by a call to DeleteObject.

WinGCreateBitmap uses pHeader and the subsequent color table to create the drawing surface. WinG ignores the biClrImportant, biXPelsPerMeter, biYPelsPerMeter, and biSizeImage fields. WinG expects biCompression to be BI_RGB.

If the biHeight field of the passed BITMAPINFOHEADER is negative, WinGCreateBitmap will create a top-down DIB as the bitmap surface. See the article on DIB Orientation for a discussion of top-down and bottom-up DIBs.

An HBITMAP can only be selected into one device context at a time, and a device context can only have a single HBITMAP selected in at a time.

WinGCreateBitmap is very similar to the new CreateDIBSection API. CreateDIBSection is a Win32 API available on Windows 95 and Windows NT 3.5.

Maximizing Performance

To create a WinGBitmap that will maximize WinGBitBlt performance, use WinGRecommendDIBFormat to fill in the entries of pHeader before calling WinGCreateBitmap, remembering to modify the height and width to suit your needs.

Larger WinGBitmaps take longer to blt to the screen. Also, if the screen DC is clipped, for example by an overlapping window or by a selected clip region, the WinGDC will take longer to blt to the screen.

Using an identity palette that exactly matches the WinGBitmap's color table will greatly increase performance.

In 16 bit code, the pointer to the bits can be accessed with 32 bit offsets in assembly, like all huge objects in Windows.

Example

The following code fragment shows how an application could create a WinGDC with an optimal 100x100 WinGBitmap selected for drawing, then delete it when it is no longer needed. Note that the WinGBitmap will initially have garbage in its color table--be sure to call WinGSetDIBColorTable before using the WinGDC.

The PALANIM sample (in the SAMPLES\PALANIM subdirectory of the WinG development kit) uses these routines, modified to create a 256x256 WinGDC, to allocate and free its drawing buffer.

Click Here to copy this code sample to the clipboard.

HBITMAP ghBitmapMonochrome = 0;

HDC Create100x100WinGDC(void)

{

HDC hWinGDC;

HBITMAP hBitmapNew;

struct {

BITMAPINFOHEADER InfoHeader;

RGBQUAD ColorTable[256];

} Info;

void far *pSurfaceBits;

// Set up an optimal bitmap

if (WinGRecommendDibFormat((BITMAPINFO far *)&Info) == FALSE)

return 0;

// Set the width and height of the DIB but preserve the

// sign of biHeight in case top-down DIBs are faster

Info.InfoHeader.biHeight *= 100;

Info.InfoHeader.biWidth = 100;

// Create a WinGDC and Bitmap, then select away

hWinGDC = WinGCreateDC();

if (hWinGDC)

{

hBitmapNew = WinGCreateBitmap(hWinGDC,

(BITMAPINFO far *)&Info, &pSurfaceBits);

if (hBitmapNew)

{

ghBitmapMonochrome = (HBITMAP)SelectObject(hWinGDC,

hBitmapNew);

}

else

{

DeleteDC(hWinGDC);

hWinGDC = 0;

}

return hWinGDC;

}

void Destroy100x100WinGDC(HDC hWinGDC)

{

HBITMAP hBitmapOld;

if (hWinGDC && ghBitmapMonochrome)

{

// Select the stock 1x1 monochrome bitmap back in

hBitmapOld = (HBITMAP)SelectObject(hWinGDC,

ghBitmapMonochrome);

DeleteObject(hBitmapOld);

DeleteDC(hWinGDC);

}