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:

• 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

Refer to the "Error Explanations" section of the Presentation Manager Programming Reference for further explanation.

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.