Shader

A Shader Game Object.

This Game Object allows you to easily add a quad with its own shader

into the display list, and manipulate it as you would any other Game Object,

including scaling, rotating, positioning and adding to Containers.

The Shader can be made interactive and used for input events.

It can also be used in filters to create visually stunning effects.

It works by creating a custom RenderNode which runs a custom shader program

to draw a quad. The shader program can be loaded from the Shader Cache,

or provided in-line as strings.

Please see the Phaser 3 Examples GitHub repo for several examples

of loading and creating shaders dynamically.

Due to the way in which they work, you cannot directly change the alpha

of a Shader. It should be handled via uniforms in the shader code itself.

By default, a Shader has a uniform called uProjectionMatrix

which is set automatically.

You can control additional uniforms using the setupUniforms method

in the Shader configuration object, which runs every time the shader renders.

Shaders are stand-alone renders: they finish any current render batch

and run once by themselves. As this costs a draw call, you should use them sparingly.

If you need to have a fully batched custom shader, then please look at using

a custom RenderNode instead. However, for background or special masking effects,

they are extremely effective.

Note: be careful when using texture coordinates in shader code.

The built-in variable gl_FragCoord and the default uniform outTexCoord

both use WebGL coordinates, which are 0,0 in the bottom-left.

Additionally, gl_FragCoord says it's in "window relative" coordinates.

But this is actually relative to the framebuffer size.

Constructor

new Shader(scene, config, [x], [y], [width], [height], [textures])

Parameters

name	type	optional	default	description
scene	Phaser.Scene	No		The Scene to which this Game Object belongs.
config	string | Phaser.Types.GameObjects.Shader.ShaderQuadConfig	No		The configuration object this Shader will use. It can also be a key that corresponds to a shader in the shader cache, which will be used as fragmentKey in a new config object.
x	number	Yes	0	The horizontal position of this Game Object in the world.
y	number	Yes	0	The vertical position of this Game Object in the world.
width	number	Yes	128	The width of the Game Object.
height	number	Yes	128	The height of the Game Object.
textures	Array.<string> | Array.<Phaser.Textures.Texture>	Yes		The textures that the shader uses, if any. If you intend to define the textures later, use '__DEFAULT' as a placeholder, to avoid initialization errors.

---

Scope: static

Extends

Phaser.GameObjects.GameObject
Phaser.GameObjects.Components.BlendMode
Phaser.GameObjects.Components.ComputedSize
Phaser.GameObjects.Components.Depth
Phaser.GameObjects.Components.GetBounds
Phaser.GameObjects.Components.Origin
Phaser.GameObjects.Components.ScrollFactor
Phaser.GameObjects.Components.Transform
Phaser.GameObjects.Components.Visible

Source: src/gameobjects/shader/Shader.js#L17
Since: 3.17.0

Inherited Members

From Phaser.GameObjects.Components.BlendMode:

• blendMode

From Phaser.GameObjects.Components.ComputedSize:

• displayHeight
• displayWidth
• height
• width

From Phaser.GameObjects.Components.Depth:

• depth

From Phaser.GameObjects.Components.Filters:

• filterCamera
• filters
• filtersAutoFocus
• filtersFocusContext
• filtersForceComposite
• maxFilterSize
• renderFilters

From Phaser.GameObjects.Components.Origin:

• displayOriginX
• displayOriginY
• originX
• originY

From Phaser.GameObjects.Components.ScrollFactor:

• scrollFactorX
• scrollFactorY

From Phaser.GameObjects.Components.Transform:

• angle
• hasTransformComponent
• rotation
• scale
• scaleX
• scaleY
• w
• x
• y
• z

From Phaser.GameObjects.Components.Visible:

• visible

From Phaser.GameObjects.GameObject:

• active
• body
• cameraFilter
• data
• displayList
• ignoreDestroy
• input
• name
• parentContainer
• renderFlags
• scene
• state
• tabIndex
• type
• vertexRoundMode

---

Public Members

drawingContext

drawingContext: Phaser.Renderer.WebGL.DrawingContext

Description:

The drawing context containing the framebuffer and texture that the shader is rendered to.

This is only set if the shader is rendering to a texture.

Source: src/gameobjects/shader/Shader.js#L166
Since: 4.0.0

---

glTexture

glTexture: Phaser.Renderer.WebGL.Wrappers.WebGLTextureWrapper

Description:

A reference to the WebGLTextureWrapper this Shader is rendering to.

This property is only set if you have called Shader.setRenderToTexture.

Source: src/gameobjects/shader/Shader.js#L176
Since: 3.19.0

---

renderNode

renderNode: Phaser.Renderer.WebGL.RenderNodes.ShaderQuad

Description:

The underlying RenderNode object that the shader uses to render with.

Source: src/gameobjects/shader/Shader.js#L144
Since: 4.0.0

---

renderToTexture

renderToTexture: boolean

Description:

A flag that indicates if this Shader has been set to render to a texture instead of the display list.

This property is true if you have called Shader.setRenderToTexture, otherwise it's false.

A Shader that is rendering to a texture does not appear on the display list.

Source: src/gameobjects/shader/Shader.js#L186
Since: 3.19.0

---

texture

texture: Phaser.Textures.Texture

Description:

A reference to the Phaser.Textures.Texture that has been stored in the Texture Manager for this Shader.

This property is only set if you have called Shader.setRenderToTexture with a key, otherwise it is null.

Source: src/gameobjects/shader/Shader.js#L200
Since: 3.19.0

---

textureCoordinateBottomLeft

textureCoordinateBottomLeft: Phaser.Math.Vector2

Description:

The bottom-left texture coordinate of the shader.

This is set to 0,0 by default. It uses WebGL texture coordinates.

Source: src/gameobjects/shader/Shader.js#L231
Since: 4.0.0

---

textureCoordinateBottomRight

textureCoordinateBottomRight: Phaser.Math.Vector2

Description:

The bottom-right texture coordinate of the shader.

This is set to 1,0 by default. It uses WebGL texture coordinates.

Source: src/gameobjects/shader/Shader.js#L241
Since: 4.0.0

---

textureCoordinateTopLeft

textureCoordinateTopLeft: Phaser.Math.Vector2

Description:

The top-left texture coordinate of the shader.

This is set to 0,1 by default. It uses WebGL texture coordinates.

Source: src/gameobjects/shader/Shader.js#L211
Since: 4.0.0

---

textureCoordinateTopRight

textureCoordinateTopRight: Phaser.Math.Vector2

Description:

The top-right texture coordinate of the shader.

This is set to 1,1 by default. It uses WebGL texture coordinates.

Source: src/gameobjects/shader/Shader.js#L221
Since: 4.0.0

---

textures

textures: Array.<Phaser.Textures.Texture>

Description:

The textures that the shader uses.

These will be assigned to texture units 0 to N when the shader is

rendered, where N is textures.length - 1.

Source: src/gameobjects/shader/Shader.js#L133
Since: 4.0.0

---

Inherited Methods

From Phaser.Events.EventEmitter:

• addListener
• emit
• eventNames
• listenerCount
• listeners
• off
• on
• once
• removeAllListeners
• removeListener
• shutdown

From Phaser.GameObjects.Components.BlendMode:

• setBlendMode

From Phaser.GameObjects.Components.ComputedSize:

• setDisplaySize
• setSize

From Phaser.GameObjects.Components.Depth:

• setAbove
• setBelow
• setDepth
• setToBack
• setToTop

From Phaser.GameObjects.Components.Filters:

• enableFilters
• focusFilters
• focusFiltersOnCamera
• focusFiltersOverride
• renderWebGLFilters
• setFiltersAutoFocus
• setFiltersFocusContext
• setFiltersForceComposite
• setFilterSize
• setRenderFilters
• willRenderFilters

From Phaser.GameObjects.Components.GetBounds:

• getBottomCenter
• getBottomLeft
• getBottomRight
• getBounds
• getCenter
• getLeftCenter
• getRightCenter
• getTopCenter
• getTopLeft
• getTopRight

From Phaser.GameObjects.Components.Origin:

• setDisplayOrigin
• setOrigin
• setOriginFromFrame
• updateDisplayOrigin

From Phaser.GameObjects.Components.RenderSteps:

• addRenderStep
• renderWebGLStep

From Phaser.GameObjects.Components.ScrollFactor:

• setScrollFactor

From Phaser.GameObjects.Components.Transform:

• copyPosition
• getLocalPoint
• getLocalTransformMatrix
• getParentRotation
• getWorldPoint
• getWorldTransformMatrix
• setAngle
• setPosition
• setRandomPosition
• setRotation
• setScale
• setW
• setX
• setY
• setZ

From Phaser.GameObjects.Components.Visible:

• setVisible

From Phaser.GameObjects.GameObject:

• addedToScene
• addToDisplayList
• addToUpdateList
• destroy
• disableInteractive
• getData
• getDisplayList
• getIndexList
• incData
• removedFromScene
• removeFromDisplayList
• removeFromUpdateList
• removeInteractive
• setActive
• setData
• setDataEnabled
• setInteractive
• setName
• setState
• setVertexRoundMode
• toggleData
• toJSON
• update
• willRender
• willRoundVertices

---

Public Methods

getUniform

<instance> getUniform(name)

Description:

Returns the current value of a uniform from the render node.

This value is actually copied to all shaders that use it.

Modifications to non-primitive values such as arrays and objects

will modify the original.

It's generally better to use the setupUniforms function in the

shader configuration object to set uniform values on changing uniforms.

This method is provided in the spirit of reading back the values.

Parameters:

name	type	optional	description
name	string	No	The name of the uniform to get.

Returns: any - The value of the uniform.

Source: src/gameobjects/shader/Shader.js#L257
Since: 4.0.0

---

preDestroy

<instance> preDestroy()

Description:

Internal destroy handler, called as part of the destroy process.

Access: protected

Source: src/gameobjects/shader/Shader.js#L582
Since: 3.17.0

---

renderImmediate

<instance> renderImmediate()

Description:

Render the shader immediately.

This is useful for a Shader that is not part of the display list,

but you want to use with renderToTexture.

Returns: Phaser.GameObjects.Shader - This Shader instance.

Source: src/gameobjects/shader/Shader.js#L430
Since: 4.0.0

---

setRenderToTexture

<instance> setRenderToTexture([key])

Description:

Changes this Shader so instead of rendering to the display list

it renders to a WebGL Framebuffer and Texture instead.

This allows you to use the output of this shader as a texture.

After calling this method the following properties are populated:

• Shader.drawingContext

• Shader.glTexture

Additionally, you can provide a key to this method.

Doing so will create a Phaser Texture from this Shader,

store it in Shader.texture,

and save it into the Texture Manager, allowing you to then use it for

any texture-based Game Object, such as a Sprite or Image:

var shader = this.add.shader('myShader', x, y, width, height);



shader.setRenderToTexture('doodle');



this.add.image(400, 300, 'doodle');

Note that it stores an active reference to this Shader. That means as this shader updates,

so does the texture and any object using it to render with. Also, if you destroy this

shader, be sure to clear any objects that may have been using it as a texture too.

By default it will create a single base texture. You can add frames to the texture

by using the Texture.add method. After doing this, you can then allow Game Objects

to use a specific frame from a Render Texture.

If you want to update a texture only sporadically, don't use this method.

Instead, use a DynamicTexture:

var shader = this.add.shader('myShader', x, y, width, height);



var dynamic = this.textures.addDynamicTexture('myTexture', shader.width, shader.height);



// To update the texture:

dynamic.clear().draw(shader).render();

Parameters:

name	type	optional	description
key	string	Yes	The unique key to store the texture as within the global Texture Manager.

Returns: Phaser.GameObjects.Shader - This Shader instance.

Source: src/gameobjects/shader/Shader.js#L345
Since: 3.19.0

---

setTextureCoordinates

<instance> setTextureCoordinates([topLeftX], [topLeftY], [topRightX], [topRightY], [bottomLeftX], [bottomLeftY], [bottomRightX], [bottomRightY])

Description:

Set the texture coordinates of the shader.

These values are used to provide texture mapping to the shader,

and are commonly used to drive generative output.

By default, the shader uses the whole texture, the range 0-1.

The coordinates are in WebGL texture space, which is 0,0 in the bottom-left.

This method allows you to specify a region of the texture to use,

or even go outside the 0-1 bounds.

This can be useful if you want to use a single frame from a texture,

repeat the shader's texture, use a larger numeric range,

or distort the shader.

Note that a quad is made of two triangles, divided by the diagonal

from the top-left to the bottom-right. This means that some permutations

of coordinates may affect just one or the other triangle.

This can cause abrupt warping along the diagonal.

Keep an eye on your output. Rectangles and parallelograms are safe bets.

So are rotation and scaling transforms. Moving a single point is risky.

Call this method with no arguments to reset the shader to use the whole texture.

Parameters:

name	type	optional	default	description
topLeftX	number	Yes	0	The top-left x coordinate of the texture.
topLeftY	number	Yes	1	The top-left y coordinate of the texture.
topRightX	number	Yes	1	The top-right x coordinate of the texture.
topRightY	number	Yes	1	The top-right y coordinate of the texture.
bottomLeftX	number	Yes	0	The bottom-left x coordinate of the texture.
bottomLeftY	number	Yes	0	The bottom-left y coordinate of the texture.
bottomRightX	number	Yes	1	The bottom-right x coordinate of the texture.
bottomRightY	number	Yes	0	The bottom-right y coordinate of the texture.

Returns: Phaser.GameObjects.Shader - This Shader instance

Source: src/gameobjects/shader/Shader.js#L491
Since: 4.0.0

---

setTextureCoordinatesFromFrame

<instance> setTextureCoordinatesFromFrame(frame, [texture])

Description:

Set the texture coordinates of the shader from a frame.

This is a convenience method that sets the texture coordinates

to match a frame from a texture.

Parameters:

name	type	optional	description
frame	Phaser.Textures.Frame | string	No	The frame to set the texture coordinates from. If a string is given, it will be used to look up the frame in the texture.
texture	Phaser.Textures.Texture | string	Yes	The texture that the frame is from. This is only used if frame is a string. If a string is given, it will be used to look up the texture in the Texture Manager. If not given, the first member of Shader.textures is used. If Shader.textures is empty, an error will occur.

Source: src/gameobjects/shader/Shader.js#L549
Since: 4.0.0

---

setTextures

<instance> setTextures([textures])

Description:

Set the textures that the shader uses.

Some shaders don't use any textures. Some may use one or more.

The textures are assigned to texture units 0 to N when the shader is rendered,

where N is textures.length - 1.

You must set the uniforms in your shader to match these texture units.

Calling this method will replace the existing textures array with the new one.

Parameters:

name	type	optional	description
textures	Array.<string> | Array.<Phaser.Textures.Texture>	Yes	The textures that the shader uses.

Source: src/gameobjects/shader/Shader.js#L297
Since: 4.0.0

---

setUniform

<instance> setUniform(name, value)

Description:

Set the value of a uniform in the shader.

This value is actually copied to all shaders that use it.

It's generally better to use the setupUniforms function in the

shader configuration object to set uniform values on changing uniforms.

Use this method to set uniforms just once.

Parameters:

name	type	optional	description
name	string	No	The name of the uniform to set.
value	any	No	The value to set the uniform to.

Returns: Phaser.GameObjects.Shader - undefined

Source: src/gameobjects/shader/Shader.js#L277
Since: 4.0.0

---

setupUniforms

<instance> setupUniforms(setUniform, drawingContext)

Description:

The function which sets uniforms for the shader.

This is called automatically during rendering.

It is set from the config object passed in the constructor.

You should use this function to set any uniform values you need for your shader to run.

You can set this function directly after object creation,

but it's recommended to use the config object

to keep your logic encapsulated.

The function is invoked with two arguments: setUniform and drawingContext.

setUniform is a function that takes two arguments: a string (the name of the uniform) and a value.

Ensure that the value matches the expected type in the shader.

You don't need to be too precise, as the system will convert

e.g. Array and Float32Array types as needed.

To set an array in a shader, append [0] to the uniform name.

drawingContext is a reference to the current drawing context,

which may be useful if you need to query the camera or similar.

Note that uProjectionMatrixis set for you automatically.

Parameters:

name	type	optional	description
setUniform	function	No	The function which sets uniforms. (name: string, value: any) => void.
drawingContext	Phaser.Renderer.WebGL.DrawingContext	No	A reference to the current drawing context.

Source: src/gameobjects/shader/Shader.js#L446
Since: 4.0.0

---