#

API Documentation for: NEXT
Show: Inherited Protected Private Deprecated

# 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`

- Index
- Methods
- Properties

## Item Index

### Methods

- _applyFilters
- _drawToCache
- _updateSurface
- BitmapCache.cache
- draw
- getCacheDataURL
- getFilterBounds static
- release
- toString
- update

### Properties

- _cacheDataURL
- _cacheDataURLID
- _drawHeight
- _drawWidth
- _filterOffY
- _filterOffY
- cacheID
- height
- offX
- offY
- scale
- width
- x
- y

## 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

Defined in `BitmapCache.cache:238`

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