GreDrawBits

GreDrawBits draws a rectangle of bits.


 * Simulation support: This function is simulated by a handling routine in Revision 2.0 (or higher) of the graphics engine and can be hooked by the presentation driver.

Syntax
GreDrawBits(hdc, pBitmap, pInfo, cPoints, paptlPoint, lRop, flOptions, pInstance, lFunction);

Parameters

 * hdc (HDC) - input : Device context handle.


 * pBitmap (PBYTE) - input : Pointer to bit map data.

Pointer to the pel data of the bit map. 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, three 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 three bytes are the only pel data for that scan line, one more byte of zeros would be required to pad the line to a ULONG boundary.


 * pInfo (PBITMAPINFO) - input : Pointer to data structure defining the new bit map. Pointer to either a BITMAPINFO structure:


 * cbFix Length of structure
 * cx Bit-map width
 * cy Bit-map height
 * cPlanes Number of color planes, one if standard format
 * cBitCount Number of adjacent color bits per pel
 * argbColor[] Color table array of RGB structures:
 * bBlue
 * bGreen
 * bRed


 * Or pointer to a BITMAPINFO2 structure:


 * cbFix Length of structure
 * cx Bit-map width
 * cy Bit-map height
 * cPlanes Number of color planes, one 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 (the default) can be specified.
 * cxResolution Horizontal component of the resolution of the target device. That is, the resolution of the device the bit map is intended for 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 the bit map is intended for 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 (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 Half-toning 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.


 * cPoints (LONG) - input : Number of (X, Y) pairs in paptlPoint.

This count must be set to 4.

The operation is determined by comparing the sizes of the two rectangles:

TargetSource Stretch the source rectangle into the target rectangle. In this case, the call can be passed to the GreBitblt routine in the graphics engine.

M paptlPoint (PPOINTL) - input : Pointer to an array of (X, Y) coordinate pairs.

A pointer to a block of (X, Y) coordinate pairs that define the target and source rectangles. The coordinates, which can be passed as a pair of RECTL structures, define the bottom-left and top-right corners of the target and source rectangles (see "cPoints" above for more information): (xTgtBL, yTgtBL), (xTgtTR, yTgtTR), (xSrcBL, ySrcBL), (xSrcTR, ySrcTR)

When the source rectangle is totally or partially outside the source bit map (or device), the operation is implementation-dependent for that area, that is, the user must decide what to do.


 * Note: When BBO_TARGWORLD is set, the target rectangle is inclusive at all boundaries. The source is noninclusive.

When BBO_TARGWORLD is not set, the rectangles are noninclusive. That is, they include the left and lower boundaries in device units but not the top and right boundaries. When the bottom-left corner of a rectangle maps to the same device pel as the top-right corner, that rectangle is considered to be empty.


 * lRop (LONG) - input : Raster operation code.

The low-order byte represents a mix value in the range, hex 00 - hex FF. Raster operation code values and the mix-bit table are defined in the Presentation Manager Programming Reference. The handling routine uses lRop to determine the operations to perform on pattern, source, and target to get the required mix.

In addition to the raster operation values defined at the API, the presentation driver must support ROP_GRAY (hex 000080CA). This value is used to shade the text for menu items that are not currently selectable. When ROP_GRAY is set, the handling routine overpaints the foreground pattern using the current pattern and the background pattern color (background pels for the pattern are not changed). For the PATSYM_HALFTONE pattern, this overpaints the background pattern color onto alternate pels, leaving those in between unchanged.

Option flags:
 * flOptions (ULONG) - input : Specified treatment of eliminated lines and columns.
 * BBO_OR Stretch and compress, as necessary, ORing any eliminated rows and columns. Used for White on Black.
 * BBO_AND Stretch and compress, as necessary, ANDing any eliminated rows and columns. Used for Black on White.
 * BBO_IGNORE Stretch and compress, as necessary, IGNORing any eliminated rows and columns. Used for color.
 * BBO_TARGWORLD The target rectangle is defined in world coordinates in the target PS. When this option is specified, the target rectangle is transformed to device coordinates. Where any shear or rotation has occurred, the target rectangle must be converted to an upright rectangle that bounds the transformed figure. This rectangle is then used as the target for the operation. No inversion of the image takes place.
 * BBO_COLORS The source color map is defined in terms of indexes into the destination color map instead of RGB values.
 * BBO_PAL_COLORS The color values in BITMAPINFOHEADER2 are not colors; they are indexes into the currently realized palette.
 * BBO_NO_COLOR_INFO No color information is associated with the source. The source bit map should be copied directly to the destination without translating the pels. This option must be supported if the device supports palette management.
 * BBO_DITHER Use an enhanced stretching algorithm when stretching a bit map.
 * BLTMODE_SRC_BITMAP hdcSrc is a bit map handle. The bit map must not be currently selected into a device context. If this flag is not set, hdcSrc is a DC handle.
 * BLTMODE_ATTRS_PRES If set, the pBattrs parameter is present. This option can be ORed with any of the options above.


 * Note: Flags 15-31 are not used by the system; they are reserved for use by the presentation driver.


 * pInstance (PVOID) - input : Pointer to instance data.


 * lFunction (ULONG) - input : High-order WORD=flags; low-order WORD=NGreDrawBits.

Returns

 * rc (ULONG) - returns : Return Codes.

On completion, the handling routine must return a LONG integer (cHits) indicating, where appropriate, whether correlation hits were detected:
 * GPI_OK Successful
 * GPI_HITS Successful with correlation hit (returned by the display driver when the correlation flag is ON, and a hit is detected)
 * GPI_ERROR Error

Possible Errors Detected: When an error is detected, the handling routine must call WinSetErrorInfo to post the condition. Error codes for conditions that the handling routine is expected to check include:
 * PMERR_BASE_ERROR
 * PMERR_HDC_BUSY
 * PMERR_INCORRECT_DC_TYPE
 * PMERR_INV_BITBLT_MIX
 * PMERR_INV_BITBLT_STYLE
 * PMERR_INV_COORDINATE
 * PMERR_INV_HDC
 * PMERR_INV_LENGTH_OR_COUNT
 * PMERR_INV_RECT

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

Sample

 * 1) define INCL_GRE_BITMAPS
 * 2) include 

HDC           hdc;         /*  Device context handle. */ PBYTE         pBitmap;     /*  Pointer to bit map data. */ PBITMAPINFO   pInfo; LONG          cPoints;     /*  Number of (X, Y) pairs in paptlPoint. */ PPOINTL       paptlPoint;  /*  Pointer to an array of (X, Y) coordinate pairs. */ LONG          lRop;        /*  Raster operation code. */ ULONG         flOptions; PVOID         pInstance;   /*  Pointer to instance data. */ ULONG         lFunction; ULONG         rc;          /*  Return Codes. */

rc = GreDrawBits(hdc, pBitmap, pInfo, cPoints,      paptlPoint, lRop, flOptions, pInstance,       lFunction);