API Documentation for: 0.7.0
Show:

SpriteSheetBuilder Class

Extends EventDispatcher
Defined in: SpriteSheetBuilder:39
Module: EaselJS

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

()

Methods

_dispatchEvent

(
  • eventObj
  • eventPhase
)
protected

Parameters:

_drawNext

() protected

Defined in _drawNext:505

Returns:

Boolean Returns false if this is the last draw.

_endBuild

() protected

Defined in _endBuild:469

_fillRow

(
  • frames
  • y
  • img
  • dataFrames
  • pad
)
Number protected

Defined in _fillRow:431

Parameters:

Returns:

Number:

The width & height of the row.

_getSize

() Number protected

Defined in _getSize:420

Returns:

Number:

The width & height of the row.

_run

() protected

Defined in _run:480

_startBuild

() protected

Defined in _startBuild:380

addAnimation

(
  • name
  • frames
  • [next]
  • [frequency]
)

Defined in addAnimation:258

Adds an animation that will be included in the created sprite sheet.

Parameters:

  • name String

    The name for the animation.

  • frames Array

    An array of frame indexes that comprise the animation. Ex. [3,6,5] would describe an animation that played frame indexes 3, 6, and 5 in that order.

  • [next] String optional

    Specifies the name of the animation to continue to after this animation ends. You can also pass false to have the animation stop when it ends. By default it will loop to the start of the same animation.

  • [frequency] Number optional

    Specifies a frame advance frequency for this animation. For example, a value of 2 would cause the animation to advance every second tick.

addEventListener

(
  • type
  • listener
  • [useCapture]
)
Function | Object

Adds the specified event listener. Note that adding multiple listeners to the same function will result in multiple callbacks getting fired.

Example

 displayObject.addEventListener("click", handleClick);
 function handleClick(event) {
    // Click happened.
 }

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    An object with a handleEvent method, or a function that will be called when the event is dispatched.

  • [useCapture] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

Returns:

Function | Object:

Returns the listener for chaining or assignment.

addFrame

(
  • source
  • [sourceRect]
  • [scale=1]
  • [setupFunction]
  • [setupParams]
  • [setupScope]
)
Number

Defined in addFrame:229

Adds a frame to the SpriteSheet. Note that the frame will not be drawn until you call build method. 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 its 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 DisplayObject 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=1] Number optional

    Optional. The scale to draw this frame at. Default is 1.

  • [setupFunction] Function optional

    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

(
  • source
  • [sourceRect]
  • [scale=1]
)

Defined in addMovieClip:274

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=1] Number optional

    The scale to draw the movie clip at.

build

()

Defined in build:325

Builds a SpriteSheet instance based on the current frames.

Returns:

SpriteSheet The created SpriteSheet instance, or null if a build is already running or an error occurred.

buildAsync

(
  • [timeSlice]
)

Defined in buildAsync:338

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:

  • [timeSlice] Number optional

    Sets the timeSlice property on this instance.

clone

()

Defined in clone:362

SpriteSheetBuilder instances cannot be cloned.

dispatchEvent

(
  • eventObj
  • [target]
)
Boolean

Dispatches the specified event to all listeners.

Example

 // Use a string event
 this.dispatchEvent("complete");

 // Use an Event instance
 var event = new createjs.Event("progress");
 this.dispatchEvent(event);

Parameters:

  • eventObj Object | String | Event

    An object with a "type" property, or a string type. While a generic object will work, it is recommended to use a CreateJS Event instance. If a string is used, dispatchEvent will construct an Event instance with the specified type.

  • [target] Object optional

    The object to use as the target property of the event object. This will default to the dispatching object. This parameter is deprecated and will be removed.

Returns:

Boolean:

Returns the value of eventObj.defaultPrevented.

hasEventListener

(
  • type
)
Boolean

Indicates whether there is at least one listener for the specified event type and useCapture value.

Parameters:

  • type String

    The string type of the event.

Returns:

Boolean:

Returns true if there is at least one listener for the specified event.

initialize

() protected

Inherited from EventDispatcher but overwritten in initialize:217

Initialization method.

off

(
  • type
  • listener
  • [useCapture]
)

Inherited from EventDispatcher: off:246

A shortcut to the removeEventListener method, with the same parameters and return value. This is a companion to the .on method.

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    The listener function or object.

  • [useCapture] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

on

(
  • type
  • listener
  • [scope]
  • [once=false]
  • [data]
  • [useCapture=false]
)
Function

Inherited from EventDispatcher: on:174

A shortcut method for using addEventListener that makes it easier to specify an execution scope, have a listener only run once, associate arbitrary data with the listener, and remove the listener.

This method works by creating an anonymous wrapper function and subscribing it with addEventListener. The created anonymous function is returned for use with .removeEventListener (or .off).

Example

    var listener = myBtn.on("click", handleClick, null, false, {count:3});
    function handleClick(evt, data) {
        data.count -= 1;
        console.log(this == myBtn); // true - scope defaults to the dispatcher
        if (data.count == 0) {
            alert("clicked 3 times!");
            myBtn.off("click", listener);
            // alternately: evt.remove();
        }
    }

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    An object with a handleEvent method, or a function that will be called when the event is dispatched.

  • [scope] Object optional

    The scope to execute the listener in. Defaults to the dispatcher/currentTarget for function listeners, and to the listener itself for object listeners (ie. using handleEvent).

  • [once=false] Boolean optional

    If true, the listener will remove itself after the first time it is triggered.

  • [data] optional

    Arbitrary data that will be included as the second parameter when the listener is called.

  • [useCapture=false] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

Returns:

Function:

Returns the anonymous function that was created and assigned as the listener. This is needed to remove the listener later using .removeEventListener.

removeAllEventListeners

(
  • [type]
)

Removes all listeners for the specified type, or all listeners of all types.

Example

 // Remove all listeners
 displayObject.removeAllEvenListeners();

 // Remove all click listeners
 displayObject.removeAllEventListeners("click");

Parameters:

  • [type] String optional

    The string type of the event. If omitted, all listeners for all types will be removed.

removeEventListener

(
  • type
  • listener
  • [useCapture]
)

Removes the specified event listener.

Important Note: that you must pass the exact function reference used when the event was added. If a proxy function, or function closure is used as the callback, the proxy/closure reference must be used - a new proxy or closure will not work.

Example

 displayObject.removeEventListener("click", handleClick);

Parameters:

  • type String

    The string type of the event.

  • listener Function | Object

    The listener function or object.

  • [useCapture] Boolean optional

    For events that bubble, indicates whether to listen for the event in the capture or bubbling/target phase.

stopAsync

()

Defined in stopAsync:353

Stops the current asynchronous build.

toString

() String

Inherited from EventDispatcher but overwritten in toString:370

Returns a string representation of this object.

Returns:

String:

a string representation of the instance.

Properties

_animations

Array protected

Defined in _animations:174

_captureListeners

Object protected

_data

Array protected

Defined in _data:181

_frames

Array protected

Defined in _frames:167

_index

Number protected

Defined in _index:195

_listeners

Object protected

_nextFrameIndex

Number protected

Defined in _nextFrameIndex:188

_scale

Number protected

Defined in _scale:209

_timerID

Number protected

Defined in _timerID:202

maxHeight

Number

Defined in maxHeight:93

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: 2048

maxWidth

Number

Defined in maxWidth:83

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: 2048

onComplete

Function deprecated

Defined in onComplete:150

Deprecated: Use addEventListener and the "complete" event.

REMOVED. Use addEventListener and the complete event.

onProgress

Function deprecated

Defined in onProgress:157

Deprecated: Use addEventListener and the "progress" event.

REMOVED. Use addEventListener and the SpriteSheetBuilder/progress:event event.

padding

Number

Defined in padding:120

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

Default: 1

progress

Number

Defined in progress:139

A value between 0 and 1 that indicates the progress of a build, or -1 if a build has not been initiated.

Default: -1

scale

Number

Defined in scale:110

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: 1

spriteSheet

SpriteSheet

Defined in spriteSheet:103

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

timeSlice

Number

Defined in timeSlice:128

A number from 0.01 to 0.99 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.

Default: 0.3

Events

complete

Defined in complete:64

Available since 0.6.0

Dispatched when a build completes.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.

complete

Defined in complete:72

Available since 0.6.0

Dispatched when an asynchronous build has progress.

Event Payload:

  • target Object

    The object that dispatched the event.

  • type String

    The event type.

  • progress Number

    The current progress value (0-1).