Class: CanvasTexture

Phaser.Textures. CanvasTexture

A Canvas Texture is a special kind of Texture that is backed by an HTML Canvas Element as its source.

You can use the properties of this texture to draw to the canvas element directly, using all of the standard
canvas operations available in the browser. Any Game Object can be given this texture and will render with it.

Note: When running under WebGL the Canvas Texture needs to re-generate its base WebGLTexture and reupload it to
the GPU every time you modify it, otherwise the changes you make to this texture will not be visible. To do this
you should call CanvasTexture.refresh() once you are finished with your changes to the canvas. Try and keep
this to a minimum, especially on large canvas sizes, or you may inadvertently thrash the GPU by constantly uploading
texture data to it. This restriction does not apply if using the Canvas Renderer.

It starts with only one frame that covers the whole of the canvas. You can add further frames, that specify
sections of the canvas using the add method.

Should you need to resize the canvas use the setSize method so that it accurately updates all of the underlying
texture data as well. Forgetting to do this (i.e. by changing the canvas size directly from your code) could cause
graphical errors.


new CanvasTexture(manager, key, source, width, height)

Parameters:
Name Type Description
manager Phaser.Textures.CanvasTexture

A reference to the Texture Manager this Texture belongs to.

key string

The unique string-based key of this Texture.

source HTMLCanvasElement

The canvas element that is used as the base of this texture.

width integer

The width of the canvas.

height integer

The height of the canvas.

Since: 3.7.0
Source: src/textures/CanvasTexture.js (Line 12)

Extends

Members


buffer :ArrayBuffer

An ArrayBuffer the same size as the context ImageData.

Type:
  • ArrayBuffer
Since: 3.13.0
Source: src/textures/CanvasTexture.js (Line 143)

<readonly> canvas :HTMLCanvasElement

The source Canvas Element.

Type:
  • HTMLCanvasElement
Since: 3.7.0
Source: src/textures/CanvasTexture.js (Line 66)

<readonly> context :CanvasRenderingContext2D

The 2D Canvas Rendering Context.

Type:
  • CanvasRenderingContext2D
Since: 3.7.0
Source: src/textures/CanvasTexture.js (Line 76)

customData :object

Any additional data that was set in the source JSON (if any),
or any extra data you'd like to store relating to this texture

Type:
  • object
Since: 3.0.0
Inherited From:
Source: src/textures/Texture.js (Line 94)

data :Uint8ClampedArray

A Uint8ClampedArray view into the buffer.
Use the update method to populate this when the canvas changes.
Note that this is unavailable in some browsers, such as Epic Browser, due to their security restrictions.

Type:
  • Uint8ClampedArray
Since: 3.13.0
Source: src/textures/CanvasTexture.js (Line 118)

dataSource :array

An array of TextureSource data instances.
Used to store additional data images, such as normal maps or specular maps.

Type:
  • array
Since: 3.0.0
Inherited From:
Source: src/textures/Texture.js (Line 75)

firstFrame :string

The name of the first frame of the Texture.

Type:
  • string
Since: 3.0.0
Inherited From:
Source: src/textures/Texture.js (Line 104)

frames :object

A key-value object pair associating the unique Frame keys with the Frames objects.

Type:
  • object
Since: 3.0.0
Inherited From:
Source: src/textures/Texture.js (Line 85)

frameTotal :integer

The total number of Frames in this Texture.

Type:
  • integer
Since: 3.0.0
Inherited From:
Default Value:
  • 0
Source: src/textures/Texture.js (Line 113)

<readonly> height :integer

The height of the Canvas.
This property is read-only, if you wish to change it use the setSize method.

Type:
  • integer
Since: 3.7.0
Source: src/textures/CanvasTexture.js (Line 97)

imageData :ImageData

The context image data.
Use the update method to populate this when the canvas changes.

Type:
  • ImageData
Since: 3.13.0
Source: src/textures/CanvasTexture.js (Line 108)

key :string

The unique string-based key of this Texture.

Type:
  • string
Since: 3.0.0
Inherited From:
Source: src/textures/Texture.js (Line 56)

manager :Phaser.Textures.TextureManager

A reference to the Texture Manager this Texture belongs to.

Type:
Since: 3.0.0
Inherited From:
Source: src/textures/Texture.js (Line 47)

pixels :Uint32Array

An Uint32Array view into the buffer.

Type:
  • Uint32Array
Since: 3.13.0
Source: src/textures/CanvasTexture.js (Line 134)

source :Array.<Phaser.Textures.TextureSource>

An array of TextureSource instances.
These are unique to this Texture and contain the actual Image (or Canvas) data.

Type:
Since: 3.0.0
Inherited From:
Source: src/textures/Texture.js (Line 65)

<readonly> width :integer

The width of the Canvas.
This property is read-only, if you wish to change it use the setSize method.

Type:
  • integer
Since: 3.7.0
Source: src/textures/CanvasTexture.js (Line 86)

Methods


add(name, sourceIndex, x, y, width, height)

Adds a new Frame to this Texture.

A Frame is a rectangular region of a TextureSource with a unique index or string-based key.

Parameters:
Name Type Description
name integer | string

The name of this Frame. The name is unique within the Texture.

sourceIndex integer

The index of the TextureSource that this Frame is a part of.

x number

The x coordinate of the top-left of this Frame.

y number

The y coordinate of the top-left of this Frame.

width number

The width of this Frame.

height number

The height of this Frame.

Since: 3.0.0
Inherited From:
Source: src/textures/Texture.js (Line 130)
Returns:

The Frame that was added to this Texture.

Type
Phaser.Textures.Frame

clear()

Clears this Canvas Texture, resetting it back to transparent.

Since: 3.7.0
Source: src/textures/CanvasTexture.js (Line 303)
Returns:

The Canvas Texture.

Type
Phaser.Textures.CanvasTexture

destroy()

Destroys this Texture and releases references to its sources and frames.

Since: 3.0.0
Inherited From:
Source: src/textures/Texture.js (Line 434)

draw(x, y, source)

Draws the given Image or Canvas element to this CanvasTexture, then updates the internal
ImageData buffer and arrays.

Parameters:
Name Type Description
x integer

The x coordinate to draw the source at.

y integer

The y coordinate to draw the source at.

source HTMLImageElement | HTMLCanvasElement

The element to draw to this canvas.

Since: 3.13.0
Source: src/textures/CanvasTexture.js (Line 206)
Returns:

This CanvasTexture.

Type
Phaser.Textures.CanvasTexture

get( [name])

Gets a Frame from this Texture based on either the key or the index of the Frame.

In a Texture Atlas Frames are typically referenced by a key.
In a Sprite Sheet Frames are referenced by an index.
Passing no value for the name returns the base texture.

Parameters:
Name Type Argument Description
name string | integer <optional>

The string-based name, or integer based index, of the Frame to get from this Texture.

Since: 3.0.0
Inherited From:
Source: src/textures/Texture.js (Line 182)
Returns:

The Texture Frame.

Type
Phaser.Textures.Frame

getCanvas()

Gets the Canvas Element.

Since: 3.7.0
Source: src/textures/CanvasTexture.js (Line 277)
Returns:

The Canvas DOM element this texture is using.

Type
HTMLCanvasElement

getContext()

Gets the 2D Canvas Rendering Context.

Since: 3.7.0
Source: src/textures/CanvasTexture.js (Line 290)
Returns:

The Canvas Rendering Context this texture is using.

Type
CanvasRenderingContext2D

getDataSourceImage( [name])

Given a Frame name, return the data source image it uses to render with.
You can use this to get the normal map for an image for example.

This will return the actual DOM Image.

Parameters:
Name Type Argument Description
name string | integer <optional>

The string-based name, or integer based index, of the Frame to get from this Texture.

Since: 3.7.0
Inherited From:
Source: src/textures/Texture.js (Line 342)
Returns:

The DOM Image or Canvas Element.

Type
HTMLImageElement | HTMLCanvasElement

getFrameNames( [includeBase])

Returns an array with all of the names of the Frames in this Texture.

Useful if you want to randomly assign a Frame to a Game Object, as you can
pick a random element from the returned array.

Parameters:
Name Type Argument Default Description
includeBase boolean <optional>
false

Include the __BASE Frame in the output array?

Since: 3.0.0
Inherited From:
Source: src/textures/Texture.js (Line 277)
Returns:

An array of all Frame names in this Texture.

Type
Array.<string>

getFramesFromTextureSource(sourceIndex [, includeBase])

Returns an array of all the Frames in the given TextureSource.

Parameters:
Name Type Argument Default Description
sourceIndex integer

The index of the TextureSource to get the Frames from.

includeBase boolean <optional>
false

Include the __BASE Frame in the output array?

Since: 3.0.0
Inherited From:
Source: src/textures/Texture.js (Line 242)
Returns:

An array of Texture Frames.

Type
Array.<Phaser.Textures.Frame>

getPixel(x, y [, out])

Get the color of a specific pixel from this texture and store it in a Color object.

If you have drawn anything to this CanvasTexture since it was created you must call CanvasTexture.update to refresh the array buffer,
otherwise this may return out of date color values, or worse - throw a run-time error as it tries to access an array element that doesn't exist.

Parameters:
Name Type Argument Description
x integer

The x coordinate of the pixel to be set. Must lay within the dimensions of this CanvasTexture and be an integer.

y integer

The y coordinate of the pixel to be set. Must lay within the dimensions of this CanvasTexture and be an integer.

out Phaser.Display.Color <optional>

An object into which 4 properties will be set: r, g, b and a. If not provided a Color object will be created.

Since: 3.13.0
Source: src/textures/CanvasTexture.js (Line 226)
Returns:

An object with the red, green, blue and alpha values set in the r, g, b and a properties.

Type
Phaser.Display.Color

getSourceImage( [name])

Given a Frame name, return the source image it uses to render with.

This will return the actual DOM Image or Canvas element.

Parameters:
Name Type Argument Description
name string | integer <optional>

The string-based name, or integer based index, of the Frame to get from this Texture.

Since: 3.0.0
Inherited From:
Source: src/textures/Texture.js (Line 309)
Returns:

The DOM Image, Canvas Element or Render Texture.

Type
HTMLImageElement | HTMLCanvasElement | Phaser.GameObjects.RenderTexture

getTextureSourceIndex(source)

Takes the given TextureSource and returns the index of it within this Texture.
If it's not in this Texture, it returns -1.
Unless this Texture has multiple TextureSources, such as with a multi-atlas, this
method will always return zero or -1.

Parameters:
Name Type Description
source Phaser.Textures.TextureSource

The TextureSource to check.

Since: 3.0.0
Inherited From:
Source: src/textures/Texture.js (Line 216)
Returns:

The index of the TextureSource within this Texture, or -1 if not in this Texture.

Type
integer

has(name)

Checks to see if a Frame matching the given key exists within this Texture.

Parameters:
Name Type Description
name string

The key of the Frame to check for.

Since: 3.0.0
Inherited From:
Source: src/textures/Texture.js (Line 167)
Returns:

True if a Frame with the matching key exists in this Texture.

Type
boolean

refresh()

This should be called manually if you are running under WebGL.
It will refresh the WebGLTexture from the Canvas source. Only call this if you know that the
canvas has changed, as there is a significant GPU texture allocation cost involved in doing so.

Since: 3.7.0
Source: src/textures/CanvasTexture.js (Line 260)
Returns:

This CanvasTexture.

Type
Phaser.Textures.CanvasTexture

setDataSource(data)

Adds a data source image to this Texture.

An example of a data source image would be a normal map, where all of the Frames for this Texture
equally apply to the normal map.

Parameters:
Name Type Description
data HTMLImageElement | HTMLCanvasElement

The source image.

Since: 3.0.0
Inherited From:
Source: src/textures/Texture.js (Line 379)

setFilter(filterMode)

Sets the Filter Mode for this Texture.

The mode can be either Linear, the default, or Nearest.

For pixel-art you should use Nearest.

The mode applies to the entire Texture, not just a specific Frame of it.

Parameters:
Name Type Description
filterMode Phaser.Textures.FilterMode

The Filter Mode.

Since: 3.0.0
Inherited From:
Source: src/textures/Texture.js (Line 405)

setSize(width [, height])

Changes the size of this Canvas Texture.

Parameters:
Name Type Argument Description
width integer

The new width of the Canvas.

height integer <optional>

The new height of the Canvas. If not given it will use the width as the height.

Since: 3.7.0
Source: src/textures/CanvasTexture.js (Line 318)
Returns:

The Canvas Texture.

Type
Phaser.Textures.CanvasTexture

update()

This re-creates the imageData from the current context.
It then re-builds the ArrayBuffer, the data Uint8ClampedArray reference and the pixels Int32Array.

Warning: This is a very expensive operation, so use it sparingly.

Since: 3.13.0
Source: src/textures/CanvasTexture.js (Line 171)
Returns:

This CanvasTexture.

Type
Phaser.Textures.CanvasTexture