Phaser API Documentation

  Version: 
Filter

Instances of the WebGLShader class belong to the WebGL Pipeline classes. When the pipeline is created it will create an instance of this class for each one of its shaders, as defined in the pipeline configuration.

This class encapsulates everything needed to manage a shader in a pipeline, including the shader attributes and uniforms, as well as lots of handy methods such as set2f, for setting uniform values on this shader.

Typically, you do not create an instance of this class directly, as it works in unison with the pipeline to which it belongs. You can gain access to this class via a pipeline's shaders array, post-creation.

Constructor:

new WebGLShader(pipeline, name, vertexShader, fragmentShader, attributes)

Parameters:

name type description
pipeline Phaser.Renderer.WebGL.WebGLPipeline

The WebGLPipeline to which this Shader belongs.

name string

The name of this Shader.

vertexShader string

The vertex shader source code as a single string.

fragmentShader string

The fragment shader source code as a single string.

attributes Array.<Phaser.Types.Renderer.WebGL.WebGLPipelineAttributeConfig>

An array of attributes.

Since: 3.50.0

Members

Description:

Array of objects that describe the vertex attributes.

Type:
Since: 3.50.0
Focus
Focus
fragSrc: string
Focus
Focus

Description:

The fragment shader source code.

Type:
string
Since: 3.60.0
Focus
Focus
gl: WebGLRenderingContext
Focus
Focus

Description:

A reference to the WebGL Rendering Context the WebGL Renderer is using.

Type:
WebGLRenderingContext
Since: 3.50.0
Focus
Focus
name: string
Focus
Focus

Description:

The name of this shader.

Type:
string
Since: 3.50.0
Focus
Focus

Description:

A reference to the WebGLPipeline that owns this Shader.

A Shader class can only belong to a single pipeline.

Type:
Since: 3.50.0
Focus
Focus

Description:

The WebGLProgram created from the vertex and fragment shaders.

Type:
Since: 3.50.0
Focus
Focus

Description:

A reference to the WebGLRenderer instance.

Type:
Since: 3.50.0
Focus
Focus

Description:

The active uniforms that this shader has.

This is an object that maps the uniform names to their WebGL location and cached values.

It is populated automatically via the createUniforms method.

Type:
Since: 3.50.0
Focus
Focus
vertSrc: string
Focus
Focus

Description:

The vertex shader source code.

Type:
string
Since: 3.60.0
Focus
Focus
vertexComponentCount: number
Focus
Focus

Description:

The amount of vertex attribute components of 32 bit length.

Type:
number
Since: 3.50.0
Focus
Focus
<readonly> vertexSize: number
Focus
Focus

Description:

The size, in bytes, of a single vertex.

This is derived by adding together all of the vertex attributes.

For example, the Multi Pipeline has the following attributes:

inPosition - (size 2 x gl.FLOAT) = 8 inTexCoord - (size 2 x gl.FLOAT) = 8 inTexId - (size 1 x gl.FLOAT) = 4 inTintEffect - (size 1 x gl.FLOAT) = 4 inTint - (size 4 x gl.UNSIGNED_BYTE) = 4

The total, in this case, is 8 + 8 + 4 + 4 + 4 = 28.

This is calculated automatically during the createAttributes method.

Type:
number
Since: 3.50.0
Focus
Focus

Methods

bind([setAttributes], [flush])
Focus
Focus

Description:

Sets the program this shader uses as being the active shader in the WebGL Renderer.

This method is called every time the parent pipeline is made the current active pipeline.

Parameters:

name type arguments Default description
setAttributes boolean <optional> false

Should the vertex attribute pointers be set?

flush boolean <optional> false

Flush the pipeline before binding this shader?

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
createAttributes(attributes)
Focus
Focus

Description:

Takes the vertex attributes config and parses it, creating the resulting array that is stored in this shaders attributes property, calculating the offset, normalization and location in the process.

Calling this method resets WebGLShader.attributes, WebGLShader.vertexSize and WebGLShader.vertexComponentCount.

It is called automatically when this class is created, but can be called manually if required.

Parameters:

name type description
attributes Array.<Phaser.Types.Renderer.WebGL.WebGLPipelineAttributeConfig>

An array of attributes configs.

Since: 3.50.0
Focus
Focus
createProgram([vertSrc], [fragSrc])
Focus
Focus

Description:

This method will create the Shader Program on the current GL context.

If a program already exists, it will be destroyed and the new one will take its place.

After the program is created the uniforms will be reset and this shader will be rebound.

This is a very expensive process and if your shader is referenced elsewhere in your game those references may then be lost, so be sure to use this carefully.

However, if you need to update say the fragment shader source, then you can pass the new source into this method and it'll rebuild the program using it. If you don't want to change the vertex shader src, pass undefined as the parameter.

Parameters:

name type arguments description
vertSrc string <optional>

The source code of the vertex shader. If not given, uses the source already defined in this Shader.

fragSrc string <optional>

The source code of the fragment shader. If not given, uses the source already defined in this Shader.

Returns:
Description:

This WebGLShader instance.

Since: 3.60.0
Focus
Focus
createUniforms()
Focus
Focus

Description:

Sets up the WebGLShader.uniforms object, populating it with the names and locations of the shader uniforms this shader requires.

It works by first calling gl.getProgramParameter(program.webGLProgram, gl.ACTIVE_UNIFORMS) to find out how many active uniforms this shader has. It then iterates through them, calling gl.getActiveUniform to get the WebGL Active Info from each one. Finally, the name and location are stored in the local array.

This method is called automatically when this class is created.

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
destroy()
Focus
Focus

Description:

Removes all external references from this class and deletes the WebGL program from the WebGL context.

Does not remove this shader from the parent pipeline.

Since: 3.50.0
Focus
Focus
hasUniform(name)
Focus
Focus

Description:

Checks to see if the given uniform name exists and is active in this shader.

Parameters:

name type description
name string

The name of the uniform to check for.

Returns:
Description:

true if the uniform exists, otherwise false.

Type:
  • boolean
Since: 3.50.0
Focus
Focus
rebind()
Focus
Focus

Description:

Sets the program this shader uses as being the active shader in the WebGL Renderer.

Then resets all of the attribute pointers.

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
resetUniform(name)
Focus
Focus

Description:

Resets the cached values of the given uniform.

Parameters:

name type description
name string

The name of the uniform to reset.

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
set1f(name, x)
Focus
Focus

Description:

Sets a 1f uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

x number

The new value of the float uniform.

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
set1fv(name, arr)
Focus
Focus

Description:

Sets a 1fv uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

arr Array.<number> | Float32Array

The new value to be used for the uniform variable.

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
set1i(name, x)
Focus
Focus

Description:

Sets a 1i uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

x number

The new value of the int uniform.

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
set1iv(name, arr)
Focus
Focus

Description:

Sets a 1iv uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

arr Array.<number> | Float32Array

The new value to be used for the uniform variable.

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
set2f(name, x, y)
Focus
Focus

Description:

Sets a 2f uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

x number

The new X component of the vec2 uniform.

y number

The new Y component of the vec2 uniform.

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
set2fv(name, arr)
Focus
Focus

Description:

Sets a 2fv uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

arr Array.<number> | Float32Array

The new value to be used for the uniform variable.

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
set2i(name, x, y)
Focus
Focus

Description:

Sets a 2i uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

x number

The new X component of the ivec2 uniform.

y number

The new Y component of the ivec2 uniform.

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
set2iv(name, arr)
Focus
Focus

Description:

Sets a 2iv uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

arr Array.<number> | Float32Array

The new value to be used for the uniform variable.

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
set3f(name, x, y, z)
Focus
Focus

Description:

Sets a 3f uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

x number

The new X component of the vec3 uniform.

y number

The new Y component of the vec3 uniform.

z number

The new Z component of the vec3 uniform.

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
set3fv(name, arr)
Focus
Focus

Description:

Sets a 3fv uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

arr Array.<number> | Float32Array

The new value to be used for the uniform variable.

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
set3i(name, x, y, z)
Focus
Focus

Description:

Sets a 3i uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

x number

The new X component of the ivec3 uniform.

y number

The new Y component of the ivec3 uniform.

z number

The new Z component of the ivec3 uniform.

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
set3iv(name, arr)
Focus
Focus

Description:

Sets a 3iv uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

arr Array.<number> | Float32Array

The new value to be used for the uniform variable.

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
set4f(name, x, y, z, w)
Focus
Focus

Description:

Sets a 4f uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

x number

X component of the uniform

y number

Y component of the uniform

z number

Z component of the uniform

w number

W component of the uniform

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
set4fv(name, arr)
Focus
Focus

Description:

Sets a 4fv uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

arr Array.<number> | Float32Array

The new value to be used for the uniform variable.

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
set4i(name, x, y, z, w)
Focus
Focus

Description:

Sets a 4i uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

x number

X component of the uniform

y number

Y component of the uniform

z number

Z component of the uniform

w number

W component of the uniform

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
set4iv(name, arr)
Focus
Focus

Description:

Sets a 4iv uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

arr Array.<number> | Float32Array

The new value to be used for the uniform variable.

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
setAttribPointers([reset])
Focus
Focus

Description:

Sets the vertex attribute pointers.

This should only be called after the vertex buffer has been bound.

It is called automatically during the bind method.

Parameters:

name type arguments Default description
reset boolean <optional> false

Reset the vertex attribute locations?

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
setBoolean(name, value)
Focus
Focus

Description:

Sets a boolean uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

value boolean

The new value of the boolean uniform.

Returns:
Description:

This WebGLShader instance.

Since: 3.60.0
Focus
Focus
setMatrix2fv(name, transpose, matrix)
Focus
Focus

Description:

Sets a matrix 2fv uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

transpose boolean

Whether to transpose the matrix. Should be false.

matrix Array.<number> | Float32Array

The new values for the mat2 uniform.

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
setMatrix3fv(name, transpose, matrix)
Focus
Focus

Description:

Sets a matrix 3fv uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

transpose boolean

Whether to transpose the matrix. Should be false.

matrix Float32Array

The new values for the mat3 uniform.

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
setMatrix4fv(name, transpose, matrix)
Focus
Focus

Description:

Sets a matrix 4fv uniform value based on the given name on this shader.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type description
name string

The name of the uniform to set.

transpose boolean

Should the matrix be transpose

matrix Float32Array

Matrix data

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
setUniform1(setter, name, value1, [skipCheck])
Focus
Focus

Description:

Sets the given uniform value/s based on the name and GL function.

This method is called internally by other methods such as set1f and set3iv.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type arguments Default description
setter function

The GL function to call.

name string

The name of the uniform to set.

value1 boolean | number | Array.<number> | Float32Array

The new value of the uniform.

skipCheck boolean <optional> false

Skip the value comparison?

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
setUniform2(setter, name, value1, value2, [skipCheck])
Focus
Focus

Description:

Sets the given uniform value/s based on the name and GL function.

This method is called internally by other methods such as set1f and set3iv.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type arguments Default description
setter function

The GL function to call.

name string

The name of the uniform to set.

value1 boolean | number | Array.<number> | Float32Array

The new value of the uniform.

value2 boolean | number | Array.<number> | Float32Array

The new value of the uniform.

skipCheck boolean <optional> false

Skip the value comparison?

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
setUniform3(setter, name, value1, value2, value3, [skipCheck])
Focus
Focus

Description:

Sets the given uniform value/s based on the name and GL function.

This method is called internally by other methods such as set1f and set3iv.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type arguments Default description
setter function

The GL function to call.

name string

The name of the uniform to set.

value1 boolean | number | Array.<number> | Float32Array

The new value of the uniform.

value2 boolean | number | Array.<number> | Float32Array

The new value of the uniform.

value3 boolean | number | Array.<number> | Float32Array

The new value of the uniform.

skipCheck boolean <optional> false

Skip the value comparison?

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
setUniform4(setter, name, value1, value2, value3, value4, [skipCheck])
Focus
Focus

Description:

Sets the given uniform value/s based on the name and GL function.

This method is called internally by other methods such as set1f and set3iv.

The uniform is only set if the value/s given are different to those previously set.

This method works by first setting this shader as being the current shader within the WebGL Renderer, if it isn't already. It also sets this shader as being the current one within the pipeline it belongs to.

Parameters:

name type arguments Default description
setter function

The GL function to call.

name string

The name of the uniform to set.

value1 boolean | number | Array.<number> | Float32Array

The new value of the uniform.

value2 boolean | number | Array.<number> | Float32Array

The new value of the uniform.

value3 boolean | number | Array.<number> | Float32Array

The new value of the uniform.

value4 boolean | number | Array.<number> | Float32Array

The new value of the uniform.

skipCheck boolean <optional> false

Skip the value comparison?

Returns:
Description:

This WebGLShader instance.

Since: 3.50.0
Focus
Focus
syncUniforms()
Focus
Focus

Description:

Repopulate uniforms on the GPU.

This is called automatically by the pipeline when the context is lost and then recovered. By the time this method is called, the WebGL resources are already recreated, so we just need to re-populate them.

Since: 3.80.0
Focus
Focus