Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function combines the color data for the source and destination bitmaps using the specified mask and raster operation.

Syntax 

BOOL MaskBlt(
  HDC 
hdcDest, 
  int 
nXDest, 
  int 
nYDest, 
  int 
nWidth, 
  int 
nHeight, 
  HDC 
hdcSrc, 
  int 
nXSrc, 
  int 
nYSrc, 
  HBITMAP 
hbmMask, 
  int 
xMask, 
  int 
yMask, 
  DWORD 
dwRop 
);

Parameters

hdcDest

[in] Handle to the destination device context.

nXDest

[in] Specifies the logical x-coordinate of the upper left corner of the destination rectangle.

nYDest

[in] Specifies the logical y-coordinate of the upper left corner of the destination rectangle.

nWidth

[in] Specifies the width, in logical units, of the destination rectangle and source bitmap.

nHeight

[in] Specifies the height, in logical units, of the destination rectangle and source bitmap.

hdcSrc

[in] Handle to the device context from which the bitmap is to be copied. It must be zero if the dwRopparameter specifies a raster operation that does not include a source.

nXSrc

[in] Specifies the logical x-coordinate of the upper left corner of the source bitmap.

nYSrc

[in] Specifies the logical y-coordinate of the upper left corner of the source bitmap.

hbmMask

[in] Handle to the monochrome mask bitmap combined with the color bitmap in the source device context.

xMask

[in] Specifies the horizontal pixel offset for the mask bitmap specified by the hbmMaskparameter.

yMask

[in] Specifies the vertical pixel offset for the mask bitmap specified by the hbmMaskparameter.

dwRop

[in] Specifies both foreground and background ternary raster operation codes that the function uses to control the combination of source and destination data.

The background raster operation code is stored in the high-order byte of the high-order word of this value. The foreground raster operation code is stored in the low-order byte of the high-order word of this value; the low-order word of this value is ignored, and should be zero.

The macro MAKEROP4creates such combinations of foreground and background raster operation codes.

For a discussion of foreground and background in the context of this function, see the following Remarks section.

For a list of common raster operation codes, see the BitBltfunction.

Windows CE 1.0 and 1.01 support only the SRCCOPYand SRCINVERTraster operations.

Return Value

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

A value of 1 in the mask specified by hbmMaskindicates that the foreground raster operation code specified by dwRopshould be applied at that location.

A value of 0 in the mask indicates that the background raster operation code specified by dwRopshould be applied at that location.

If the raster operations require a source, the mask rectangle must cover the source rectangle. If it does not, the function will fail.

If the raster operations do not require a source, the mask rectangle must cover the destination rectangle. If it does not, the function will fail.

If a rotation or shear transformation is in effect for the source device context when this function is called, an error occurs. However, other types of transformation are allowed.

If the color formats of the source, pattern, and destination bitmaps differ, this function converts the pattern or source format, or both, to match the destination format.

If the mask bitmap is not a monochrome bitmap, an error occurs.

When an enhanced metafile is being recorded, an error occurs (and the function returns FALSE) if the source device context identifies an enhanced-metafile device context.

Not all devices support the MaskBltfunction. An application should call the GetDeviceCapsfunction to determine whether a device supports this function.

If no mask bitmap is supplied, this function behaves exactly like BitBlt, using the foreground raster operation code.

Requirements

Header windows.h
Library coredll.lib
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also