GpiDrawBits

This function draws a rectangle of bits.

Syntax

GpiDrawBits(hps, pBits, pbmiInfoTable, lCount, aptlPoints, lRop, flOptions)

Parameters

hps (HPS) - input

Target presentation-space handle.

pBits (PVOID) - input

Source bits.

The source bits must be in one of the standard bit-map formats. This field must point to a doubleword aligned address to assure correct creation of the bit map by the device in device specific format.

pbmiInfoTable (PBITMAPINFO2) - input

Bit-map information table.

This describes the format of the source bits.

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.

An error occurs if the left coordinate of the target rectangle is greater than the right, or if the bottom coordinate is greater than the top.

• 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 below:

P S T(initial) T(final)
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 as described above 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 value; 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 Bitmap-InfoTable 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_INV_COORDINATE (0x205B)

An invalid coordinate value was specified.

PMERR_INV_RECT (0x20BD)

An invalid rectangle parameter was specified.

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.

Remarks

A rectangle of bit-map image data is copied from storage 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. An error occurs if this device does not support raster operations.

The source bits must be in one of the standard bit-map formats.

A rectangle is specified in device coordinates for the source bits, 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.

These current attributes of the target presentation space are used (other than for converting between monochrome and colour, as described below):

• Area colour
• Area background colour
• Pattern set
• Pattern symbol.

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

The conversions are:

• Output of a monochrome pattern to a colour device

In this instance the pattern is converted first to a colour pattern, using the current area colours:

• • source 1s -> area foreground colour
  • source 0s -> area background colour.
• Copying from a monochrome bit map to a colour bit map (or device)

The source bits are converted as follows:

• • source 1s -> image foreground colour
  • source 0s -> image background colour.
• Copying from a colour bit map to a monochrome bit map (or device)

The source bits are converted as follows:

• • source non-zeros -> image foreground colour
  • source 0s -> image background colour.

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 colour.

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 colour 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 colour, 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 colour. This provides for a transparent underlay function.

This function can cause immediate drawing, or be retained in segment store, or both of these, depending upon the drawing mode (see GpiSetDrawingMode). If the function is retained in segment store, the storage identified by the pBits and pbmiInfoTable parameters must not be changed or freed by the application while the segment containing the function can still be drawn. However, if a metafile is generated and no further drawing is needed, this does not apply, as the information is encaptured in the metafile.

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 example uses GpiDrawBits to draw a rectangle of bits. The bit map was previously placed in application memory using GpiQueryBitmapBits; when the stored image is displayed, it will be a compressed copy (ROP_SRCCOPY) of the source bit map (note the difference between the target and source rectangle sizes), with eliminated rows/columns ignored (BBO_IGNORE) when compression takes place.

#define INCL_GPIBITMAPS /* Bit map functions */
#include <os2.h>

HPS hps; /* presentation-space handle */
PBYTE pb; /* bit-map image data */
BITMAPINFO2 pbmi; /* bit-map information table */
LONG lHits; /* correlation/error indicator */
LONG lScan; /* number of lines scanned */
/* target and source rectangles */
POINTL aptlPoints[4]={ 300, 400, 350, 450, 0, 0, 100, 100 };

/* scan and transfer bit map to application storage */
pbmi.cbFix = 16L;
pbmi.cPlanes = 1;
pbmi.cBitCount = 4;
lScan = GpiQueryBitmapBits(hps, 0L, 100L, pb, &pbmi);
 .
 .
 .
/* draw stored rectangle bit map */
lHits = GpiDrawBits(hps, (VOID *)pb, &pbmi, 4L, aptlPoints, ROP_SRCCOPY, BBO_IGNORE);

Related Functions

• GpiBitBlt
• GpiCreateBitmap
• GpiDeleteBitmap
• GpiLoadBitmap
• GpiQueryBitmapBits
• GpiQueryBitmapDimension
• GpiQueryBitmapHandle
• GpiQueryBitmapParameters
• GpiQueryDeviceBitmapFormats
• GpiSetBitmap
• GpiSetBitmapBits
• GpiSetBitmapDimension
• GpiSetBitmapId
• GpiWCBitBlt