GpiBitBlt

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

Syntax

GpiBitBlt(hpsTarget, hpsSource, lCount, aptlPoints, lRop, flOptions)

Parameters

hpsTarget (HPS) - input

Target presentation-space handle.

hpsSource (HPS) - input

Source presentation-space handle.

lCount (LONG) - input

Point count.

Number of points specified in aptlPoints.

It must be 3 or 4. If this is 3, a source rectangle of the same size as the target rectangle is used. If it is 4, stretching or compression is performed as necessary. If compression is performed, the flOptions parameter determines how eliminated rows or columns are handled.

aptlPoints (PPOINTL) - input

Point array.

Array of lCount points, in the order Tx1, Ty1, Tx2, Ty2, Sx1, Sy1, Sx2, Sy2, where:

• Tx1,Ty1 Specify the lower-left corner of the target rectangle in target device coordinates.
• Tx2,Ty2 Specify the upper-right corner of the target rectangle in target device coordinates.
• Sx1,Sy1 Specify the lower-left corner of the source rectangle in source device coordinates.
• Sx2,Sy2 Specify the upper-right corner of the source rectangle in source device coordinates (not required if neither stretching nor compression is to be performed).

lRop (LONG) - input

Mixing function required.

The value of lRop required to achieve any given result can be determined from the following table. The final value of each bit in every pel depends on the values of the corresponding bits in the pattern (P), source (S), and the original target value (T initial). Each row of the table shows one of the 8 possible combinations of these values. For each combination, mark the desired final target value in the last column. The 8 bits in this column then show the value of the least significant byte of lRop required to achieve this mixing function. For example, if the required mixing function is to copy the source to the target, then the T (final) column will be the same as the S column, and so lRop will have the binary value 11001100, or the hexadecimal value 00CC.

P S T (initial) T (final) 0 0 0 Bit 0 (least significant) 0 0 1 Bit 1 0 1 0 Bit 2 0 1 1 Bit 3 1 0 0 Bit 4 1 0 1 Bit 5 1 1 0 Bit 6 1 1 1 Bit 7 (most significant)

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.

The options define how eliminated lines or columns are treated if a compression is performed.

Bits 15 through 31 of flOptions may be used for privately supported modes for particular devices.

• BBO_OR : The default. If compression is necessary, logical-OR the eliminated rows or columns. This is useful for white on black.
• BBO_AND : If compression is necessary, logical-AND the eliminated rows or columns. This is useful for black on white.
• BBO_IGNORE : If compression is necessary, ignore the eliminated rows or columns. This is useful for colour.
• BBO_PAL_COLORS : The colour table passed in with the BitmapInfoTable is defined as indices into the currently realized palette, rather than actual colours.

Return Code

lHits (LONG) - returns

Correlation and error indicators.

• GPI_OK : Successful completion
• GPI_HITS : Correlate hits
• GPI_ERROR : Error occurred

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.

Remarks

A rectangle of bit-map image data is copied from a bit map selected into a device context associated with the source presentation space, to a bit map selected into a device context associated with the target presentation space. Alternatively, either presentation space may 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.

Unless the device is a banded printer, both source and target may refer to the same presentation space. If so, the copy is nondestructive when source and target rectangles overlap.

A rectangle can be specified in device coordinates, for both source and target. These rectangles are noninclusive; that is, they include the left and lower boundaries in device space, but not the right and upper boundaries. Thus, if the lower-left maps to the same device pel as the upper-right, that rectangle is considered to be empty.

If the upper-right source point is specified, and the source and target rectangles are of different sizes, stretching, or compressing, or both, 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.

The following 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 image will be grey scaled under the current operation of the device drivers, and the colours will be shades of grey corresponding to a mapping scheme that the device driver uses. This behaviour may vary from one printer to another, depending on the printer's capabilities.
  • The only variance from this grey-scaling is that pure white (for example, backgrounds) prints as black and pure black (for example, text) prints as white.

Note

In all of the above instances (except where the source image background colour is used) it is the attributes of the target presentation space that are used.

If the mix (lRop) does not call for a pattern, the pattern set and pattern symbol are not used. If it does not require a source (this is not valid when flOptions is in the range 1 through 3), hpsSource is not required and must be null. Sx1,Sy1 is also ignored in this instance.

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.

If any of the source data is not available (when, for example, the source presentation space is connected to a screen window, and the source rectangle is not totally visible), the contents of the unavailable parts are undefined. This can be checked with GpiRectVisible before calling this function.

This function is independent of drawing mode (see GpiSetDrawingMode); the effect always occurs immediately, and it is not retained even if the drawing mode is draw-and-retain or retain. Its effect, however, is recorded in a metafile, but note that this is successful only if the metafile is replayed on a similar device, with draw drawing mode.

The current position in both source and target presentation spaces is unchanged by this function.

Note

This function must not be used when creating SAA-conforming metafiles; see "MetaFile Resolutions" in the Presentation Manager Programming Reference for more information.

Example Code

#define INCL_GPIBITMAPS /* Or use INCL_GPI, INCL_PM, Also in COMMON section */
#include <os2.h>

HPS        hpsTarget;   /*  Target presentation-space handle. */
HPS        hpsSource;   /*  Source presentation-space handle. */
LONG       lCount;      /*  Point count. */
PPOINTL    aptlPoints;  /*  Point array. */
LONG       lRop;        /*  Mixing function required. */
ULONG      flOptions;   /*  Options. */
LONG       lHits;       /*  Correlation and error indicators. */

lHits = GpiBitBlt(hpsTarget, hpsSource, lCount,
          aptlPoints, lRop, flOptions);

This example uses GpiBitBlt to copy a bit map from one presentation space to another. Two presentation spaces are created: one associated with a memory context, and the other associated with a screen context. The function copies the memory context bit map that is 100 pels wide and 100 pels high into a 50-by-50-pel rectangle at the location (300,400) on the screen, thereby causing the bit map to be visible in the window. Since the raster operation is ROP_SRCCOPY, GpiBitBlt replaces the image previously in the target 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   /* Bit map functions */
 #define INCL_DEV          /* Device Function definitions */
 #define INCL_GPICONTROL   /* GPI control Functions */
 #define INCL_WINWINDOWMGR /* Window Manager Functions */
 #include <os2.h>
 
 HAB hab;           /* anchor-block handle */
 HPS hpsMemory;     /* presentation-space handle */
 HPS hpsScreen;     /* presentation-space handle */
 HDC hdcScreen;     /* Device-context handle */
 HDC hdcMemory;     /* Device-context handle */
 SIZEL sizl={0, 0}; /* use same page size as device */
 
 /* context data structure */
 DEVOPENSTRUC dop = {0L, "DISPLAY", NULL, 0L, 0L, 0L, 0L, 0L, 0L};
 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 */
 HWND hwnd;
 
 /* create memory device context and presentation space, associating DC with the PS */
 hdcMemory = DevOpenDC(hab, OD_MEMORY, "*", 5L, (PDEVOPENDATA)&dop, NULLHANDLE);
 hpsMemory = GpiCreatePS(hab, hdcMemory, &sizl, GPIA_ASSOC | PU_PELS);
 
 /* create window device context and presentation space, associating DC with the PS */
 hdcScreen = WinOpenWindowDC(hwnd); /* Open window device context */
 hpsScreen = GpiCreatePS(hab, hdcScreen, &sizl, PU_PELS | GPIF_LONG | GPIA_ASSOC);
 
 /*.
   . get bit map, associate bit map with memory device context,
   . draw into bit map
   . */
 /* display the bit map on the screen by copying it from the memory
    device context into the screen device context */
 GpiBitBlt(hpsScreen, hpsMemory, 4L, aptl, ROP_SRCCOPY, BBO_IGNORE);

Related Functions

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