Package | com.greensock |
Class | public class BlitMask |
Inheritance | BlitMask flash.display.Sprite |
bitmapMode
can be turned off to restore interactivity in the DisplayObject
whenever you want. When scrolling very large images or text blocks, a BlitMask can greatly improve
performance, especially on mobile devices that have weaker processors.
Here are some of the conveniences BlitMask offers:
update()
the BlitMask and it syncs the pixels.
The BlitMask basically sits on top of the DisplayObject in the display list and you can
move it independently too if you want.scrollX
and scrollY
properties to move the
target DisplayObject inside the masked area. For example, to scroll from top to bottom over
the course of 2 seconds, simply do: myBlitMask.scrollY = 0;
TweenLite.to(myBlitMask, 2, {scrollY:1});
bitmapMode
of course), as though the BlitMask is
filled with a grid of bitmap copies of the target.smoothing
to false
or
for maximum quality, set it to true
bitmapMode
to get either maximum performance or interactivity
in the target DisplayObject anytime. (some other solutions out there are only viable for
non-interactive bitmap content) Property | Defined By | ||
---|---|---|---|
autoUpdate : Boolean
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. | BlitMask | ||
bitmapMode : Boolean
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. | BlitMask | ||
fillColor : uint
The ARGB hexadecimal color that should fill the empty areas of the BlitMask. | BlitMask | ||
height : Number [override] Height of the BlitMask | BlitMask | ||
rotation : Number [override] [write-only] Rotation of the BlitMask (always 0 because BlitMasks can't be rotated!) | BlitMask | ||
scaleX : Number [override] scaleX (warning: altering the scaleX won't actually change its value - instead, it affects the width property accordingly) | BlitMask | ||
scaleY : Number [override] scaleY (warning: altering the scaleY won't actually change its value - instead, it affects the height property accordingly) | BlitMask | ||
scrollX : Number
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. | BlitMask | ||
scrollY : Number
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. | BlitMask | ||
smoothing : Boolean
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. | BlitMask | ||
target : DisplayObject The target DisplayObject that the BlitMask should mask | BlitMask | ||
width : Number [override] Width of the BlitMask | BlitMask | ||
wrap : Boolean
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. | BlitMask | ||
wrapOffsetX : Number
When wrap is true, wrapOffsetX controls how many pixels
along the x-axis the wrapped copies of the bitmap are spaced. | BlitMask | ||
wrapOffsetY : Number
When wrap is true, wrapOffsetY controls how many pixels
along the y-axis the wrapped copies of the bitmap are spaced. | BlitMask | ||
x : Number [override] x coordinate of the BlitMask (it will automatically be forced to whole pixel values if smoothing is false). | BlitMask | ||
y : Number [override] y coordinate of the BlitMask (it will automatically be forced to whole pixel values if smoothing is false). | BlitMask |
Method | Defined By | ||
---|---|---|---|
BlitMask(target:DisplayObject, x:Number = 0, y:Number = 0, width:Number = 100, height:Number = 100, smoothing:Boolean = false, autoUpdate:Boolean = false, fillColor:uint = 0x00000000, wrap:Boolean = false)
Constructor
| BlitMask | ||
disableBitmapMode(event:Event = null):void
Identical to setting bitmapMode = false but this method simplifies adding that
functionality to tweens or using it as an event handler. | BlitMask | ||
dispose():void Disposes of the BlitMask and its internal BitmapData instances, releasing them for garbage collection. | BlitMask | ||
enableBitmapMode(event:Event = null):void
Identical to setting bitmapMode = true but this method simplifies adding that
functionality to tweens or using it as an event handler. | BlitMask | ||
normalizePosition():void
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). | BlitMask | ||
setSize(width:Number, height:Number):void
Sets the width and height of the BlitMask. | BlitMask | ||
update(event:Event = null, forceRecaptureBitmap:Boolean = false):void
Updates the BlitMask's internal bitmap to reflect the target's current position/scale/rotation. | BlitMask |
autoUpdate | property |
autoUpdate:Boolean
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
.
public function get autoUpdate():Boolean
public function set autoUpdate(value:Boolean):void
bitmapMode | property |
bitmapMode:Boolean
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;
}
public function get bitmapMode():Boolean
public function set bitmapMode(value:Boolean):void
See also
fillColor | property |
fillColor:uint
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
.
public function get fillColor():uint
public function set fillColor(value:uint):void
height | property |
height:Number
[override] Height of the BlitMask
public function get height():Number
public function set height(value:Number):void
rotation | property |
rotation:Number
[write-only] [override] Rotation of the BlitMask (always 0 because BlitMasks can't be rotated!)
public function set rotation(value:Number):void
scaleX | property |
scaleX:Number
[override] scaleX (warning: altering the scaleX won't actually change its value - instead, it affects the width
property accordingly)
public function get scaleX():Number
public function set scaleX(value:Number):void
scaleY | property |
scaleY:Number
[override] scaleY (warning: altering the scaleY won't actually change its value - instead, it affects the height
property accordingly)
public function get scaleY():Number
public function set scaleY(value:Number):void
scrollX | property |
scrollX:Number
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});
public function get scrollX():Number
public function set scrollX(value:Number):void
See also
scrollY | property |
scrollY:Number
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});
public function get scrollY():Number
public function set scrollY(value:Number):void
See also
smoothing | property |
smoothing:Boolean
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
.
public function get smoothing():Boolean
public function set smoothing(value:Boolean):void
target | property |
target:DisplayObject
The target DisplayObject that the BlitMask should mask
public function get target():DisplayObject
public function set target(value:DisplayObject):void
width | property |
width:Number
[override] Width of the BlitMask
public function get width():Number
public function set width(value:Number):void
wrap | property |
wrap:Boolean
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.
public function get wrap():Boolean
public function set wrap(value:Boolean):void
See also
wrapOffsetX | property |
wrapOffsetX:Number
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).
public function get wrapOffsetX():Number
public function set wrapOffsetX(value:Number):void
See also
wrapOffsetY | property |
wrapOffsetY:Number
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).
public function get wrapOffsetY():Number
public function set wrapOffsetY(value:Number):void
See also
x | property |
x:Number
[override] x coordinate of the BlitMask (it will automatically be forced to whole pixel values if smoothing
is false
).
public function get x():Number
public function set x(value:Number):void
y | property |
y:Number
[override] y coordinate of the BlitMask (it will automatically be forced to whole pixel values if smoothing
is false
).
public function get y():Number
public function set y(value:Number):void
BlitMask | () | Constructor |
public function BlitMask(target:DisplayObject, x:Number = 0, y:Number = 0, width:Number = 100, height:Number = 100, smoothing:Boolean = false, autoUpdate:Boolean = false, fillColor:uint = 0x00000000, wrap:Boolean = false)
Constructor
Parameterstarget:DisplayObject — The DisplayObject that will be masked by the BlitMask
| |
x:Number (default = 0 ) — x coorinate of the upper left corner of the BlitMask. If smoothing is false , the x coordinate will be rounded to the closest integer.
| |
y:Number (default = 0 ) — y coordinate of the upper right corner of the BlitMask
| |
width:Number (default = 100 ) — width of the BlitMask (in pixels)
| |
height:Number (default = 100 ) — height of the BlitMask (in pixels)
| |
smoothing:Boolean (default = false ) — 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 .
| |
autoUpdate:Boolean (default = false ) — 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 .
| |
fillColor:uint (default = 0x00000000 ) — 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 .
| |
wrap:Boolean (default = false ) — 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.
|
disableBitmapMode | () | method |
public function disableBitmapMode(event:Event = null):void
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
event:Event (default = null ) — An optional Event that isn't used internally but makes it possible to use the method as an event handler like addEventListener(MouseEvent.CLICK, myBlitMask.disableBitmapMode) .
|
See also
dispose | () | method |
public function dispose():void
Disposes of the BlitMask and its internal BitmapData instances, releasing them for garbage collection.
enableBitmapMode | () | method |
public function enableBitmapMode(event:Event = null):void
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
event:Event (default = null ) — An optional Event that isn't used internally but makes it possible to use the method as an event handler like addEventListener(MouseEvent.CLICK, myBlitMask.enableBitmapMode) .
|
See also
normalizePosition | () | method |
public function normalizePosition():void
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.
setSize | () | method |
public function setSize(width:Number, height:Number):void
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
width:Number — The width of the BlitMask
| |
height:Number — The height of the BlitMask
|
See also
update | () | method |
public function update(event:Event = null, forceRecaptureBitmap:Boolean = false):void
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
event:Event (default = null ) — An optional Event object (which isn't used at all internally) in order to make it easier to use update() as an event handler. For example, you could addEventListener(Event.ENTER_FRAME, myBlitMask.update) to make sure it is updated on every frame (although it would be more efficient to simply set autoUpdate to true in this case).
| |
forceRecaptureBitmap:Boolean (default = false ) — Normally, the cached bitmap of the target is only recaptured if its scale or rotation changed because doing so is rather processor-intensive, but you can force a full update (and regeneration of the cached bitmap) by setting forceRecaptureBitmap to true .
|
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();
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.