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):

• Area color
• Area background color
• Pattern set
• Pattern symbol.

The color values are used in conversion between monochrome and color data. This is the only format conversion performed by this function.

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.

#define INCL_GPIBITMAPS
#include <OS2.H>
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 */

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