Shader

Introduction

A quad with its own shader, built-in game object of phaser.

• Author: Richard Davey

Usage

Load GLSL

scene.load.glsl(key, url);

Reference: load glsl

Add shader object

var shader = scene.add.shader(key, x, y, width, height, textures);

• key : The key of the shader to use from the shader cache, or a BaseShader instance.
• x, y : Position.
• width, height : Size.
• textures : Optional array of texture keys to bind to the iChannel0, iChannel1, iChannel2, iChannel3 uniforms.

Note

Lots of shaders expect textures to be power-of-two sized.

Add shader object from JSON

var shader = scene.make.shader({
    x: 0,
    y: 0,
    key: '',

    // angle: 0,
    // alpha: 1
    // flipX: true,
    // flipY: true,
    // scale : {
    //    x: 1,
    //    y: 1
    //},
    // origin: {x: 0.5, y: 0.5},

    add: true
});

• key : The key of the shader to use from the shader cache, or a BaseShader instance.
  • A string
  • An array of string to pick one element at random
• x, y, scale.x, scale.y :
  • A number
  • A callback to get return value

    function() { return 0; }
    

  • Random integer between min and max

    { randInt: [min, max] }
    

  • Random float between min and max

    { randFloat: [min, max] }
    

Custom class

• Define class

  class MyShader extends Phaser.GameObjects.Shader {
      constructor(scene, key, x, y, width, height, textures) {
          super(scene, key, x, y, width, height, textures);
          // ...
          scene.add.existing(this);
      }
      // ...
  
      // preUpdate(time, delta) {}
  }
  

  • scene.add.existing(gameObject) : Adds an existing Game Object to this Scene.
    • If the Game Object renders, it will be added to the Display List.
    • If it has a preUpdate method, it will be added to the Update List.
• Create instance

  var shader = new MyShader(scene, key, x, y, width, height, textures);
  

Sampler2D uniform

• Default uniform mappings :
  • resolution (2f) - Set to the size of this shader.
    • uniform vec2 resolution; in GLSL.
  • time (1f) - The elapsed game time, in seconds.
    • uniform float time; in GLSL.
  • mouse (2f) - If a pointer has been bound (with setPointer), this uniform contains its position each frame.
    • uniform vec2 mouse; in GLSL.
  • date (4fv) - A vec4 containing the year, month, day and time in seconds.
    • uniform vec4 date; in GLSL.
  • sampleRate (1f) - Sound sample rate. 44100 by default.
    • uniform float sampleRate; in GLSL.
  • iChannel0...3 (sampler2D) - Input channels 0 to 3. null by default. uniform sampler2D iChannel0; in GLSL.
• Get uniform object

  var uniform = shader.getUniform(key);
  

  • Texture key

    var textureKey = uniform.textureKey;
    

  • Get texture key of iChannel0, iChannel1, iChannel2, iChannel3 sampler2D uniform.

    var textureKey = shader.getUniform('iChannel0').textureKey;
    var textureKey = shader.getUniform('iChannel1').textureKey;
    var textureKey = shader.getUniform('iChannel2').textureKey;
    var textureKey = shader.getUniform('iChannel3').textureKey;
    

• Sets a property of a uniform already present on this shader.

  shader.setUniform(key, value);
  

  • key : The key of the uniform to modify. Use dots for deep properties, i.e. resolution.value.x.
• Sets a sampler2D uniform from texture manager.

  shader.setChannel0(textureKey);
  shader.setChannel1(textureKey);
  shader.setChannel2(textureKey);
  shader.setChannel3(textureKey);
  // shader.setChannel0(textureKey, textureData);
  // shader.setChannel1(textureKey, textureData);
  // shader.setChannel2(textureKey, textureData);
  // shader.setChannel3(textureKey, textureData);
  

  or

  shader.setSampler2D(uniformKey, textureKey, textureIndex);
  // shader.setSampler2D(uniformKey, textureKey, textureIndex, textureData);
  

  • uniformKey : 'iChannel0', 'iChannel1', 'iChannel2', or 'iChannel3'.
  • textureIndex : 0(for iChannel0), 1(for iChannel1), 2(for iChannel2), 3(for iChannel3).
  • textureData : Additional texture data.
  • textureKey: Key from the Texture Manager cache. It cannot be a single frame from a texture, only the full image. Lots of shaders expect textures to be power-of-two sized.
• Sets a sampler2D uniform from a webgl texture.

  shader.setSampler2DBuffer(uniformKey, texture, width, height, textureIndex);
  // shader.setSampler2DBuffer(uniformKey, texture, width, height, textureIndex, textureData);
  

  • uniformKey : 'iChannel0', 'iChannel1', 'iChannel2', or 'iChannel3'.
  • width, height : The width, height of the texture.
  • textureIndex : 0(for iChannel0), 1(for iChannel1), 2(for iChannel2), 3(for iChannel3).
  • textureData : Additional texture data.

Other uniforms

• mouse, a pointer parameter.
  • Get

    var pointer = shader.pointer;
    

  • Set

    shader.setPointer(pointer);
    

    • pointer : {x, y}
• time, the elapsed game time, in seconds.
  • Get

    var time = shader.getUniform('time').value;
    // var time = shader.uniforms.time.value
    

  • Set

    shader.setUniform('time.value', time);
    

Output

• Render to Display list, by default.
• Redirect render result to internal webgl texture.

  shader.setRenderToTexture();
  var texture = shader.glTexture;
  

• Redirect render result to internal webgl texture, and sample2D from buffer.

  shader.setRenderToTexture(undefined, true);
  var texture = shader.glTexture;
  

• Redirect render result to texture manager, for texture-based game object.

  shader.setRenderToTexture(textureKey);
  // var texture = shader.glTexture;
  

• Redirect render result to texture manager, and Sample2D from buffer.

  shader.setRenderToTexture(textureKey, true);
  // var texture = shader.glTexture;
  

Texture routing

graph TB

TextureManagerIn["Texture manager"] --> |"shader.setSampler2D()"| Sampler2D["Samplers:<br>iChannel0<br>iChannel1<br>iChannel2<br>iChannel3"]
Sampler2D--> Shader["shader<br>Shader game object"]
Shader --> DisplayList["Display list"]
Shader --> |"shader.setRenderToTexture()"| InternalTexture["shader.glTexture"]
InternalTexture -.-> |"Texture key"| TextureManagerOut["Texture manager"]
TextureManagerOut -.-> GameObject["Image game object"]
GameObject -.-> DisplayList

WebGLTexture["WebGl texture<br>gameObject.glTexture"] --> |"shader.setSampler2DBuffer()"| Sampler2D
InternalTexture --> WebGLTexture

subgraph Output
DisplayList
GameObject
TextureManagerOut
end

subgraph Input
TextureManagerIn
WebGLTexture
end

Other properties

See game object

Create mask

var mask = shader.createBitmapMask();

See mask

BaseShader

var baseShader = new Phaser.Display.BaseShader(key, fragmentSrc, vertexSrc, uniforms);

• key : The key of this shader
• fragmentSrc : The fragment source for the shader.
• vertexSrc : The vertex source for the shader.
  • undefined, or '' : Use default vertex source.
• uniforms : Optional object defining the uniforms the shader uses.

  {
      uniformName : {type: uniformType, value: initValue},
      ...
  }
  

  • uniformName : Uniform name in fragment source.
  • uniformType, initValue : Type and initial value of uniform.
    • '1f' : initValue is a single float value.
      • Example : time: { type: '1f', value: 0 }
    • '2f' : initValue is float numbers {x, y}.
      • Example : resolution: { type: '2f', value: { x: this.width, y: this.height } }
    • '3f' : initValue is float numbers {x, y, z}.
      • Example : color: { type: '3f', value: {x: 0, y: 0, z: 0}}
    • '4f' : initValue is float numbers {x, y, z, w}.