Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Imaging With QuickDraw /

Chapter 3 - QuickDraw Drawing / QuickDraw Drawing Reference

CopyDeepMask
To use a mask when copying bitmaps or pixel maps between graphics ports (or from an offscreen graphics world into a graphics port), you can use the CopyDeepMask procedure, which combines the effects of the CopyBits and CopyMask procedures.
PROCEDURE CopyDeepMask  (srcBits: BitMap; maskBits: BitMap; 
                         dstBits: BitMap; srcRect: Rect; 
                         maskRect: Rect; dstRect: Rect; 
                         mode: Integer; maskRgn: RgnHandle);
srcBits
The source BitMap record.
maskBits
The masking BitMap record.
dstBits
The destination BitMap record.
srcRect
The source rectangle.
maskRect
The mask rectangle. This must be the same size as the rectangle passed in the srcRect parameter.
dstRect
The destination rectangle.
mode
The source mode.
maskRgn
The mask clipping region.

DESCRIPTION
The CopyDeepMask procedure transfers a bitmap between two basic graphics ports or a pixel map between two color graphics ports. You specify a mask to CopyDeepMask so that it transfers the source image to the destination image only where the bits of the mask are set to 1. You can use CopyDeepMask to move offscreen graphic images into an onscreen window, to blend colors for the image in a pixel map, and to shrink and expand images.
Specify a source bitmap in the srcBits parameter and a destination bitmap in the dstBits parameter. Specify a mask in the maskBits parameter. When copying images between color graphics ports, you must coerce each port's CGrafPort record to a GrafPort record, dereference the portBits fields of each, and then pass these "bitmaps" in the srcBits and dstBits parameters. If your application copies a pixel image from a color graphics port called MyColorPort, for example, you could specify GrafPtr(MyColorPort)^.portBits in the srcBits parameter. The transfer can be performed in any of the transfer modes--with or without adding the ditherCopy constant--that are available to the CopyBits procedure, described beginning on page 3-108.
Using the srcRect and dstRect parameters, you can specify identically or differently sized source and destination rectangles; for differently sized rectangles, CopyDeepMask scales the source image to fit the destination. When you specify rectangles in the srcRect and dstRect parameters, use the local coordinate systems of, respectively, the source and destination graphics ports.
The result (in the parameter dstBits) is clipped to the mask region that you specify in the maskRgn parameter, and to the boundary rectangle that you specify in the dstRect parameter. The rectangle you pass in the maskRect parameter selects the portion of the bitmap or pixel map that you specify in the maskBits parameter to use as the mask. If you don't want to clip to the mask region, specify NIL in the maskRgn parameter.
If you specify pixel maps to CopyDeepMask, they may range from 1 to 32 pixels in depth. The pixel depth of the mask that you specify in the maskBits parameter is applied as a filter between the source and destination pixel maps that you specify in the srcBits and dstBits parameters. A black mask pixel value means that the copy operation is to take the source pixel; a white value means that the copy operation is to take the destination pixel. Intermediate values specify a weighted average, which
is calculated on a color component basis. For each pixel's color component value, the calculation is
(1 - mask) source + (mask) destination
Thus high mask values for a pixel's color component reduce that component's contribution from the source PixMap record.

SPECIAL CONSIDERATIONS
This procedure is available to basic QuickDraw only in System 7.
As with the CopyMask procedure, calls to CopyDeepMask are not recorded in pictures and do not print.
See the list of special considerations for the CopyBits procedure beginning on page 3-113; these considerations also apply to CopyDeepMask.
The CopyDeepMask procedure may move or purge memory blocks in the application heap. Your application should not call this procedure at interrupt time.

SEE ALSO
The chapter "Color QuickDraw" describes in more detail how to use CopyDeepMask in a Color QuickDraw environment.