BitBlt - Windows 3.1 Device Drivers

Windows 3.1 Device Drivers (ddag31qh.hlp) (Table of Contents; Topic list)

Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Up► ◄Next► ◄Previous► ──────────────────────────────────────────────────────────────────────────── BOOL BitBlt(lpDestDev, wDestX, wDestY, lpSrcDev, wSrcX, wSrcY, wXext, wYext, Rop3, lpPBrush, lpDrawMode); LPPDEVICE lpDestDev; WORD wDestX; WORD wDestY; LPPDEVICE lpSrcDev; WORD wSrcX; WORD wSrcY; WORD wXext; WORD wYext; long Rop3; LPBRUSH lpPBrush; LPDRAWMODE lpDrawMode; 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. Parameter Description ──────────────────────────────────────────────────────────────────────────── 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. Value Meaning ──────────────────────────────────────────────────────────────── SRCCOPY (0x00CC0020) Copies source bits to the destination rectangle: Destination = Source. SRCPAINT (0x00EE0086) Combines the source and destination bits using the bitwise OR operator: Destination = Source | Destination. SRCAND (0x008800C6) Combines the source and destination bits using the bitwise AND operator: Destination = Source & Destination. SRCINVERT (0x00660046) Combines the source and destination bits using the bitwise exclusive OR operator: Destination = Source ^ Destination. SRCERASE (0x00440328) Combines the source and inverse of destination bits using the bitwise AND operator: Destination = Source & (~ Destination). NOTSRCCOPY (0x00330008) Copies the inverse of the destination bits to the destination rectangle: Destination = ~ Destination. NOTSRCERASE (0x001100A6) Combines the inverse of the source and destination bits using the bitwise AND operator: Destination = (~ Source) & (~ Destination). MERGECOPY (0x00C000CA) Combines the source and brush bits using the bitwise AND operator: Destination = Source & Pattern. MERGEPAINT (0x00BB0226) Combines the destination and inverse of the source bits using the bitwise OR operator: Destination = (~ Source) | Destination. PATCOPY (0x00F00021) Copies the brush bits to the destination rectangle: Destination = Pattern. PATPAINT (0x00FB0A09) Combines the destination, pattern, and the inverse of source bits using the bitwise OR operator: Destination = (~ Source) | Pattern | Destination. PATINVERT (0x005A0049) Combines the pattern and destination bits using using the bitwise exclusive OR operator: Destination = Pattern ^ Destination. DSTINVERT (0x00550009) Copies the inverse of the destination bits: Destination = ~ Destination. BLACKNESS (0x00000042) Set all destination bits to black. WHITENESS (0x00FF0062) Set all bits to white. 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. 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, DRAWMODE, GDIINFO ♦