GreCreateBitmap

GreCreateBitmap creates a bit map and returns its handle.

This function is supported by the graphics engine.

Syntax
GreCreateBitmap(hdc, pInfoHd, flUsage, pBitmap, paInfo, pInstance, lFunction)

Parameters

 * hdc (HDC) - input:Device context handle.
 * pInfoHd (PBITMAPINFOHEADER) - input:Pointer to BITMAPINFOHEADER or BITMAPINFOHEADER2 structure for new bit map.
 * flUsage (ULONG) - input:Additional information, used when creating a new bit map. The only defined flag is:
 * CBM_INIT - When set, the pBitmap and paInfo parameters are used to initialize the newly created bit map. If this flag is not set, the bit map initialization is device dependent. It is assumed that sufficient data is supplied to initialize the whole bit map.
 * Other flags (16 - 31) can be used for special purposes known to be supported by a particular presentation driver.


 * pBitmap (PBYTE) - input:Pointer to bit-map initialization data, starting on a DWORD-aligned address. This data is stored in the order that the coordinates appear on a display screen, that is, the pel in the lower-left corner is the first in the bit map. Pels are scanned to the right and upward from that position. The bits of the first pel are stored beginning with the most significant bits of the first byte. The data for pels in each scan line is packed together tightly. However, all scan lines are padded at the end so that each one begins on a ULONG boundary. That is, 3 bytes of pel data will hold one 24-bit pel, three 8-bit pels, six 4-bit pels, or twenty-four 1-bit pels. If those 3 bytes are the only pel data for that scan line, 1 more byte of zeros would be required to pad the line to a ULONG boundary.
 * paInfo (PBITMAPINFO) - input:Pointer to BITMAPINFO or BITMAPINFO2 structure for initialization data.
 * pInstance (PVOID) - input:Pointer to instance data.
 * lFunction (ULONG) - input:High-order WORD=flags; low-order WORD=NGreCreateBitmap.

Return Code

 * rc (HBITMAP) - returns: Return codes.
 * On completion, the handling routine must return the handle of the bit map (hbm), or 0 if an error occurs.

Possible Errors Detected: Error codes posted by the engine for this function include: Refer to the "Error Explanations" section of the Presentation Manager Programming Reference for further explanation.
 * PMERR_DEV_FUNC_NOT_INSTALLED
 * PMERR_HDC_BUSY
 * PMERR_INSUFFICIENT_MEMORY
 * PMERR_INV_BITMAP_DIMENSION
 * PMERR_INV_HDC
 * PMERR_INV_INFO_TABLE
 * PMERR_INV_LENGTH_OR_COUNT
 * PMERR_INV_SCAN_START
 * PMERR_INV_USAGE_PARM

Remarks
Bit-map size is limited by available memory; the maximum width and height are 64KB. The following standard bit-maps formats are normally used: Bitcount    Planes 1          1     4           1     8           1    24           1 Display drivers must support at least 4 bits per pel. For other devices, the presentation driver must be able to create and accept any of the standard formats even though they might not use the color information.

The DC handle supplied to this function must never be NULL. Bit maps always belong to some device. The bit map is created on the device specified and can be selected to a different device later as the engine can handle the transfer of bits from one device to another. When the value specified for cPlanes or cBitcount is incompatible with the physical device specified by the DC handle, an error is raised.