API Documentation for: 1.0.0
Show:

BitmapCache Class

Defined in: BitmapCache:41
Module: EaselJS

The BitmapCache is an internal representation of all the cache properties and logic required in order to "cache" an object. This information and functionality used to be located on a cache method in DisplayObject, but was moved to its own class.

Caching in this context is purely visual, and will render the DisplayObject out into an image to be used instead of the object. The actual cache itself is still stored on the target with the cacheCanvas. Working with a singular image like a Bitmap there is little benefit to performing a cache as it is already a single image. Caching is best done on containers containing multiple complex parts that do not move often, so that rendering the image instead will improve overall rendering speed. A cached object will not visually update until explicitly told to do so with a call to update, much like a Stage. If a cache is being updated every frame it is likely not improving rendering performance. Cache are best used when updates will be sparse.

Caching is also a co-requisite for applying filters to prevent expensive filters running constantly without need, and to physically enable some effects. The BitmapCache is also responsible for applying filters to objects and reads each Filter due to this relationship. Real-time Filters are not recommended performance wise when dealing with a Context2D canvas. For best performance and to still allow for some visual effects use a compositeOperation when possible.

Constructor

BitmapCache

()

Defined in BitmapCache:41

Methods

_applyFilters

() protected

Defined in _applyFilters:516

Work through every filter and apply its individual visual transformation.

_drawToCache

() protected

Defined in _drawToCache:475

Perform the cache draw out for context 2D now that the setup properties have been performed.

_updateSurface

() protected

Defined in _updateSurface:405

Create or resize the invisible canvas/surface that is needed for the display object(s) to draw to, and in turn be used in their stead when drawing. The surface is resized to the size defined by the width and height, factoring in scaling and filters. Adjust them to adjust the output size.

BitmapCache.cache

(
  • x
  • y
  • width
  • height
  • [scale=1]
  • [options=undefined]
)
public

Actually create the correct cache surface and properties associated with it. Caching and it's benefits are discussed by the cache function and this class description. Here are the detailed specifics of how to use the options object.

  • If options.useGL is set to "new" a StageGL is created and contained on this for use when rendering the cache.
  • If options.useGL is set to "stage" if the current stage is a StageGL it will be used. If not then it will default to "new".
  • If options.useGL is a StageGL instance it will not create one but use the one provided.
  • If options.useGL is undefined a Context 2D cache will be performed.

This means you can use any combination of StageGL and 2D with either, neither, or both the stage and cache being WebGL. Using "new" with a StageGL display list is highly unrecommended, but still an option. It should be avoided due to negative performance reasons and the Image loading limitation noted in the class complications above.

When "options.useGL" is set to the parent stage of the target and WebGL, performance is increased by using "RenderTextures" instead of canvas elements. These are internal Textures on the graphics card stored in the GPU. Because they are no longer canvases you cannot perform operations you could with a regular canvas. The benefit is that this avoids the slowdown of copying the texture back and forth from the GPU to a Canvas element. This means "stage" is the recommended option when available.

A StageGL cache does not infer the ability to draw objects a StageGL cannot currently draw, i.e. do not use a WebGL context cache when caching a Shape, Text, etc.

WebGL cache with a 2D context

var stage = new createjs.Stage();
var bmp = new createjs.Bitmap(src);
bmp.cache(0, 0, bmp.width, bmp.height, 1, {gl: "new"});          // no StageGL to use, so make one

var shape = new createjs.Shape();
shape.graphics.clear().fill("red").drawRect(0,0,20,20);
shape.cache(0, 0, 20, 20, 1);                             // cannot use WebGL cache

WebGL cache with a WebGL context

var stageGL = new createjs.StageGL();
var bmp = new createjs.Bitmap(src);
bmp.cache(0, 0, bmp.width, bmp.height, 1, {gl: "stage"});       // use our StageGL to cache

var shape = new createjs.Shape();
shape.graphics.clear().fill("red").drawRect(0,0,20,20);
shape.cache(0, 0, 20, 20, 1);                             // cannot use WebGL cache

You may wish to create your own StageGL instance to control factors like clear color, transparency, AA, and others. If you do, pass a new instance in instead of "true", the library will automatically set the StageGL/isCacheControlled to true on your instance. This will trigger it to behave correctly, and not assume your main context is WebGL.

Parameters:

  • x Number

    The x coordinate origin for the cache region.

  • y Number

    The y coordinate origin for the cache region.

  • width Number

    The width of the cache region.

  • height Number

    The height of the cache region.

  • [scale=1] Number optional

    The scale at which the cache will be created. For example, if you cache a vector shape using myShape.cache(0,0,100,100,2) then the resulting cacheCanvas will be 200x200 px. This lets you scale and rotate cached elements with greater fidelity. Default is 1.

  • [options=undefined] Object optional

    Specify additional parameters for the cache logic

    • [useGL=undefined] Undefined | "new" | "stage" | StageGL optional

      Select whether to use context 2D, or WebGL rendering, and whether to make a new stage instance or use an existing one. See above for extensive details on use.

draw

(
  • ctx
)
Boolean

Defined in draw:389

Use context2D drawing commands to display the cache canvas being used.

Parameters:

  • ctx CanvasRenderingContext2D

    The context to draw into.

Returns:

Boolean:

Whether the draw was handled successfully.

getCacheDataURL

() String

Defined in getCacheDataURL:372

Returns a data URL for the cache, or null if this display object is not cached. Uses cacheID to ensure a new data URL is not generated if the cache has not changed.

Returns:

String:

The image data url for the cache.

getFilterBounds

(
  • target
  • [output=null]
)
Rectangle static

Defined in getFilterBounds:199

Returns the bounds that surround all applied filters, relies on each filter to describe how it changes bounds.

Parameters:

  • target DisplayObject

    The object to check the filter bounds for.

  • [output=null] Rectangle optional

    Optional parameter, if provided then calculated bounds will be applied to that object.

Returns:

Rectangle:

bounds object representing the bounds with filters.

release

()

Defined in release:344

Reset and release all the properties and memory associated with this cache.

toString

() String

Defined in toString:229

Returns a string representation of this object.

Returns:

String:

a string representation of the instance.

update

(
  • [compositeOperation=null]
)

Defined in update:313

Directly called via updateCache, but also internally. This has the dual responsibility of making sure the surface is ready to be drawn to, and performing the draw. For full details of each behaviour, check the protected functions _updateSurface and _drawToCache respectively.

Parameters:

  • [compositeOperation=null] String optional

    The DisplayObject this cache is linked to.

Properties

_cacheDataURL

String protected

Defined in _cacheDataURL:170

The cache's DataURL, generated on-demand using the getter.

Default: null

_cacheDataURLID

Number protected

Defined in _cacheDataURLID:161

The cacheID when a DataURL was requested.

Default: 0

_drawHeight

Number protected

Defined in _drawHeight:188

Internal tracking of final bounding height, approximately height*scale; however, filters can complicate the actual value.

Default: 0

_drawWidth

Number protected

Defined in _drawWidth:179

Internal tracking of final bounding width, approximately width*scale; however, filters can complicate the actual value.

Default: 0

_filterOffY

Number protected

Defined in _filterOffY:151

The relative offset of the filter's y position, used for drawing the cache onto its container. Re-calculated every update call before drawing.

Default: 0

_filterOffY

Number protected

Defined in _filterOffY:141

The relative offset of the filter's x position, used for drawing the cache onto its container. Re-calculated every update call before drawing.

Default: 0

cacheID

Number

Defined in cacheID:131

Track how many times the cache has been updated, mostly used for preventing duplicate cacheURLs. This can be useful to see if a cache has been updated.

Default: 0

height

Number protected

Defined in height:74

Height of the cache relative to the target object.

Default: undefined

offX

Number protected

Defined in offX:113

The x offset used for drawing into the cache itself, accounts for both transforms applied.

Default: 0

offY

Number protected

Defined in offY:122

The y offset used for drawing into the cache itself, accounts for both transforms applied.

Default: 0

scale

Number protected

Defined in scale:102

The internal scale of the cache image, does not affects display size. This is useful to both increase and decrease render quality. Objects with increased scales are more likely to look good when scaled up or rotated. Objects with decreased scales can save on rendering performance.

Default: 1

width

Number protected

Defined in width:65

Width of the cache relative to the target object.

Default: undefined

x

Number protected

Defined in x:84

Horizontal position of the cache relative to the target's origin.

Default: undefined

y

Number protected

Defined in y:93

Vertical position of the cache relative to target's origin.

Default: undefined