GreBitblt

GreBitBlt modifies bit-map data at a target rectangle in the current device context (DC). The modification can copy a rectangle of data from a specified source DC to the target or perform a raster operation on the target.

This function must be supported by the presentation driver. GreBitblt is called by the function GpiBitBlt and is used to modify bit-map data within a target rectangle of the current device context. However, if the destination is larger or smaller than the source, the presentation driver can pass this function to the graphics engine by using the original pointer copied from the dispatch table.

Simulation support

None. This function is mandatory for all drivers.

Syntax

rc = GreBitblt(hdc, hdcSrc, cPoints, paptlPoint, lRop, flOptions, pBattrs, pInstance, lFunction);

Parameters

hdc (HDC) - input

Device context handle.

hdcSrc (HDC) - input

Handle to the source DC or bit map.

When lRop does not require a source, hdcSrc is passed as NULL. The handling routine then copies the current pattern to the currently selected bit map or device.

cPoints (LONG) - input

Number of (X,Y) pairs in paptlPoint.

A count of the number of (X,Y) pairs in the paptlPoint array. The count can be 2, 3, or 4.

cPoints=2 A raster operation (as determined by lRop) on the destination rectangle.

cPoints=3 A copy between two rectangles of the same size. Only the bottom-left corner is given for the source rectangle.

cPoints=4 An operation is determined by comparing the sizes of the two rectangles:

Target<Source Compress the source rectangle into the target rectangle. The flOptions flags determine how to handle eliminated rows and columns. In this case, the function can be passed to the GreBitblt routine in the graphics engine.

Target=Source Copy between equal rectangles.

Target>Source Stretch the source rectangle into the target rectangle. In this case, the function can be passed to the GreBitblt routine in the graphics engine.

paptlPoint (PPOINTL) - input

Pointer to an array of (X, Y) coordinate pairs.

Pointer to an array 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 previous parameter, cPoints, for exceptions).

(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 programmer of the called presentation driver must decide what to do).

Note

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. When BBO_TARGWORLD is set, the target rectangle is inclusive at all boundaries. The source is noninclusive.

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 the pattern, source, and target to get the required mix.

In addition to the ROP values defined at the API, the presentation driver must support ROP_GRAY (000080CAH). 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 by using the current pattern and the background pattern color (background pels for the pattern are not changed). For the PATSYM_HALFTONE pattern, this setting overpaints the background pattern color onto alternate pels leaving those in between unchanged.

flOptions (ULONG) - input

Specifies treatment of eliminated lines and columns when compression is done. Option flag values are:

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, this 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_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.

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 device context handle.

BLTMODE_ATTRS_PRES If set, the pBattrs parameter is present. This option can be ORed with any of the above options.

Note

Flags 15 - 31 are not used by the system. They are reserved for use by the presentation driver.

pBattrs (PBITBLTATTRS) - input

Pointer to attributes.

Pointer to a BITBLTATTRS structure containing the attributes. The BITBLTATTRS structure consists of the following fields:

cSize

Size of this structure

lColor

Foreground color of source

lBackColor

Background color of source

The color values are used in conversions between monochrome and color data, and are the only format conversions required. The conversions are required for:

• Output of a monochrome pattern to a color device. In this case, the source pattern is converted to a color pattern. This is performed by using the colors provided in the BITBLTATTRS structure. If these colors are not provided, the handling routine uses the current area colors for the target device context. See Area (Pattern) Attributes. The bits are then transferred so that:

• Source 1s become (target area) foreground color
• Source 0s become (target area) background color

• Transfer from a monochrome bit map to a color bit map or device. In this case, the source bits are converted by using the current image colors. These are the colors provided in the BITBLTATTRS structure. If these colors are not provided, the handling routine uses the current image colors for the target device context. See Image Attributes. The bits are then transferred so that:

• Source 1s become (target image) foreground color
• Source 0s become (target image) background color

• Transfer from a color bit map to a monochrome bit map or device. In this case, the source bit map is converted by using the source and target image colors. The target colors are provided in the BITBLTATTRS structure. If these colors are not provided, the handling routine uses those in the image attributes bundle for the target device context. See Image Attributes. When the source is a device context, the source-image background color is that from the source DC. When the source is a bit-map handle, the background color is taken from the BITBLTATTRS structure, if provided, or from the background-image color of the target DC. The bits are then transferred so that:

• Source pels that are the source-image background color become target-image background color.
• All other pels become target-image foreground color.

When lRop does not call for a pattern, the pattern set and pattern symbol are not used. Neither the source nor the pattern is required when a bit map or part of a bit map is being cleared to a particular color. When a pattern is required, dithering can be done for solid patterns in a color that is not available on the device. Color dithering is described in GreQueryNearestColor

pInstance (PVOID) - input

Pointer to instance data.

lFunction (ULONG) - input

High-order WORD=flags; low-order WORD=NGreBitblt.