If true, the BlitMask will automatically watch the target to see if its position/scale/rotation has changed on each frame (while bitmapMode is true) and if so, it will update() to make sure the BlitMask always stays synced with the target. This is the easiest way to use BlitMask but it is slightly less efficient than manually calling update() whenever you need to. Keep in mind that if you're tweening with TweenLite or TweenMax, you can simply set its onUpdate to the BlitMask's update() method to keep things synced. Like onUpdate:myBlitMask.update.

When true, the BlitMask optimizes itself for performance by setting the target's visible property to false (greatly reducing the load on Flash's graphics rendering routines) and uses its internally cached bitmap version of the target to redraw only the necessary pixels inside the masked area. Since only a bitmap version of the target is shown while in bitmapMode, the target won't be interactive. So if you have buttons and other objects that normally react to MouseEvents, they won't while in bitmapMode. If you need the interactivity, simply set bitmapMode to false and then it will turn the target's visible property back to true and its mask property to the BlitMask itself. Typically it is best to turn bitmapMode on at least when you're animating the target or the BlitMask itself, and then when the tween/animation is done and you need interactivity, set bitmapMode back to false. For example: var bm:BlitMask = new BlitMask(mc, 0, 0, 300, 200, true); TweenLite.to(mc, 3, {x:200, onUpdate:bm.update, onComplete:completeHandler}); function completeHandler():void { bm.bitmapMode = false; }

See also

The ARGB hexadecimal color that should fill the empty areas of the BlitMask. By default, it is transparent (0x00000000). If you wanted a red color, for example, it would be 0xFFFF0000.

Height of the BlitMask

Rotation of the BlitMask (always 0 because BlitMasks can't be rotated!)

scaleX (warning: altering the scaleX won't actually change its value - instead, it affects the width property accordingly)

scaleY (warning: altering the scaleY won't actually change its value - instead, it affects the height property accordingly)

Typically a value between 0 and 1 indicating the target's position in relation to the BlitMask on the x-axis where 0 is at the beginning, 0.5 is scrolled to exactly the halfway point, and 1 is scrolled all the way. This makes it very easy to animate the scroll. For example, to scroll from beginning to end over 5 seconds, you could do: myBlitMask.scrollX = 0; TweenLite.to(myBlitMask, 5, {scrollX:1});

See also

Typically a value between 0 and 1 indicating the target's position in relation to the BlitMask on the y-axis where 0 is at the beginning, 0.5 is scrolled to exactly the halfway point, and 1 is scrolled all the way. This makes it very easy to animate the scroll. For example, to scroll from beginning to end over 5 seconds, you could do: myBlitMask.scrollY = 0; TweenLite.to(myBlitMask, 5, {scrollY:1});

See also

If false (the default), the bitmap (and the BlitMask's x/y coordinates) will be rendered only on whole pixels which is faster in terms of processing. However, for the best quality and smoothest animation, set smoothing to true.

The target DisplayObject that the BlitMask should mask

Width of the BlitMask

If true, the bitmap will be wrapped around to the opposite side when it scrolls off one of the edges (only in bitmapMode of course), like the BlitMask is filled with a grid of bitmap copies of the target. Use the wrapOffsetX and wrapOffsetY properties to affect how far apart the copies are from each other. You can reposition the target anywhere and BlitMask will align the copies accordingly.

See also

When wrap is true, wrapOffsetX controls how many pixels along the x-axis the wrapped copies of the bitmap are spaced. It is essentially the gap between the copies (although you can use a negative value or 0 to avoid any gap).

See also

When wrap is true, wrapOffsetY controls how many pixels along the y-axis the wrapped copies of the bitmap are spaced. It is essentially the gap between the copies (although you can use a negative value or 0 to avoid any gap).

See also

x coordinate of the BlitMask (it will automatically be forced to whole pixel values if smoothing is false).

y coordinate of the BlitMask (it will automatically be forced to whole pixel values if smoothing is false).

Constructor

Identical to setting bitmapMode = false but this method simplifies adding that functionality to tweens or using it as an event handler. For example, to enable bitmapMode at the beginning of a tween and then disable it when the tween completes, you could do: TweenLite.to(mc, 3, {x:400, onStart:myBlitMask.enableBitmapMode, onUpdate:myBlitMask.update, onComplete:myBlitMask.disableBitmapMode});

Parameters

See also

Disposes of the BlitMask and its internal BitmapData instances, releasing them for garbage collection.

Identical to setting bitmapMode = true but this method simplifies adding that functionality to tweens or using it as an event handler. For example, to enable bitmapMode at the beginning of a tween and then disable it when the tween completes, you could do: TweenLite.to(mc, 3, {x:400, onStart:myBlitMask.enableBitmapMode, onUpdate:myBlitMask.update, onComplete:myBlitMask.disableBitmapMode});

Parameters

See also

Repositions the target so that it is visible within the BlitMask, as though wrap was enabled (this method is called automatically when bitmapMode is disabled while wrap is true). For example, if you tween the target way off the edge of the BlitMask and have wrap enabled, it will appear to come back in from the other side even though the raw coordinates of the target would indicate that it is outside the BlitMask. If you want to force the coordinates to normalize so that they reflect that wrapped position, simply call normalizePosition(). It will automatically choose the coordinates that would maximize the visible portion of the target if a seam is currently showing.

Sets the width and height of the BlitMask. Keep in mind that a BlitMask should not be rotated or scaled. You can also directly set the width or height properties.

Parameters

See also

Updates the BlitMask's internal bitmap to reflect the target's current position/scale/rotation. This is a very important method that you'll need to call whenever visual or transformational changes are made to the target so that the BlitMask remains synced with it.

Parameters

 import com.greensock.*;
 
 //create a 200x200 BlitMask positioned at x:20, y:50 to mask our "mc" object and turn smoothing on:
 var blitMask:BlitMask = new BlitMask(mc, 20, 50, 200, 200, true);
 
 //position mc at the top left of the BlitMask using the scrollX and scrollY properties
 blitMask.scrollX = 0;
 blitMask.scrollY = 0;
 
 //tween the scrollY to make mc scroll to the bottom over the course of 3 seconds and then turn off bitmapMode so that mc becomes interactive:
 TweenLite.to(blitMask, 3, {scrollY:1, onComplete:blitMask.disableBitmapMode});
 
 //or simply position mc manually and then call update() to sync the display:
 mc.x = 350;
 blitMask.update();
 
 

• BlitMasks themselves should not be rotated or scaled (although technically you can alter the scaleX and scaleY but doing so will only change the width or height instead). You can, of course, alter their x, y, width, or height properties as much as you want.
• BlitMasks don't perform nearly as well in bitmapMode when the target is being scaled or rotated because it forces a flushing and recapture of the internal bitmap. BlitMasks are MUCH better when you are simply changing x/y properties (scrolling) because it can reuse the same cached bitmap over and over.
• If the target content is changing frequently (like if it has nested MovieClips that are animating on every frame), you'd need to call update(null, true) each time you want the BlitMask to redraw itself to sync with the changes in the target, but that's a relatively expensive operation so it's not a great use case for BlitMask. You may be better off just turning off bitmapMode during that animation sequence.