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.

Pointer to either a BITMAPINFOHEADER structure:

cbFix

Length in bytes of this structure

cx

Bit-map width

cy

Bit-map height

cPlanes

Number of color planes, 1 if standard format

cBitCount

Number of adjacent color bits per pel

Each plane has ((cx*cBitCount+31)/32*4*cy) bytes.

Or pointer to a BITMAPINFOHEADER2 structure:

cbFix

Length in bytes of this structure.

cx

Bit-map width.

cy

Bit-map height.

cPlanes

Number of color planes, 1 if standard format.

cBitCount

Number of adjacent color bits per pel.

ulCompression

Compression scheme used to store the bit map:

BCA_UNCOMP

Bit map is uncompressed (the only valid value).

cbImage

Length of bit-map storage data in bytes. If the bit map is uncompressed, 0 (default) can be specified for this.

cxResolution

Horizontal component of the resolution of the target device; that is, the resolution of the device for which the bit map is intended in the units specified by usUnits. This information enables an application to select from a resource group the bit map that best matches the characteristics of the current output device.

cyResolution

Vertical component of the resolution of the target device; that is, the resolution of the device for which the bit map is intended in the units specified by usUnits. This information enables an application to select from a resource group the bit map that best matches the characteristics of the current output device.

cclrUsed

The number of color indexes from the color table that are used by the bit map. If it is 0 (default), all the indexes are used. If it is nonzero, only the first cclrUsed entries in the table are accessed by the system; further entries can be omitted.

For standard formats with a cBitCount of 1, 4, or 8 (and cPlanes=1), any indexes beyond cclrUsed are not valid. For example, a bit map with 64 colors can use the 8-bitcount format without having to supply the other 192 entries in the color table. For the 24-bitcount standard format, cclrUsed is the number of colors used by the bit map.

cclrImportant

Minimum number of color indexes for satisfactory appearance of the bit map. More colors can be used in the bit map. However, it is not necessary to assign them to the device palette. These additional colors can be mapped to the nearest colors available. Zero (default) means that all entries are mapped. For a 24-bitcount standard format, the cclrImportant colors are also listed in the color table relating to this bit map.

usUnits Units of measure of the horizontal and vertical components of resolution

BRU_METRIC

(Default) Pels per meter.

usReserved

Reserved field. If present, it must be 0.

usRecording

Recording algorithm, the format in which bit-map data is recorded:

BRA_BOTTOMUP

(Default) Scan lines are recorded from bottom to top.

usRendering

Halftoning algorithm used to record bit-map data that has been digitally halftoned:

BRH_NOTHALFTONED

(Default) Bit-map data not halftoned.

BRH_ERRORDIFFUSION

Error diffusion or damped error diffusion algorithm

BRH_PANDA

Processing algorithm for noncoded document acquisition

BRH_SUPERCIRCLE

Super circle algorithm

cSize1

Size value 1. If BRH_ERRORDIFFUSION is specified in usRendering, cSize1 is the error damping as a percentage in the range 0 - 100. A value of 100% indicates no damping. A value of 0% indicates that any errors are not diffused.

If the BRH_PANDA or BRH_SUPERCIRCLE is specified, cSize1 is the x-dimension of the pattern used in pels.

cSize2

Size value 2. If BRH_ERRORDIFFUSION is specified in usRendering, this parameter is ignored. If the BRH_PANDA or BRH_SUPERCIRCLE is specified, cSize2 is the Y-dimension of the pattern used in pels.

ulColorEncoding

Color encoding:

BCE_RGB

(Default) Each element in the color array is an RGB2 data type.

ulIdentifier

Reserved for applications.

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.

Pointer to either a BITMAPINFO structure:

cbFix

Length of structure

cx

Bit-map width

cy

Bit-map height

cPlanes

Number of color planes, 1 if standard format

cBitCount

Number of adjacent color bits per pel

argbColor[ ]

Color table array of RGB structures:

bBlue

bGreen

bRed

Or to a BITMAPINFO2 structure:

cbFix

Length in bytes of this structure.

cx

Bit-map width.

cy

Bit-map height.

cPlanes

Number of color planes, 1 if standard format.

cBitCount

Number of adjacent color bits per pel.

ulCompression Compression scheme used to store the bit map

BCA_UNCOMP

Bit map is uncompressed (the only valid value).

cbImage Length of bit-map storage data in bytes. If the bit map is uncompressed, 0 (default) can be specified for this.

cxResolution Horizontal component of the resolution of the target device; that is, the resolution of the device for which the bit map is intended in the units specified by usUnits. This information enables an application to select from a resource group the bit map that best matches the characteristics of the current output device.

cyResolution Vertical component of the resolution of the target device; that is, the resolution of the device for which the bit map is intended in the units specified by usUnits. This information enables an application to select from a resource group the bit map that best matches the characteristics of the current output device.

cclrUsed

The number of color indexes from the color table that are used by the bit map. If it is 0 (default), all the indexes are used. If it is nonzero, only the first cclrUsed entries in the table are accessed by the system; further entries can be omitted.

For standard formats with a cBitCount of 1, 4, or 8 (and cPlanes=1), any indexes beyond cclrUsed are not valid. For example, a bit map with 64 colors can use the 8-bitcount format without having to supply the other 192 entries in the color table. For the 24-bitcount standard format, cclrUsed is the number of colors used by the bit map.

cclrImportant

Minimum number of color indexes for satisfactory appearance of the bit map. More colors can be used in the bit map but it is not necessary to assign them to the device palette. These additional colors can be mapped to the nearest colors available. Zero (the default) means that all entries are important. For a 24-bitcount standard format, the cclrImportant colors are also listed in the color table relating to this bit map.

usUnits

Units of measure of the horizontal and vertical components of resolution:

BRU_METRIC

(Default) Pels per meter.

usReserved

Reserved field. If present, it must be 0.

usRecording

Recording algorithm, the format in which bit-map data is recorded:

BRA_BOTTOMUP

(Default.) Scan lines are recorded from bottom to top.

usRendering

Halftoning algorithm used to record bit-map data that has been digitally halftoned:

BRH_NOTHALFTONED

(Default) Bit-map data not halftoned

BRH_ERRORDIFFUSION

Error diffusion or damped error diffusion algorithm

BRH_PANDA

Processing algorithm for noncoded document acquisition

BRH_SUPERCIRCLE

Super circle algorithm

cSize1

Size value 1. If BRH_ERRORDIFFUSION is specified in usRendering, cSize1 is the error damping as a percentage in the range 0 - 100. A value of 100% indicates no damping. A value of 0% indicates that any errors are not diffused.

If the BRH_PANDA or BRH_SUPERCIRCLE is specified, cSize1 is the X-dimension of the pattern used in pels.

cSize2

Size value 2. If BRH_ERRORDIFFUSION is specified in usRendering, this parameter is ignored. If the BRH_PANDA or BRH_SUPERCIRCLE is specified, cSize2 is the Y-dimension of the pattern used in pels.

ulColorEncoding

Color encoding:

BCE_RGB

(Default) Each element in the color array is an RGB2 data type.

ulIdentifier

Reserved for application use.

argbColor[ ]

Color table array of RGB2 structures:

bBlue

bGreen

bRed

fcOptions Reserved. Must be 0.

Note

The same bit-map file format is used for bit maps, icons, and pointers. For details, refer to the Presentation Manager Programming Reference.

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.

Example Code

#define INCL_GRE_DEVSUPPORT
#include <os2.h>

HDC                  hdc;        /*  Device context handle. */
PBITMAPINFOHEADER    pInfoHd;
ULONG                flUsage;
PBYTE                pBitmap;
PBITMAPINFO          paInfo;
PVOID                pInstance;  /*  Pointer to instance data. */
ULONG                lFunction;
HBITMAP              rc;         /*  Return codes. */

rc = GreCreateBitmap(hdc, pInfoHd, flUsage,
       pBitmap, paInfo, pInstance, lFunction);