EaselJS

EaselJS  0.5.0

EaselJS > EaselJS > SpriteSheetBuilder
Search:
 
Filters

Class SpriteSheetBuilder

The SpriteSheetBuilder allows you to generate sprite sheets at run time from any display object. This can allow you to maintain your assets as vector graphics (for low file size), and render them at run time as sprite sheets for better performance.

Sprite sheets can be built either synchronously, or asynchronously, so that large sprite sheets can be generated without locking the UI.

Note that the "images" used in the generated sprite sheet are actually canvas elements, and that they will be sized to the nearest power of 2 up to the value of maxWidth or maxHeight.

Constructor

SpriteSheetBuilder ( )

Properties

_animations - protected Array


_callback - protected Function


_data - protected Array


_frames - protected Array


_index - protected Number


_nextFrameIndex - protected Number


_scale - protected Number


_timerID - protected Number


_timeSlice - protected Number


defaultScale - Number

The scale to apply when drawing all frames to the sprite sheet. This is multiplied against any scale specified in the addFrame call. This can be used, for example, to generate a sprite sheet at run time that is tailored to the a specific device resolution (ex. tablet vs mobile).
Default Value: 1

maxHeight - Number

The maximum height for the images (not individual frames) in the generated sprite sheet. It is recommended to use a power of 2 for this value (ex. 1024, 2048, 4096). If the frames cannot all fit within the max dimensions, then additional images will be created as needed.
Default Value: 2048

maxWidth - Number

The maximum width for the images (not individual frames) in the generated sprite sheet. It is recommended to use a power of 2 for this value (ex. 1024, 2048, 4096). If the frames cannot all fit within the max dimensions, then additional images will be created as needed.
Default Value: 2048

padding - Number

The padding to use between frames. This is helpful to preserve antialiasing on drawn vector content.
Default Value: 1

spriteSheet - SpriteSheet

The sprite sheet that was generated. This will be null before a build is completed successfully.

Methods

_drawNext

protected _drawNext ( )

_endBuild

protected void _endBuild ( )
Returns: void

_fillRow

protected Number _fillRow ( )
Returns: Number
The width & height of the row.

_run

protected void _run ( )
Returns: void

_startBuild

protected void _startBuild ( )
Returns: void

addFrame

Number addFrame ( source , sourceRect , scale , setupFunction , setupParams , setupScope )
Adds a frame to the sprite sheet. Note that the frame will not be drawn until you call build. The optional setup params allow you to have a function run immediately before the draw occurs. For example, this allows you to add a single source multiple times, but manipulate it or it's children to change it to generate different frames.

Note that the source's transformations (x,y,scale,rotate,alpha) will be ignored, except for regX/Y. To apply transforms to a source object and have them captured in the sprite sheet, simply place it into a Container and pass in the Container as the source.
Parameters:
source <DisplayObject> The source display object to draw as the frame.
sourceRect <Rectangle> Optional. A rectangle defining the portion of the source to draw to the frame. If not specified, it will look for a getBounds method, bounds property, or nominalBounds property on the source to use. If one is not found, the frame will be skipped.
scale <Number> Optional. The scale to draw this frame at. Default is 1.
setupFunction <Function> Optional. A function to call immediately before drawing this frame.
setupParams <Array> Optional. Parameters to pass to the setup function.
setupScope <Object> Optional. The scope to call the setupFunction in.
Returns: Number
The index of the frame that was just added, or null if a sourceRect could not be determined.

addMovieClip

void addMovieClip ( source , sourceRect , scale )
This will take a MovieClip, and add its frames and labels to this builder. Labels will be added as an animation running from the label index to the next label. For example, if there is a label named "foo" at frame 0 and a label named "bar" at frame 10, in a MovieClip with 15 frames, it will add an animation named "foo" that runs from frame index 0 to 9, and an animation named "bar" that runs from frame index 10 to 14.

Note that this will iterate through the full MovieClip with actionsEnabled set to false, ending on the last frame.
Parameters:
source <MovieClip> The source MovieClip to add to the sprite sheet.
sourceRect <Rectangle> Optional. A rectangle defining the portion of the source to draw to the frame. If not specified, it will look for a getBounds method, frameBounds array, bounds property, or nominalBounds property on the source to use. If one is not found, the MovieClip will be skipped.
scale <Number> Optional. The scale to draw the movie clip at. Default is 1.
Returns: void

build

build ( )
Builds a SpriteSheet instance based on the current frames.

buildAsync

void buildAsync ( callback , timeSlice )
Asynchronously builds a SpriteSheet instance based on the current frames. It will run 20 times per second, using an amount of time defined by timeSlice. When it is complete it will call the specified callback.
Parameters:
callback <Function> Optional. The function to call when the build operation completes. It will be called with a single parameter providing a reference back to the builder.
timeSlice <Number> Optional. A number from 0.01 to 1 that indicates what percentage of time the builder can use. This can be thought of as the number of seconds per second the builder will use. For example, with a timeSlice value of 0.3, the builder will run 20 times per second, using approximately 15ms per build (30% of available time, or 0.3s per second). Defaults to 0.3.
Returns: void

clone

void clone ( )
SpriteSheetBuilder instances cannot be cloned.
Returns: void

initialize

protected void initialize ( )
Initialization method.
Returns: void

stopAsync

void stopAsync ( )
Stops the current asynchronous build.
Returns: void

toString

String toString ( )
Returns a string representation of this object.
Returns: String
a string representation of the instance.