Class 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.

Hierarchy (View Summary)

Textures.Texture
- CanvasTexture

Constructors

constructor

new CanvasTexture(
    manager: TextureManager,
    key: string,
    source: HTMLCanvasElement,
    width: number,
    height: number,
): Textures.CanvasTexture
Parameters
- manager: TextureManager
  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: number
  The width of the canvas.
- height: number
  The height of the canvas.
Returns Textures.CanvasTexture
Overrides Texture.constructor
- Defined in types/phaser.d.ts:108015

Properties

buffer

buffer: ArrayBuffer

An ArrayBuffer the same size as the context ImageData.

`Readonly`canvas

canvas: HTMLCanvasElement

The source Canvas Element.

`Readonly`context

context: CanvasRenderingContext2D

The 2D Canvas Rendering Context.

customData

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

data

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.

dataSource

dataSource: any[]

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

firstFrame

firstFrame: string

The name of the first frame of the Texture.

frames

frames: object

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

frameTotal

frameTotal: number

The total number of Frames in this Texture, including the __BASE frame.

A Texture will always contain at least 1 frame because every Texture contains a __BASE frame by default, in addition to any extra frames that have been added to it, such as when parsing a Sprite Sheet or Texture Atlas.

`Readonly`height

height: number

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

imageData

imageData: ImageData

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

key

key: string

The unique string-based key of this Texture.

manager

manager: TextureManager

A reference to the Texture Manager this Texture belongs to.

pixels

pixels: Uint32Array

An Uint32Array view into the buffer.

smoothPixelArt

smoothPixelArt: boolean

Whether shaders using this texture should use special filtering code. This relies on shader support.

If null, the game default will be used.

source

source: TextureSource[]

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

`Readonly`width

width: number

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

Methods

add

add(
    name: string | number,
    sourceIndex: number,
    x: number,
    y: number,
    width: number,
    height: number,
): Frame
Adds a new Frame to this Texture.

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

The name given must be unique within this Texture. If it already exists, this method will return null.
Parameters
- name: string | number
  The name of this Frame. The name is unique within the Texture.
- sourceIndex: number
  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.
Returns Frame
Inherited from Texture.add
- Defined in types/phaser.d.ts:108999

clear

clear(
    x?: number,
    y?: number,
    width?: number,
    height?: number,
    update?: boolean,
): Textures.CanvasTexture
Clears the given region of this Canvas Texture, resetting it back to transparent. If no region is given, the whole Canvas Texture is cleared.
Parameters
- Optionalx: number
  The x coordinate of the top-left of the region to clear. Default 0.
- Optionaly: number
  The y coordinate of the top-left of the region to clear. Default 0.
- Optionalwidth: number
  The width of the region.
- Optionalheight: number
  The height of the region.
- Optionalupdate: boolean
  Update the internal ImageData buffer and arrays. Default true.
Returns Textures.CanvasTexture
- Defined in types/phaser.d.ts:108190

destroy

destroy(): void
Destroys this Texture and releases references to its sources and frames.

Returns void
Overrides Texture.destroy
- Defined in types/phaser.d.ts:108202

draw

draw(
    x: number,
    y: number,
    source: HTMLImageElement | HTMLCanvasElement,
    update?: boolean,
): Textures.CanvasTexture
Draws the given Image or Canvas element to this CanvasTexture, then updates the internal ImageData buffer and arrays.
Parameters
- x: number
  The x coordinate to draw the source at.
- y: number
  The y coordinate to draw the source at.
- source: HTMLImageElement | HTMLCanvasElement
  The element to draw to this canvas.
- Optionalupdate: boolean
  Update the internal ImageData buffer and arrays. Default true.
Returns Textures.CanvasTexture
- Defined in types/phaser.d.ts:108078

drawFrame

drawFrame(
    key: string,
    frame?: string | number,
    x?: number,
    y?: number,
    update?: boolean,
): Textures.CanvasTexture
Draws the given texture frame to this CanvasTexture, then updates the internal ImageData buffer and arrays.
Parameters
- key: string
  The unique string-based key of the Texture.
- Optionalframe: string | number
  The string-based name, or integer based index, of the Frame to get from the Texture.
- Optionalx: number
  The x coordinate to draw the source at. Default 0.
- Optionaly: number
  The y coordinate to draw the source at. Default 0.
- Optionalupdate: boolean
  Update the internal ImageData buffer and arrays. Default true.
Returns Textures.CanvasTexture
- Defined in types/phaser.d.ts:108089

get

get(name?: string | number): Frame
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
- Optionalname: string | number
  The string-based name, or integer based index, of the Frame to get from this Texture.
Returns Frame
Inherited from Texture.get
- Defined in types/phaser.d.ts:109024

getCanvas

getCanvas(): HTMLCanvasElement
Gets the Canvas Element.

Returns HTMLCanvasElement
- Defined in types/phaser.d.ts:108174

getContext

getContext(): CanvasRenderingContext2D
Gets the 2D Canvas Rendering Context.

Returns CanvasRenderingContext2D
- Defined in types/phaser.d.ts:108179

getData

getData(x: number, y: number, width: number, height: number): ImageData
Gets an ImageData region from this CanvasTexture from the position and size specified. You can write this back using CanvasTexture.putData, or manipulate it.
Parameters
- x: number
  The x coordinate of the top-left of the area to get the ImageData from. Must lay within the dimensions of this CanvasTexture and be an integer.
- y: number
  The y coordinate of the top-left of the area to get the ImageData from. Must lay within the dimensions of this CanvasTexture and be an integer.
- width: number
  The width of the rectangle from which the ImageData will be extracted. Positive values are to the right, and negative to the left.
- height: number
  The height of the rectangle from which the ImageData will be extracted. Positive values are down, and negative are up.
Returns ImageData
- Defined in types/phaser.d.ts:108124

getDataSourceImage

getDataSourceImage(name?: string | number): HTMLImageElement | HTMLCanvasElement
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
- Optionalname: string | number
  The string-based name, or integer based index, of the Frame to get from this Texture.
Returns HTMLImageElement | HTMLCanvasElement
Inherited from Texture.getDataSourceImage
- Defined in types/phaser.d.ts:109076

getFrameBounds

getFrameBounds(sourceIndex?: number): RectangleLike
Based on the given Texture Source Index, this method will get all of the Frames using that source and then work out the bounds that they encompass, returning them in an object.

This is useful if this Texture is, for example, a sprite sheet within an Atlas, and you need to know the total bounds of the sprite sheet.
Parameters
- OptionalsourceIndex: number
  The index of the TextureSource to get the Frame bounds from. Default 0.
Returns RectangleLike
Inherited from Texture.getFrameBounds
- Defined in types/phaser.d.ts:109050

getFrameNames

getFrameNames(includeBase?: boolean): string[]
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
- OptionalincludeBase: boolean
  Include the __BASE Frame in the output array? Default false.
Returns string[]
Inherited from Texture.getFrameNames
- Defined in types/phaser.d.ts:109059

getFramesFromTextureSource

getFramesFromTextureSource(sourceIndex: number, includeBase?: boolean): Frame[]
Returns an array of all the Frames in the given TextureSource.
Parameters
- sourceIndex: number
  The index of the TextureSource to get the Frames from.
- OptionalincludeBase: boolean
  Include the __BASE Frame in the output array? Default false.
Returns Frame[]
Inherited from Texture.getFramesFromTextureSource
- Defined in types/phaser.d.ts:109040

getIndex

getIndex(x: number, y: number): number
Returns the Image Data index for the given pixel in this CanvasTexture.

The index can be used to read directly from the this.data array.

The index points to the red value in the array. The subsequent 3 indexes point to green, blue and alpha respectively.
Parameters
- x: number
  The x coordinate of the pixel to get. Must lay within the dimensions of this CanvasTexture and be an integer.
- y: number
  The y coordinate of the pixel to get. Must lay within the dimensions of this CanvasTexture and be an integer.
Returns number
- Defined in types/phaser.d.ts:108162

getPixel

getPixel(x: number, y: number, out?: Display.Color): Display.Color
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
- x: number
  The x coordinate of the pixel to get. Must lay within the dimensions of this CanvasTexture and be an integer.
- y: number
  The y coordinate of the pixel to get. Must lay within the dimensions of this CanvasTexture and be an integer.
- Optionalout: Display.Color
  A Color object to store the pixel values in. If not provided a new Color object will be created.
Returns Display.Color
- Defined in types/phaser.d.ts:108135

getPixels

getPixels(
    x?: number,
    y?: number,
    width?: number,
    height?: number,
): PixelConfig[][]
Returns an array containing all of the pixels in the given region.

If the requested region extends outside the bounds of this CanvasTexture, the region is truncated to fit.

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
- Optionalx: number
  The x coordinate of the top-left of the region. Must lay within the dimensions of this CanvasTexture and be an integer. Default 0.
- Optionaly: number
  The y coordinate of the top-left of the region. Must lay within the dimensions of this CanvasTexture and be an integer. Default 0.
- Optionalwidth: number
  The width of the region to get. Must be an integer. Defaults to the canvas width if not given.
- Optionalheight: number
  The height of the region to get. Must be an integer. If not given will be set to the width.
Returns PixelConfig[][]
- Defined in types/phaser.d.ts:108150

getSourceImage

getSourceImage(
name?: string | number,
): HTMLImageElement | GameObjects.RenderTexture | HTMLCanvasElement
Given a Frame name, return the source image it uses to render with.

This will return the actual DOM Image or Canvas element.
Parameters
- Optionalname: string | number
  The string-based name, or integer based index, of the Frame to get from this Texture.
Returns HTMLImageElement | GameObjects.RenderTexture | HTMLCanvasElement
Inherited from Texture.getSourceImage
- Defined in types/phaser.d.ts:109067

getTextureSourceIndex

getTextureSourceIndex(source: TextureSource): number
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
- source: TextureSource
  The TextureSource to check.
Returns number
Inherited from Texture.getTextureSourceIndex
- Defined in types/phaser.d.ts:109033

has

has(name: string): boolean
Checks to see if a Frame matching the given key exists within this Texture.
Parameters
- name: string
  The key of the Frame to check for.
Returns boolean
Inherited from Texture.has
- Defined in types/phaser.d.ts:109014

putData

putData(
    imageData: ImageData,
    x: number,
    y: number,
    dirtyX?: number,
    dirtyY?: number,
    dirtyWidth?: number,
    dirtyHeight?: number,
): this
Puts the ImageData into the context of this CanvasTexture at the given coordinates.
Parameters
- imageData: ImageData
  The ImageData to put at the given location.
- x: number
  The x coordinate to put the imageData. Must lay within the dimensions of this CanvasTexture and be an integer.
- y: number
  The y coordinate to put the imageData. Must lay within the dimensions of this CanvasTexture and be an integer.
- OptionaldirtyX: number
  Horizontal position (x coordinate) of the top-left corner from which the image data will be extracted. Default 0.
- OptionaldirtyY: number
  Vertical position (x coordinate) of the top-left corner from which the image data will be extracted. Default 0.
- OptionaldirtyWidth: number
  Width of the rectangle to be painted. Defaults to the width of the image data.
- OptionaldirtyHeight: number
  Height of the rectangle to be painted. Defaults to the height of the image data.
Returns this
- Defined in types/phaser.d.ts:108114

refresh

refresh(): Textures.CanvasTexture
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.

Returns Textures.CanvasTexture
- Defined in types/phaser.d.ts:108169

remove

remove(name: string): boolean
Removes the given Frame from this Texture. The Frame is destroyed immediately.

Any Game Objects using this Frame should stop using it before you remove it, as it does not happen automatically.
Parameters
- name: string
  The key of the Frame to remove.
Returns boolean
Inherited from Texture.remove
- Defined in types/phaser.d.ts:109008

setDataSource

setDataSource(
    data:
        | HTMLImageElement
        | HTMLCanvasElement
        | HTMLImageElement[]
        | HTMLCanvasElement[],
): void
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
- data: HTMLImageElement | HTMLCanvasElement | HTMLImageElement[] | HTMLCanvasElement[]
  The source image.
Returns void
Inherited from Texture.setDataSource
- Defined in types/phaser.d.ts:109085

setFilter

setFilter(filterMode: FilterMode): void
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
- filterMode: FilterMode
  The Filter Mode.
Returns void
Inherited from Texture.setFilter
- Defined in types/phaser.d.ts:109097

setPixel

setPixel(
    x: number,
    y: number,
    red: number,
    green: number,
    blue: number,
    alpha?: number,
): this
Sets a pixel in the CanvasTexture to the given color and alpha values.

This is an expensive operation to run in large quantities, so use sparingly.
Parameters
- x: number
  The x coordinate of the pixel to get. Must lay within the dimensions of this CanvasTexture and be an integer.
- y: number
  The y coordinate of the pixel to get. Must lay within the dimensions of this CanvasTexture and be an integer.
- red: number
  The red color value. A number between 0 and 255.
- green: number
  The green color value. A number between 0 and 255.
- blue: number
  The blue color value. A number between 0 and 255.
- Optionalalpha: number
  The alpha value. A number between 0 and 255. Default 255.
Returns this
- Defined in types/phaser.d.ts:108102

setSize

setSize(width: number, height?: number): Textures.CanvasTexture
Changes the size of this Canvas Texture.
Parameters
- width: number
  The new width of the Canvas.
- Optionalheight: number
  The new height of the Canvas. If not given it will use the width as the height.
Returns Textures.CanvasTexture
- Defined in types/phaser.d.ts:108197

setSmoothPixelArt

setSmoothPixelArt(value: boolean): void
Set the smoothPixelArt property for this Texture. If true, it will also run setFilter(Phaser.Textures.FilterMode.LINEAR) to enable the necessary linear filtering. If false, it will not change the filter mode, as it doesn't know the previous state, nor is it necessary to change it.
Parameters
- value: boolean
  The value of the smoothPixelArt property.
Returns void
Inherited from Texture.setSmoothPixelArt
- Defined in types/phaser.d.ts:109107

update

update(): Textures.CanvasTexture
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.

Returns Textures.CanvasTexture
- Defined in types/phaser.d.ts:108068

Class CanvasTexture

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns Textures.CanvasTexture

Properties

buffer

Readonlycanvas

Readonlycontext

customData

data

dataSource

firstFrame

frames

frameTotal

Readonlyheight

imageData

key

manager

pixels

smoothPixelArt

source

Readonlywidth

Methods

add

Parameters

Returns Frame

clear

Parameters

Returns Textures.CanvasTexture

destroy

Returns void

draw

Parameters

Returns Textures.CanvasTexture

drawFrame

Parameters

Returns Textures.CanvasTexture

get

Parameters

Returns Frame

getCanvas

Returns HTMLCanvasElement

getContext

Returns CanvasRenderingContext2D

getData

Parameters

Returns ImageData

getDataSourceImage

Parameters

Returns HTMLImageElement | HTMLCanvasElement

getFrameBounds

Parameters

Returns RectangleLike

getFrameNames

Parameters

Returns string[]

getFramesFromTextureSource

Parameters

Returns Frame[]

getIndex

Parameters

Returns number

getPixel

Parameters

Returns Display.Color

getPixels

Parameters

Returns PixelConfig[][]

getSourceImage

Parameters

Returns HTMLImageElement | GameObjects.RenderTexture | HTMLCanvasElement

getTextureSourceIndex

Parameters

Returns number

`Readonly`canvas

`Readonly`context

`Readonly`height

`Readonly`width