BitBlt

The BitBlt function transfers bits from a rectangle to a source device to a rectangle having the same dimensions to a destination device. The transfer is controlled by a ternary raster operation value that specifies how corresponding bits from the source, destination, and pattern in a brush are combined to form the final bits in the destination.

A graphics driver must export the BitBlt function if the RC_BITBLT value is set in the dpRaster member of the driver's GDIINFO structure.

Parameters

lpDestDev

Points to PDEVICE or PBITMAP structure specifying the destination device or bitmap.

wDestX

Specifies the x-coordinate (in device units) of the origin of the rectangle on the destination device to receive the transferred bits.

wDestY

Specifies the y-coordinate (in device units) of the origin of the rectangle on the destination device to receive the transferred bits.

lpSrcDev

Points to PDEVICE or PBITMAP structure specifying the source device or bitmap.

wSrcX

Specifies the x-coordinate (in device units) of the origin of the rectangle on the source device containing the bits to transfer.

wSrcY

Specifies the y-coordinate (in device units) of the origin of the rectangle on the source device containing the bits to transfer.

wXext

Specifies the width (in device units) of the rectangles on both the source and destination devices.

wYext

Specifies the height (in device units) of the rectangle on both the source and destination devices.

Rop3

Specifies a ternary raster-operation value. This value determines how BitBlt combines corresponding pixels from the source, destination, and brush to produce the final pixels in the destination rectangle. The Rop3 parameter can be any one of 256 ternary raster-operation values; the following lists the most common values.

For more information about ternary-raster operations and a complete list of values, see Appendix A, “Binary and Ternary Raster-Operation Codes.”

lpPBrush

Points to a PBRUSH structure specifying a physical brush. BitBlt uses this brush only if the Rop3 parameter specifies a ternary-raster operation that requires the brush to be combined with source or destination or both.

lpDrawMode

Points to a DRAWMODE structure specifying the color information BitBlt needs to determine patterned brush colors and to carry color conversions and transparent copy operations. The structure has the following form:

typedef struct tagDRAWMODE {

short Rop2; /*binary-raster operations*/

short bkMode; /*background mode*/

PCOLOR bkColor; /*physical background color*/

PCOLOR TextColor; /*physical text (foreground) color*/

short TBreakExtra;/*number of extra pixels to add to line*/

short BreakExtra; /*pixels per break: TBreakExtra/BreakCount*/

short BreakErr; /*running error term*/

short BreakRem; /*remaining pixels: TBreakExtra%BreakCount*/

short BreakCount; /*number of breaks in the line*/

short CharExtra; /*extra pixels for each character*/

COLORREF LbkColor; /*logical background color*/

COLORREF LTextColor; /*logical text (foreground) color*/

} DRAWMODE;

Return Value

This return value is TRUE if it is successful. Otherwise, it is FALSE.

Comments

The export ordinal for this function is 1.

The lpDestDev and lpSrcDev parameters can specify the same device, and transferring bits from one part of a device to another is a valid operation. If the source and destination rectangle overlap, BitBlt must carefully transfer bits so that the transfer does not inadvertently overwrite source bits before they have been transferred to the destination.

The Rop3 parameter specifies whether bits from the source, destination, and brush are used in the transfer. If the ternary raster operation specified by Rop3 does not include the source, BitBlt ignores the source bits. If the operation does not include the destination, BitBlt replaces the original destination bits without using them to form the final bits.

If Rop3 does not include the brush, BitBlt ignores the brush. If Rop3 does include the brush, BitBlt must determine whether the brush is solid or patterned (that is, has an associated bitmap). If the brush has a bitmap, BitBlt must combine the corresponding bits of the bitmap with the source and destination bits (as specified by the raster operation) to form the final destination bits.

If the source and bitmap associated with the brush do not have the same color
format as the destination, BitBlt must convert the source and brush bitmap to
the destination's color format before transferring bits. BitBlt uses the text (foreground) and background colors specified by the lpDrawMode parameter to convert colors.

To convert a monochrome bitmap to a color bitmap, BitBlt converts white bits (1) to the background color and converts black bits (0) to the text (foreground) color.

To convert a color bitmap to a monochrome bitmap, BitBlt converts all pixels that match the background color to white (1), and converts all other pixels to black (0).

In some device drivers, BitBlt must check the bkMode member of the DRAWMODE structure pointed to by the lpDrawMode parameter as well as the Rop3 parameter to determine how to carry out the transfer. If the bkMode member specifies the background mode TRANSPARENT1, BitBlt must not transfer source and brush bits that have the same color as the destination's background color (as specified by the bkColor member of the DRAWMODE structure pointed to by lpDrawMode). In other words, the corresponding destination bits must be left unchanged. Other background modes do not affect the transfer. Only device drivers that have set the C1_TRANSPARENT value in the dpCaps1 member of the GDIINFO structure are required to check the background mode.

See Also

StretchBlt