Difference between revisions of "GreBitblt"

Revision as of 21:52, 17 February 2019

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.

Return Code

rc (LONG) - returns 

Return Codes.

On completion, the handling routine must return a LONG integer (cHits), indicating, where appropriate, whether correlation hits have been detected:

• GPI_OK Successful
• GPI_HITS Successful with correlation hit (returned by display drivers when the correlate 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_BITMAP_IS_SELECTED
• PMERR_BITMAP_NOT_SELECTED
• PMERR_COORDINATE_OVERFLOW
• PMERR_DEV_FUNC_NOT_INSTALLED
• PMERR_EXCEEDS_MAX_SEG_LENGTH
• PMERR_HBITMAP_BUSY
• PMERR_HDC_BUSY
• PMERR_HUGE_FONTS_NOT_SUPPORTED
• PMERR_INCOMPATIBLE_BITMAP
• PMERR_INCORRECT_DC_TYPE
• PMERR_INSUFFICIENT_MEMORY
• PMERR_INV_BACKGROUND_COL_ATTR
• PMERR_INV_BITMAP_DIMENSION
• PMERR_INV_BITBLT_MIX
• PMERR_INV_BITBLT_STYLE
• PMERR_INV_COLOR_ATTR
• PMERR_INV_COLOR_DATA
• PMERR_INV_COLOR_FORMAT
• PMERR_INV_COLOR_INDEX
• PMERR_INV_COLOR_OPTIONS
• PMERR_INV_COLOR_START_INDEX
• PMERR_INV_COORD_SPACE
• PMERR_INV_COORDINATE
• PMERR_INV_DC_DATA
• PMERR_INV_DC_TYPE
• PMERR_INV_DRIVER_NAME
• PMERR_INV_HBITMAP
• PMERR_INV_HDC PMERR_INV_ID
• PMERR_INV_IN_AREA
• PMERR_INV_IN_PATH
• PMERR_INV_INFO_TABLE
• PMERR_INV_LENGTH_OR_COUNT
• PMERR_INV_PATTERN_SET_ATTR
• PMERR_INV_PATTERN_SET_FONT
• PMERR_INV_PICK_APERTURE_POSN
• PMERR_INV_SCAN_START
• PMERR_INV_USAGE_PARM
• PMERR_UNSUPPORTED_ATTR_VALUE

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

Remarks

The device contexts can be memory DCs with bit maps selected or DCs belonging to devices that support raster operations.

When copying bits from a color bit map to a monochrome bit map or device, only those pels that are in the source background color are copied to the target as background color. All other pels are copied to the target as foreground color. Copying is nondestructive. When the target and source rectangles are in the same DC, no information is lost from the source if the rectangles overlap. When the target is expressed in world coordinates (that is, the BBO_TARGWORLD flag is set in flOptions), the coordinates must be transformed device coordinates. The bits are transferred to an upright rectangle in device space, regardless of any rotational elements that might have been present in the transforms.

The attribute structure identified by the pBattrs parameter defines the bit-map foreground and background colors. If pBattrs is NULL, the handling routine uses the current foreground and background colors.

When the mix specified by lRop requires both source and pattern, a 3-way operation is performed by using the current pattern in the target device context. If pattern mixing is not required, a 2-way operation is done. If any of the source data is unavailable, the handling routine transfers those bits that are present and returns without error. This might occur when the source device context is a window on the screen that has been overlaid by another. In this example, the handling routine must proceed by reading what is there.

Note

The device driver may pass back Bitblt calls that call for stretching. However during the stretching, GRE will perform dithering only if the device supports more than two colors and a bit map format of more than one bit per pel in its response to a GreQueryDeviceCaps call.

A driver may alter these capabilities before returning a Bitblt call to the GRE so that dithering will (or will not) be done.

Example Code

Related Functions