Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 3 - QuickDraw Drawing / QuickDraw Drawing Reference

Routines / Copying Images

CopyMask

You can use the CopyMask procedure to copy a bit or pixel image from one graphics port (or offscreen graphics world) into another graphics port only where the bits in a mask are set to 1.

PROCEDURE CopyMask (srcBits,maskBits,dstBits: BitMap; 
                    srcRect,maskRect,dstRect:\xDDRect);

srcBits

The source BitMap record.

maskBits

The mask 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.

DESCRIPTION

The CopyMask procedure copies the source bitmap or pixel map that you specify in the srcBits parameter to a destination bitmap or pixel map that you specify in the dstBits parameter--but only where the bits of the mask bitmap or pixel map that you specify in the maskBits parameter are set to 1. When copying images between color graphics ports, you must coerce each 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.

Using the srcRect and dstRect parameters, you can specify identically or differently sized source and destination rectangles; for differently sized rectangles, CopyMask 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 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 specify pixel maps to CopyMask, 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

Calls to CopyMask 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 CopyMask.

The CopyMask procedure may move or purge memory blocks in the application heap. Your application should not call this procedure at interrupt time.

SEE ALSO

You can use the bitmap returned by the CalcMask procedure, described on page 3-106, as the mask in order to implement a mask copy similar to that performed by the MacPaint lasso tool. In the same way, you could use the pixel map returned by the CalcCMask procedure, described in the chapter "Color QuickDraw."

The chapter "Color QuickDraw" describes in more detail how to use CopyMask in a Color QuickDraw environment. Plate 3 at the front of this book illustrates how to use different colors in the mask to produce different effects in the destination pixel map; Listing 6-2 on page 6-10 in the chapter "Offscreen Graphics Worlds" shows the code that produced this plate. Plate 4 at the front of this book provides another illustration of the effects of the source and mask pixel maps on the destination pixel map.

The CopyDeepMask procedure (described next) combines the functions of the CopyMask and CopyBits procedures.