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.

    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.

    ---

    [Back: GreBitblt Return Value - rc]
    [Next: GreBitblt - Remarks]