BitmapCache Class
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
()
Item Index
Methods
Methods
_applyFilters
()
protected
Work through every filter and apply its individual visual transformation.
_drawToCache
()
protected
Perform the cache draw out for context 2D now that the setup properties have been performed.
_updateSurface
()
protected
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]
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 cacheWebGL 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 cacheYou 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:
-
xNumberThe x coordinate origin for the cache region.
-
yNumberThe y coordinate origin for the cache region.
-
widthNumberThe width of the cache region.
-
heightNumberThe height of the cache region.
-
[scale=1]Number optionalThe 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 optionalSpecify additional parameters for the cache logic
-
[useGL=undefined]Undefined | "new" | "stage" | StageGL optionalSelect 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
Use context2D drawing commands to display the cache canvas being used.
Parameters:
-
ctxCanvasRenderingContext2DThe context to draw into.
Returns:
Whether the draw was handled successfully.
getCacheDataURL
()
String
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:
The image data url for the cache.
getFilterBounds
-
target -
[output=null]
Returns the bounds that surround all applied filters, relies on each filter to describe how it changes bounds.
Parameters:
-
targetDisplayObjectThe object to check the filter bounds for.
-
[output=null]Rectangle optionalOptional parameter, if provided then calculated bounds will be applied to that object.
Returns:
bounds object representing the bounds with filters.
release
()
Reset and release all the properties and memory associated with this cache.
toString
()
String
Returns a string representation of this object.
Returns:
a string representation of the instance.
update
-
[compositeOperation=null]
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 optionalThe DisplayObject this cache is linked to.
Properties
_boundRect
Rectangle
protected
Internal tracking of the last requested bounds, may happen repeadtedly so stored to avoid object creation
Default: 0
_cacheDataURL
String
protected
The cache's DataURL, generated on-demand using the getter.
Default: null
_drawHeight
Number
protected
Internal tracking of final bounding height, approximately height*scale; however, filters can complicate the actual value.
Default: 0
_drawWidth
Number
protected
Internal tracking of final bounding width, approximately width*scale; however, filters can complicate the actual value.
Default: 0
_filterOffY
Number
protected
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
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
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
offX
Number
protected
The x offset used for drawing into the cache itself, accounts for both transforms applied.
Default: 0
offY
Number
protected
The y offset used for drawing into the cache itself, accounts for both transforms applied.
Default: 0
scale
Number
protected
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
x
Number
protected
Horizontal position of the cache relative to the target's origin.
Default: undefined