|
Volume Number: | 8 | |
Issue Number: | 1 | |
Column Tag: | Pascal Workshop |
Related Info: Color Quickdraw Memory Manager
Superpaint Airbrush Masking
A plug-in for creating & using masks
By Allen Stenger, Gardena, California
Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.
Introduction
The airbrushes and spray cans included in paint programs tend to spatter areas next to the one you want to paint, making it difficult to paint neatly. Artists using real airbrushes have the same problem, but solve it with masks and shields. A mask is a piece of acetate or similar material, cut to cover the areas to be protected from paint, and pasted to the surface. The artist paints the exposed area with the airbrush, then peels away the mask. A shield is similar, but it is held in one hand (instead of being pasted down) and moved around while the other hand paints with the airbrush.
This article gives a plug-in program for creating and using masks in SuperPaint.
Taking Liberties
Our masks are implemented by the slightly devious method of saving the area under the mask, then restoring it later to “peel off” the mask. This is a kind of cut and paste, and perhaps cut and paste could be used sometimes, although it is hard to control exactly where the pasted object goes.
You define a mask using a selection tool. When SuperPaint calls the plug-in, it describes the selection as a BitMap where the bit image has 1’s in the selected pixels (like CalcMask’s output). We store this BitMap as the mask, offsetting its boundsRect so that the mask is in document coordinates. (Selections made with the selection rectangle are not described this way; we get the Rect and make our own BitMap.) You also can cut out parts of the mask; this is handled the same way, except that we use CopyBits with the srcBic transfer mode to remove the cut-out area from the saved BitMap. Capturing the image under the mask is also done with CopyBits; restoring it uses CopyMask to restore only those pixels under the mask.
One drawback of using selection tools to define the mask is that the mask is invisible! To get around this I added a “Tint Mask” command that inverts all pixels under the mask. By first capturing the area under the mask, you can then tint the mask to see where you’re painting; restoring under the mask obliterates the tint.
SuperPaint painting commands are described formally as “Black and White transformation commands,” and typically transform an area on a single call rather than building up a transform across several calls, as we do here. There’s nothing wrong with our approach, although the interface is clumsy since you must always select something (usually an area containing the mask) for each call.
Example
This is an exercise from Vero’s book. Start by making the mask, which is an outline of the drop. Draw a Bezier in the Draw layer (I start with an oval and bend it into shape). Then cut this into the Paint layer.
First draw the shadow. Select the mask with the lasso, and command Outline A Mask. Open a new window, command Capture Under Mask, then Tint Mask. (Note that the Masker does not remember which window it was in.) Use the airbrush set for 25% flow, 4 pixels and faded to paint the shadow with a 50% gray. Be sure the boundary is well-defined; keep spraying until it is thick enough. Use the Command Restore Under Mask to check your progress. Now mask the outside of the drop by going back to the mask window, selecting the window (double-click on the selection rectangle), commanding Outline A Mask, then selecting the outline with the lasso and commanding Remove From Mask. Go back to the drop window, select the entire window, and command Capture Under Mask. Fill the window with 12.5% gray, then Restore Under Mask to get the drop. Paint the highlight with white, using a horizontal blade brush (1 x 8 pixels). Lighten the bottom edge of the drop with the airbrush set for 25% flow, 8 pixels and faded. Touch up with a white brush if needed.
Possible Improvements
I’ve tried to keep this program simple and therefore easily understandable. Some additional complications that you might want to add are:
• Allow addition of areas to the mask. This was omitted because it might require adjusting the size of the BitMap bounds, but it’s not especially difficult to do. (A neater way than using BitMaps would be to represent the mask as a region, using QuickDraw routines to add to and subtract from the mask. Unfortunately, there is no standard way to convert the BitMap passed to the plug-in by SuperPaint into a region.)
• Nudge or shift a mask after creation. A little thought is needed to devise a convenient human interface for commanding this, but the operation is simple (offset the boundsRect).
• Allow the user to set the Tint pattern (e.g., as the current fill pattern, which is also passed to the plug-in by SuperPaint).
• Form the complement of a mask. In physical terms this corresponds to cutting holes from a mask and using both the mask and the cut-out portions as masks. This can be done as in the example, but it would be easier to have a new command.
Notes
These are some miscellaneous notes that may be helpful in understanding the program.
• All the Pascal files BWtc.p included in the Toolkit omit the fillPatNone and linePatNone fields, causing all later fields to be at the wrong offset. (The C and Asm files are correct.) This is corrected in the BWtc.p listing below.
• An important correspondence (not mentioned in the Toolkit documentation) is that selectRect and the GrafPort’s portRect represent the same area; selectRect is in document coordinates and portRect is in local coordinates. This correspondence allows us to map between the current selection and the document’s coordinates.
• The statement in the Toolkit documentation that the GrafPort is set to the selection is not completely correct. More accurately, the GrafPort is set to an offscreen copy of part of the document containing the selection. After the plug-in runs, SuperPaint copies the offscreen version back into the selected portion of the document.
• The lassoMaskBits record is set correctly for all selection tools other than the rectangle. The Toolkit documentation implies it is only valid for selections made with the Lasso.
[Also note, after this article was submitted, Aldus released SuperPaint 3.0 presenting two problems. The first of which is that Aldus has evidently abandoned 2.0 plug-ins by redefining the interface and providing no support for earlier interfaces. Second, 3.0 has some masking features. For the many users, who are choosing to not move to 3.0 because it is so incredibly slow, this tool is still useful. More importantly, it shows the basic methodology to using “plug-in tools”. - Ed.]
For Further Reading
If you are interested in further information on this topic, you might want to look at the following sources.
• Radu Vero, Airbrush: The Complete Studio Handbook. Watson-Guptill Publications, 1983. A good introduction to airbrush work. The example is on page 74 (exercise 14).
• Michael Ogawa, “BitMapper Utility For SuperPaint.” MacTutor, February 1990, pp. 28-40. Another example of a paint com-mand for SuperPaint. One of three related articles in this issue.
• “SuperPaint Plug-In Developer’s Toolkit.” Distributed by Silicon Beach. Send $15 to Silicon Beach Software, Inc., P.O. Box 262460, Dept. 20, San Diego, CA 92126. One disk, containing much documentation, source files defining the interfaces, and examples.
• Macintosh Technical Note #193, “So Many Bitmaps, So Little Time,” December 1989. Describes a new trap, BitMapToRegion, which is included in 32-bit QuickDraw and available separately under license from Apple. The trap is also described in Inside Macintosh, v. VI, p. 17-25.
• Ted Cohn, “Convert PICTs to Regions.” MacTutor, June 1989 (reprinted in Best of MacTutor v. 5, pp. 11-16). Gives routines for converting BitMaps and PICTs to regions.
About the author
Allen Stenger is a programmer for a large metropolitan radar house. He may be reached on AppleLink at “STENGER”.
Source Listings
Your first step is to set up a new THINK Pascal project that should look like the one in Figure 1.
Figure 1: THINK Pascal Project Window
Remember, you are writing a code resource here, so you will need to set the project type as in Figure 2.
Figure 2: Set Project Type Dialog
Listing: BWtc.p {File: BWtc.p} {COPYRIGHT © 1989 Silicon Beach Software, Inc.} {All Rights Reserved} { Modified by Allen Stenger, July 1991, to add } { missing fields fillPatNone, linePatNone } unit BWtc; interface const PaintOpaque = patCopy; PaintTransparent = patOr; PaintOnBlack = notPatBic; InvertPaint = patXor; { toolAbout return codes } noAbout = 1; textAbout = 2; {Command codes} menuAbout = 0; menuOptions = 10; menuSelected = 11; verNum = $0001; type MenuOptionsRec = record UsesScratch: boolean; end; MenuOptionsPtr = ^MenuOptionsRec; MenuDataRec = record toolID: integer; spare1: integer; spare2: integer; spare3: integer; spare4: integer; spare5: integer; spare6: integer; spare7: integer; shiftIsDown: boolean; cmdIsDown: boolean; optIsDown: boolean; spareFlag: boolean; fillPatNone: boolean; linePatNone: boolean; subMenu: MenuHandle; MenuItem: integer; scratchBits: BitMap; lassoMaskBits: BitMap; undoBits: BitMap; { ptr to undo bits } selectRect: Rect; { selection rectangle } { in document coords } curFillPat: Pattern;{ cur fill pattern } curPatList: Handle; { handle to currently } { selected pattern list} end; MenuDataPtr = ^MenuDataRec; implementation end.
Listing: Masker.p {----------------------- } {} {Airbrush masker for SuperPaint 2.0a } {} {Written in THINK Pascal version 3.0.2 } {} {Allen Stenger July 1991} {} {----------------------- } unit Masker; interface uses BWtc; const { returnCode values for errors (we return any } { Memory Manager error codes as themselves) } BadSelector = 1; { bad selector value } InvalidSubMenu = 2; { unimplemented submenu } { selection } MaskNotInSelection = 3; { attempt mask } { operation with mask not } { totally in selection } { equates for submenu selections } OutlineAMask = 1; { make current selection the } { mask } RemoveFromMask = 2; { remove cur selection } { from mask } { separator line = 3 } CaptureUnderMask = 4; { save portion of } { document under mask } RestoreUnderMask = 5; { restore saved data } { to document } { separator line = 6 } TintMask = 7 { tint mask area so we can } { see it } ForgetMask = 8; { discard all mask and saved } { data } type SaveArea = record { area saved by SuperPaint } { for us as globalData^^ } MaskBitMap: BitMap; { the mask, a BitMap, } { always maintained in } { document coordinates } SavedBitMap: BitMap;{ saved part of orig } { image, always maintained } { in document coordinates } Tinted: Boolean;{ mask currently tinted? } end; SaveAreaPtr = ^SaveArea; SaveAreaHandle = ^SaveAreaPtr; procedure Main (selector: integer; mDataPtr: MenuDataPtr; var globalData: SaveAreaHandle; var returnCode: integer); implementation procedure Main; { look up the save area preserved by SuperPaint, } { or create a new one if none } function GetSaveArea: OSErr; var ourReturnCode: OSErr; {holds value for GetSaveArea} begin ourReturnCode := noErr; if globalData = nil then begin globalData := SaveAreaHandle(NewHandle(sizeof(SaveArea))); ourReturnCode := MemError; if ourReturnCode = noErr then with globalData^^, globalData^^.MaskBitMap do begin baseAddr := nil; rowBytes := 0; SetRect(bounds, 0, 0, 0, 0); SavedBitMap := MaskBitMap; Tinted := false; end; end; {if globalData} GetSaveArea := ourReturnCode; end; {GetSaveArea} { release save area and storage it references } function DisposSaveArea: OSErr; var ourReturnCode: OSErr; { holds function val } begin ourReturnCode := noErr; if globalData <> nil then begin with globalData^^.MaskBitMap do if baseAddr <> nil then begin DisposPtr(baseAddr); ourReturnCode := MemError; end; with globalData^^.SavedBitMap do if (ourReturnCode = noErr) and (baseAddr <> nil) then begin DisposPtr(baseAddr); ourReturnCode := MemError end; if ourReturnCode = noErr then begin DisposHandle(Handle(globalData)); ourReturnCode := MemError end; end; globalData := nil; DisposSaveArea := ourReturnCode; end; {DisposSaveArea} { Create a bit mask in outRect within the new } { BitMap outBitMap by copying the mask in inRect } { within inBitMap; or by filling outRect if } { inBitMap is null.} function CopyBitMask (inBitMap: BitMap; var outBitMap: BitMap; inRect, outRect: Rect): OSErr; var ourReturnCode: OSErr; { holds value of } { CopyBitMask} il: longint; { loop control } bitsSize: longint;{ size of bit array in } { bytes } byteP: PTR;{ temporary byte ptr } begin { make a new BitMap the right size to hold the mask } outBitMap.bounds := outRect; with outBitMap, outBitMap.bounds do begin rowBytes := ((right - left + 7) div 8 + 1) div 2 * 2; bitsSize := rowBytes * LONGINT(bottom - top); baseAddr := NewPtr(bitsSize); ourReturnCode := MemError; end; { blit the mask into the new BitMap } if ourReturnCode = noErr then if inBitMap.baseAddr <> nil then with outBitMap, outBitMap.bounds do CopyBits(inBitMap, outBitMap, inRect, bounds, srcCopy, nil) else with outBitMap do for il := 0 to bitsSize - 1 do begin byteP := PTR(ORD(baseAddr) + il); byteP^ := 255; end; {for il} CopyBitMask := ourReturnCode; end; {CopyBitMask} { convert r from Document to GrafPort (local) } { coordinates } procedure DocToGraf (r: Rect; gPtr: GrafPtr); begin with mDataPtr^, gPtr^ do OffsetRect(r, -(selectRect.left - portRect.left), -(selectRect.top - portRect.top)); end; {DocToGraf} { Flip (i.e. XOR) the tint of the mask } procedure FlipTint (gPtr: GrafPtr); var workRect: Rect; { temp Rectangle } begin workRect := globalData^^.MaskBitMap.bounds; DocToGraf(workRect, gPtr); CopyBits(globalData^^.MaskBitMap, gPtr^.portBits, globalData^^.MaskBitMap.bounds, workRect, srcXor, nil); end; {FlipTint} { execute the desired action from the menu } procedure TakeAction; var i: integer;{ loop control } gPtr: GrafPtr; { points to current } { GrafPort } workRect: Rect; { temporary working } { rectangle } bitsSize: longint;{ size of bit array } { in bytes } workBitMap: BitMap; { temporary bit map } trashB: Boolean;{ temporary Boolean } begin GetPort(gPtr); case mDataPtr^.menuItem of OutlineAMask, ForgetMask: begin returnCode := DisposSaveArea; if returnCode = noErr then returnCode := GetSaveArea end; otherwise returnCode := GetSaveArea; end; {case mDataPtr^.menuItem} if returnCode = noErr then case mDataPtr^.menuItem of OutlineAMask: begin returnCode := CopyBitMask(mDataPtr^.lassoMaskBits, globalData^^.MaskBitMap, gPtr^.portRect, mDataPtr^.selectRect); end; {OutlineAMask} RemoveFromMask: begin returnCode := CopyBitMask(mDataPtr^.lassoMaskBits, workBitMap, gPtr^.portRect, mDataPtr^.selectRect); if returnCode = noErr then begin workRect := workBitMap.bounds; if globalData^^.Tinted then FlipTint(gPtr); { remove Tint where } { mask will be removed} CopyBits(workBitMap, globalData^^.MaskBitMap, workRect, workRect, srcBic, nil); DisposPtr(workBitMap.baseAddr); returnCode := MemError; workBitMap.baseAddr := nil; end {if returnCode} end; {RemoveFromMask} CaptureUnderMask: begin { Quick and dirty check to see } {if user’s selection includes the mask area. } { A better check would check that all } { bits in MaskBitMap are in lassoMaskBits. } trashB := SectRect(mDataPtr^.selectRect, globalData^^.MaskBitMap.bounds, workRect); if not EqualRect(workRect, globalData^^.MaskBitMap.bounds) then returnCode := MaskNotInSelection else begin with globalData^^, globalData^^.SavedBitMap do begin if baseAddr <> nil then DisposPtr(baseAddr);{ discard any } { previous capture } SavedBitMap := MaskBitMap; baseAddr := NewPtr(GetPtrSize(MaskBitMap.baseAddr)); returnCode := MemError; if returnCode = noErr then begin workRect := bounds; DocToGraf(workRect, gPtr); CopyBits(gPtr^.portBits, SavedBitMap, workRect, bounds, srcCopy, nil); end; {if returnCode} end; {with globalData^^} end; {if not EqualRect} end; {CaptureUnderMask} RestoreUnderMask: begin workRect := globalData^^.SavedBitMap.bounds; DocToGraf(workRect, gPtr); with globalData^^, gPtr^ do CopyMask(SavedBitMap, MaskBitMap, portBits, SavedBitMap.bounds, MaskBitMap.bounds, workRect); globalData^^.Tinted := false;{we obliterated tint} returnCode := noErr; end; {RestoreUnderMask} TintMask: begin FlipTint(gPtr); with globalData^^ do Tinted := not Tinted; returnCode := noErr; end; {TintMask} ForgetMask: begin returnCode := noErr; end; {ForgetMask} otherwise returnCode := InvalidSubMenu; end; {case mDataPtr^.subMenu} end; {TakeAction} { update valid menu selections } procedure UpdateMenu; begin with globalData^^, mDataPtr^ do begin if MaskBitMap.baseAddr = nil then begin DisableItem(subMenu, RemoveFromMask); DisableItem(subMenu, CaptureUnderMask); DisableItem(subMenu, TintMask); DisableItem(subMenu, ForgetMask) end else begin EnableItem(subMenu, RemoveFromMask); EnableItem(subMenu, CaptureUnderMask); EnableItem(subMenu, TintMask); EnableItem(subMenu, ForgetMask) end; if SavedBitMap.baseAddr = nil then DisableItem(subMenu, RestoreUnderMask) else EnableItem(subMenu, RestoreUnderMask); if Tinted then DisableItem(subMenu, CaptureUnderMask); CheckItem(subMenu, TintMask, Tinted); end; {with globalData^^} end; {UpdateMenu} begin {Main} case selector of menuAbout: begin returnCode := textAbout; {our About is in TEXT resource} end; menuOptions: begin MenuOptionsPtr(mDataPtr)^.usesScratch := false; {we don’t use scratch area} returnCode := noErr; end; menuSelected: begin TakeAction; UpdateMenu; if returnCode <> noErr then SysBeep(1); { SuperPaint doesn’t notify user of error, } { so we will} end; otherwise begin returnCode := BadSelector end; end; {case selector of} end; {Main} end.
Listing: Masker.r /*------------------------------------------- */ /* Resource definition file (Rez) for Masker */ /* Allen Stenger July 1991 */ /*------------------------------------------- */ /* This SICN appears in the About plug-in list. */ resource ‘SICN’ (16000, purgeable) { { /* array: 1 elements */ /* [1] */ $”0780 1FE0 3870 E01C 8004 BFF4 E31C EB5C” $”A314 BFF4 8004 8004 8004 FFFC 1860 1860” } }; /* This resource defines the interface version */ data ‘PiMI’ (16000, purgeable, preload) { $”0001” }; /* This menu is shown an a hierarchical menu to */ /* the Masker command. */ resource ‘MENU’ (16000, purgeable) { 128, textMenuProc, 0x7FFFFF01, enabled, “Masker”, { /* array: 8 elements */ /* [1] */ “Outline a Mask”, noIcon, noKey, noMark, plain, /* [2] */ “Remove from Mask”, noIcon, noKey, noMark, plain, /* [3] */ “-”, noIcon, noKey, noMark, plain, /* [4] */ “Capture under Mask”, noIcon, noKey, noMark, plain, /* [5] */ “Restore under Mask”, noIcon, noKey, noMark, plain, /* [6] */ “-”, noIcon, noKey, noMark, plain, /* [7] */ “Tint Mask”, noIcon, noKey, noMark, plain, /* [8] */ “Forget Mask”, noIcon, noKey, noMark, plain } }; /* This text is shown as the About info for Masker. */ data ‘TEXT’ (16000, “About ”, purgeable) { “Masker Menu Command - Written by Allen “ “Stenger, July 1991\n\n” “Use this command to protect an area from “ “being painted over. The steps are:\n” “ 1. Define the “mask” by selecting the “ “area to be protected with any of the “ “selection tools, then command Outline “ “A Mask. Pieces may then be cut from the “ “mask by selecting them and commanding “ “Remove From Mask.\n” “ 2. Save the area under the mask by “ “selecting an area containing the mask “ “and commanding Capture Under Mask.\n” “ 3. Paint as desired.\n” “ 4. Restore the area under the mask by “ “selecting an area containing the mask “ “and commanding Restore Under Mask.\n\n” “The Tint Mask command tints the mask “ “so it can be seen. Issue Tint Mask “ “again to remove the tint. Capture “ “is disabled while Tint is on, to “ “prevent the tint from being captured too.\n\n” “The Forget Mask command is not normally “ “needed, since Outline A Mask will clear “ “the previous mask; it may be used to “ “release the memory occupied by a mask.\n\n” “Menu commands can only work on areas “ “within the current selection, so be sure “ “the entire area of the mask is selected “ “before Tint, Capture, or Restore.” };
- SPREAD THE WORD:
- Slashdot
- Digg
- Del.icio.us
- Newsvine