SelectMask -- select a mask as output device (V2.0)
SelectMask(id[, type, frame])
This function selects the mask of the graphics object specified by id as the current output device. This means that all graphics data that are output by Hollywood will be drawn to this mask. Masks are no stand-alone objects in Hollywood; they are always connected to an image object, for example a brush or an animation.

By default, SelectMask() always works with the masks of brushes. However, starting with Hollywood 4.5, you can also use it to draw to the masks of animations and BGPics. To do this you have to specify #ANIM or #BGPIC in the optional type argument. If you specify #ANIM in type, you have to specify the frame of the animation that you want to draw to, too. See SelectAnim() for more information. If you specify #BGPIC in type, note that you can only modify the masks of BGPics that are currently not associated with a display. Starting with Hollywood 4.7, you can also pass #LAYER as the type to modify the mask of a layer. Note that if the layer is an anim layer, you will also have to specify the number of the frame to select.

Masks are used to control the transparency of a graphics object. They do not carry any color information. Every pixel in a mask can only have two different states: 1, which means that this pixel is visible and 0, which means that the pixel is invisible. Therefore you need to tell Hollywood whether or not the drawing commands should draw visible pixels (1) or invisible pixels (0) to the mask. This is done by using the SetMaskMode() command. The color argument that several Hollywood functions (like Box() or Circle()) expect, is superfluous when rendering to masks. You only need to use SetMaskMode().

If the graphics object you specify in id does not have a mask yet, it will be automatically created when you call a command that wants to draw to the mask. If a mask is created by SelectMask(), it will initially be fully opaque.

To cancel mask rendering mode and return to main display output, just call the EndSelect() function.

If you do not need a mask any longer, you can remove it from a brush by calling SetBrushTransparency() with the argument #NOTRANSPARENCY. Or simply use DeleteMask().

You cannot use brush links with this command because the graphics data of the brush specified by id will be changed. It is also forbidden to call commands which change the dimensions of the brush/anim that is currently used as output device, e.g. you may not call ScaleBrush() or ScaleAnim() to scale the brush/anim that is currently the output device. Furthermore, it is not allowed to call SelectMask() for animations that are loaded from disk. Animations must always reside completely in memory if you want to draw to their frames using SelectMask().

Only commands that output graphics directly can be used after SelectMask(). You may not call animated functions like MoveBrush() or DisplayBrushFX() while SelectMask() is active.

Please note that graphics objects cannot have a mask and an alpha channel. Only one transparency setting is possible. Thus, if you use this command on an object that already has an alpha channel, this alpha channel will be deleted.

If you are using type #LAYER and the specified layer is a vector layer, SelectMask() will rasterize the layer to a brush layer first. See SelectLayer for details.

graphics object whose mask shall be used as output device
optional: type of the graphics object specified in id; can be #BRUSH, #ANIM, #BGPIC, or #LAYER (defaults to #BRUSH) (V4.5)
optional: animation frame to use; only required if type is set to #ANIM or if #LAYER is used on an anim layer (V4.5)
w = GetAttribute(#BRUSH, 1, #ATTRWIDTH)
h = GetAttribute(#BRUSH, 1, #ATTRHEIGHT)

SelectMask(1)               ; select mask as output device
SetMaskMode(#MASKINVISIBLE) ; all calls will draw invisible pixels now
Cls                         ; clear all pixels
SetMaskMode(#MASKVISIBLE)   ; all calls will draw visible pixels now
Box(0, 0, w, h, 0, 20)      ; draw a rectangle with rounded edges
EndSelect                   ; select display as output device again
The code above renders a rectangle with rounded edges to the mask of brush 1. When you display brush 1 now, it will appear with rounded edges.

Show TOC