GpiWCBitBlt

This function copies a rectangle of bit-map image data.

Syntax
GpiWCBitBlt (hpsTarget, hbmSource,lCount, aptlPoints, lRop, flOptions)

Parameters

 * hpsTarget (HPS) - input: Target presentation-space handle.
 * hbmSource (HBITMAP) - input: Source bit-map handle.
 * It is an error if this bit map is currently selected into a memory device context.


 * lCount (LONG) - input: Point count.
 * This count must be equal to 4.


 * aptlPoints (PPOINTL) - input: Point array.
 * Array of lCount points, in the order Tx1, Ty1, Tx2, Ty2, Sx1, Sy1, Sx2, Sy2. These are:
 * Tx1,Ty1 - Specify the bottom-left corner of the target rectangle in target world coordinates.
 * Tx2,Ty2 - Specify the top-right corner of the target rectangle in target world coordinates.
 * Sx1,Sy1 - Specify the bottom-left corner of the source rectangle in source device coordinates.
 * Sx2,Sy2 - Specify the top-right corner of the source rectangle in source device coordinates.


 * lRop (LONG) - input : Mixing function required.
 * Each plane of the target can be considered to be processed separately. For any pel in a target plane, three bits together with the lRop values are used to determine the final value. These are the value of that pel in the Pattern (P) and Source (S) data and the initial value of that pel in the Target (T) data. For any combination of P, S, and T pel values, the final target value for the pel is determined by the appropriate lRop bit value as shown in the table below:

P S T       T (final) (initial) 0 0 0       Index bit 0 (least significant) 0 0 1        Index bit 1 0 1 0        Index bit 2 0 1 1        Index bit 3 1 0 0        Index bit 4 1 0 1        Index bit 5 1 1 0        Index bit 6 1 1 1        Index bit 7 (most significant) The index formed in the above way determines the mixing required. Mnemonic names are available for commonly used mixes: ROP_SRCCOPY /* SRC */ ROP_SRCPAINT /* SRC OR DST */ ROP_SRCAND /* SRC AND DST */ ROP_SRCINVERT /* SRC XOR DST */ ROP_SRCERASE /* SRC AND NOT(DST) */ ROP_NOTSRCCOPY /* NOT(SRC) */ ROP_NOTSRCERASE /* NOT(SRC) AND NOT(DST) */ ROP_MERGECOPY /* SRC AND PAT */ ROP_MERGEPAINT /* NOT(SRC) OR DST */ ROP_PATCOPY /* PAT */ ROP_PATPAINT /* NOT(SRC) OR PAT OR DST */ ROP_PATINVERT /* DST XOR PAT */ ROP_DSTINVERT /* NOT(DST) */ ROP_ZERO /* 0 */ ROP_ONE /* 1 */


 * flOptions (ULONG) - input: Options.
 * How eliminated lines or columns are treated if a compression is performed.
 * Flags 15 through 31 of flOptions can be used for privately-supported modes for particular devices.
 * BBO_OR - The default. If compression is necessary, logical-OR eliminated rows or columns. This is useful for white on black.
 * BBO_AND - If compression is necessary, logical-AND eliminated rows or columns. This is useful for black on white.
 * BBO_IGNORE - If compression is necessary, ignore eliminated rows or columns. This is useful for color.
 * BBO_PAL_COLORS - The color table passed in with the BitmapInfoTable is defined as indices into the currently realized palette, rather than actual colors.

Return Code

 * lHits (LONG) - returns : Correlation and error indicators.
 * GPI_OK Successful
 * GPI_HITS Correlate hits
 * GPI_ERROR Error.

Errors
Possible returns from WinGetLastError:
 * PMERR_INV_HPS (0x207F) : An invalid presentation-space handle was specified.
 * PMERR_PS_BUSY (0x20F4) : An attempt was made to access the presentation space from more than one thread simultaneously.
 * PMERR_INV_LENGTH_OR_COUNT (0x2092) : An invalid length or count parameter was specified.
 * PMERR_INV_BITBLT_MIX (0x2046) : An invalid lRop was specified with a GpiBitBlt or GpiWCBitBlt function.
 * PMERR_INV_BITBLT_STYLE (0x2047) : An invalid options parameter was specified with a GpiBitBlt or GpiWCBitBlt function.
 * PMERR_BITMAP_NOT_FOUND (0x200A) : A attempt was made to perform a bit-map operation on a bit map that did not exist.
 * PMERR_INV_COORDINATE (0x205B) : An invalid coordinate value was specified.
 * PMERR_INV_RECT (0x20BD) : An invalid rectangle parameter was specified.
 * PMERR_NO_BITMAP_SELECTED (0x20E4) : An attempt has been made to operate on a memory device context that has no bit map selected.
 * PMERR_INCORRECT_DC_TYPE (0x203C) : An attempt was made to perform a bit-map operation on a presentation space associated with a device context of a type that is unable to support bit-map operations.
 * PMERR_INCOMPATIBLE_BITMAP (0x203A) : An attempt was made to select a bit map or perform a BitBlt operation on a device context that was incompatible with the format of the bit map.
 * PMERR_INV_HBITMAP (0x207B) : An invalid bit-map handle was specified.
 * PMERR_HBITMAP_BUSY (0x2032) : An internal bit map busy error was detected. The bit map was locked by one thread during an attempt to access it from another thread.

Remarks
A rectangle of bit-map image data is copied from a bit map, to a bit map selected into a device context associated with the target presentation space. Alternatively, the target presentation space can be associated with a device context that specifies a suitable raster device, for example, the screen.


 * Note:In either case, both source and target device contexts must apply to the same physical device. It is an error if this device does not support raster operations. A rectangle is specified in device coordinates for the source bit map, and one in world coordinates for the target presentation space. The source rectangle is noninclusive; the left and lower boundaries in device space are included, but not the right and upper boundaries. Thus if the bottom-left is equal to the top-right, the rectangle is deemed to be empty. The target rectangle is "inclusive-inclusive"; that is, all boundaries are included in the rectangle.

If the target rectangle, after transformation to device coordinates and adjustment for inclusivity, is not the same size as the source rectangle, then stretching or compressing of the data occurs. flOptions specifies how eliminated rows or columns of bits are to be treated if compression occurs. Note that the pattern data is never stretched or compressed.

If there is a rotational effect in the transforms, the copy of the bit map is rotated accordingly.

The target rectangle is transformed to device coordinates, and if any shear or rotation has occurred, this is then converted to an upright rectangle that bounds the transformed figure. This rectangle is used as the target of the operation. No inversion of the image takes place.

These current attributes of the target presentation space are used (other than for converting between monochrome and color, as described below): The color values are used in conversion between monochrome and color data. This is the only format conversion performed by this function.
 * Area color
 * Area background color
 * Pattern set
 * Pattern symbol.

The conversions are:
 * Output of a monochrome pattern to a color device. In this instance the pattern is converted first to a color pattern, using the current area colors:
 * source 1s -> area foreground color
 * source 0s -> area background color.
 * Copying from a monochrome bit map to a color bit map (or device). The source bits are converted as follows:
 * source 1s -> image foreground color
 * source 0s -> image background color.
 * Copying from a color bit map to a monochrome bit map (or device). The source bits are converted as follows:
 * source nonzeros -> image foreground color
 * source 0s -> image background color.

If the mix (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 to be cleared to a particular color.

If the mix does require both source and pattern, a three-way operation is performed.

If a pattern is required, dithering may be performed for solid patterns in a color that is not available on the device. See GpiSetPattern.

Support for the BM_SRCTRANSPARENT and BM_DESTTRANSPARENT background mix options is provided by the CAPS_BACKGROUND_MIX_SUPPORT flags in DevQueryCaps.

Requesting the BM_SRCTRANSPARENT background mix option results in pels from the source bit map matching the presentation space background color to not be copied to the output bit map, effectively leaving those pels in the output unchanged. This provides for a transparent overlay function.

Requesting the BM_DESTTRANSPARENT background mix option results in a transfer such that pels from the source bit map will only be copied to destination pels that match the presentation space background color. This provides for a transparent underlay function. This function (unlike GpiBitBlt) can be drawn immediately, retained in segment store, or both of these, depending upon the drawing mode (see GpiSetDrawingMode).


 * Note:There are restrictions on the use of this function when creating SAA-conforming metafiles; see "MetaFile Resolutions" in the Presentation Manager Programming Reference for more information.

Graphic Elements and Orders
Element Type: OCODE_GBBLT - Order: Bitblt

Example Code
This function copies a rectangle of bit-map image data. This example uses GpiWCBitBlt to copy and compress a bit map in a presentation space. The function copies the bit map that is 100 pels wide and 100 pels high into a 50-by-50-pel rectangle at the location (300,400). Since the raster operation is ROP_SRCCOPY, GpiWCBitBlt replaces the image previously in the presentation-space rectangle. The function compresses the bit map to fit the new rectangle by discarding extra rows and columns as specified by the BBO_IGNORE option.  HPS hps;           /* Presentation space handle. */ HBITMAP hbm; POINTL aptl[4] = { 300, 400,           /* lower-left corner of target */ 350, 450,           /* upper-right corner of target */ 0, 0,               /* lower-left corner of source */ 100, 100 };         /* upper-right corner of source */
 * 1) define INCL_GPIBITMAPS
 * 2) include 

GpiWCBitBlt(hps,            /* presentation space */            hbm,             /* bit-map handle */            4L,              /* four points needed to compress */            aptl,            /* points for source and target rectangles */            ROP_SRCCOPY,     /* copy source replacing target */            BBO_IGNORE);     /* discard extra rows and columns */ 

Related Functions

 * GpiBitBlt
 * GpiCreateBitmap
 * GpiDeleteBitmap
 * GpiDrawBits
 * GpiLoadBitmap
 * GpiQueryBitmapBits
 * GpiQueryBitmapDimension
 * GpiQueryBitmapHandle
 * GpiQueryBitmapParameters
 * GpiQueryDeviceBitmapFormats
 * GpiSetBitmap
 * GpiSetBitmapBits
 * GpiSetBitmapDimension
 * GpiSetBitmapId