API Documentation for: NEXT
Show:

BitmapCache Class

Defined in: BitmapCache:40
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. On a StageGL performance is better so the presence of a filter will automatically create a cache if one is not made manually.

Some visual effects can be achieved with a compositeOperation so check out that setting before settling on a filter.

Constructor

BitmapCache

()

Defined in BitmapCache:40

Methods

_applyFilters

() protected

Defined in _applyFilters:667

Work through every filter and apply its individual visual transformation.

_drawToCache

() protected

Defined in _drawToCache:634

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

_updateSurface

() protected

Defined in _updateSurface:569

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.

define

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

Defined in define:352

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. Must be added to a stage first to work.
  • If options.useGL is a StageGL instance then it will use it to cache. Warning, caches made on one StageGL will not render on any other StageGL.
  • 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);

// option 1
stageGL.addChild(bmp);
bmp.cache(0, 0, bmp.width, bmp.height, 1, {gl: "stage"});       // when added to the display list we can look it up
// option 2
bmp.cache(0, 0, bmp.width, bmp.height, 1, {gl: stageGL});       // we can specify it explicitly if we add it later
stageGL.addChild(bmp);

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 the specified stage is not rendering content and just the cache setStageGL/isCacheControlled to true on your instance. This will trigger it to behave correctly for rendering your output.

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

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.

getBounds

() Rectangle

Defined in getBounds:541

Determine the bounds of the shape in local space.

Returns:

getCacheDataURL

() String

Defined in getCacheDataURL:509

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

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

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

toString

() String

Defined in toString:343

Returns a string representation of this object.

Returns:

String:

a string representation of the instance.

update

(
  • [compositeOperation=null]
)

Defined in update:432

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

_boundRect

Rectangle protected

Defined in _boundRect:237

Internal tracking of the last requested bounds, may happen repeadtedly so stored to avoid object creation

Default: 0

_bufferTextureConcat

WebGLTexture

One of the major render buffers used in composite blending and filter drawing. Do not expect this to always be the same object. "What you've draw before now", object occasionally swaps with output.

_bufferTextureOutput

WebGLTexture

One of the major render buffers used in composite blending and filter drawing. Do not expect this to always be the same object. "What you're drawing to", object occasionally swaps with concat.

_bufferTextureTemp

WebGLTexture

One of the major render buffers used only for composite blending draws. "Temporary mixing surface"

_cacheCanvas

HTMLCanvasElement | WebGLTexture | Object protected

Defined in _cacheCanvas:185

Internal tracking of intended cacheCanvas, may or may not be assigned based on disabled state.

_cacheDataURL

String protected

Defined in _cacheDataURL:210

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

Default: null

_cacheDataURLID

Number protected

Defined in _cacheDataURLID:201

The cacheID when a DataURL was requested.

Default: 0

_counterMatrix

Matrix2D

Defined in _counterMatrix:247

Storage for the StageGL counter positioning matrix used on the object being cached

_disabled

Boolean protected

Defined in _disabled:170

Internal tracking of the disabled state, use the getter/setters.

_drawHeight

Number protected

Defined in _drawHeight:228

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

Default: 0

_drawWidth

Number protected

Defined in _drawWidth:219

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

Default: 0

_filterOffY

Number protected

Defined in _filterOffY:160

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

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

_stageGL

StageGL protected

Defined in _stageGL:193

Output StageGL target for GL drawing

autoPurge

Boolean

Defined in autoPurge:292

Disable or enable the BitmapCache from displaying. Does not cause or block cache or cache updates when toggled. Best used if the cached state is always identical, but the object will need temporary uncaching.

Default: false

cacheID

Number

Defined in cacheID:133

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

Height of the cache relative to the target object.

Default: undefined

offX

Number protected

Defined in offX:115

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

Default: 0

offY

Number protected

Defined in offY:124

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

Default: 0

scale

Number protected

Defined in scale:104

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

Width of the cache relative to the target object.

Default: undefined

x

Number protected

Defined in x:86

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

Default: undefined

y

Number protected

Defined in y:95

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

Default: undefined