melonJS
    Preparing search index...

    Class ShaderEffect

    A simplified shader class for applying custom fragment effects to renderables. Only requires a fragment apply() function — the vertex shader, uniforms, and texture sampling boilerplate are handled automatically. In Canvas mode, the shader is silently disabled (all methods become no-ops).

    // create a grayscale effect
    mySprite.shader = new ShaderEffect(renderer, `
        vec4 apply(vec4 color, vec2 uv) {
            float gray = dot(color.rgb, vec3(0.299, 0.587, 0.114));
            return vec4(vec3(gray), color.a);
        }
    `);

    // create an effect with a custom uniform
    const pulse = new ShaderEffect(renderer, `
        uniform float uTime;
        vec4 apply(vec4 color, vec2 uv) {
            float brightness = 0.8 + 0.2 * sin(uTime * 3.0);
            return vec4(color.rgb * brightness, color.a);
        }
    `);
    mySprite.shader = pulse;
    // update the uniform each frame
    pulse.setUniform("uTime", time);

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    _enabledBeforeSuspend _textureOverflowWarned destroyed enabled shared

    Methods

    clone destroy setTexture setTime setUniform

    Constructors

    • Parameters

      • renderer: any

        the current renderer instance

      • fragmentBody: string

        GLSL code containing a vec4 apply(vec4 color, vec2 uv) function that receives the sampled pixel color and UV coordinates, and returns the modified color. You can declare additional uniform variables before the apply() function.

      • Optionalprecision: string

        float precision ('lowp', 'mediump' or 'highp')

      Returns ShaderEffect

    Properties

    _enabledBeforeSuspend

    _enabledBeforeSuspend: boolean | undefined

    _textureOverflowWarned

    _textureOverflowWarned: boolean | undefined
    destroyed: boolean = false

    true once destroy has been called. Distinct from enabled — which also toggles transiently across a context lost / restored cycle — to give callers a stable signal for "this effect has been explicitly released."

    enabled: boolean = false

    whether this effect is active (false in Canvas mode, false after destroy, and false while the WebGL context is suspended between an ONCONTEXT_LOST and the matching ONCONTEXT_RESTORED event).

    shared: boolean = false

    When true, a renderable will NOT auto-destroy this effect when it is removed from its postEffects (via the shader setter, Renderable#removePostEffect, Renderable#clearPostEffects) or when the renderable itself is destroyed. Set this on an effect shared across several renderables so one of them going away doesn't free the GL program still used by the others — you then own its lifecycle and call destroy yourself.

    false

    Methods

    • Create an independent copy of this effect, compiled as its own GL program. Use it when several renderables need the same effect with different uniform values — a single instance has a single set of uniforms, shared by everything it is assigned to.

      The clone copies the recipe: the fragment source, float precision, every uniform value set so far, and any extra textures bound via setTexture (the clone uploads and owns its own GL copies). It does NOT copy ownership or lifecycle state — in particular the clone's shared flag is always reset to false, even when cloning a shared shader (such as one returned by loader.getShader()): the clone is caller-owned and will be auto-destroyed by the renderable it is assigned to, exactly like a hand-constructed effect. Set shared = true on the clone yourself if you intend to reuse it across several renderables.

      Returns ShaderEffect

      a new, caller-owned effect (shared === false)

      // the loader's shader is ONE shared program — one uniform state for all
      sprite.shader = loader.getShader("flash");
      // the boss needs its own intensity — clone a private, caller-owned copy
      boss.shader = loader.getShader("flash").clone();
      boss.shader.setUniform("uIntensity", 0.9);

    • destroy this shader effect. Idempotent — calling destroy twice is safe. Unsubscribes from the renderer's context-lost / restored events so a destroyed effect is not auto-reactivated.

      Returns void

    • Bind an extra texture to a named sampler2D uniform in this shader, so a custom effect can read a second texture — a noise map, mask, gradient, flow/lookup table — besides the sprite/target it post-processes (uSampler). The engine uploads, caches, and re-binds it to a reserved texture unit each time the effect draws, and points the sampler uniform at it — no raw WebGL texture-unit juggling.

      Declare the sampler in your fragment (uniform sampler2D <name>;) and pass that name here. Any engine texture works — e.g. noiseTexture.getTexture(). No-op in Canvas mode.

      Parameters

      • name: string

        the sampler2D uniform name declared in the fragment

      • image: ImageBitmap | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas

        the texture source

      • Optionalrepeat: "repeat" | "no-repeat" | "repeat-x" | "repeat-y" = "no-repeat"

        wrap mode; use "repeat" for a tiled/scrolled texture (power-of-two size under WebGL 1)

      Returns ShaderEffect

      this effect for chaining

      // "water": distort the sprite by a static noise texture scrolled over time
      const noise = new me.NoiseTexture2d({ width: 256, height: 256, seamless: true });
      const water = new me.ShaderEffect(renderer, `
          uniform sampler2D uNoise;
          uniform float uTime;
          vec4 apply(vec4 color, vec2 uv) {
              vec2 flow = texture2D(uNoise, uv + uTime * 0.03).rg - 0.5;
              return texture2D(uSampler, uv + flow * 0.02);
          }`);
      water.setTexture("uNoise", noise.getTexture(), "repeat");
      waterSprite.shader = water;
      // each frame, in your Stage's update(dt):
      water.setTime(me.timer.getTime() / 1000);

    • Set the shader's uTime uniform (elapsed time, in seconds). A convenience over setUniform("uTime", ...); call it once per frame from your update loop to animate a shader that declares uniform float uTime (e.g. scrolling a static noise texture's UVs, pulsing, waving). Drive it with whatever clock you like — real time, a paused/scaled/scrubbed one.

      No-op if the shader does not declare a uTime uniform (nothing to update), or in Canvas mode. The engine does NOT call this for you — animation is opt-in, exactly like re-baking a NoiseTexture2d with update(dt).

      Parameters

      • seconds: number

        elapsed time in seconds

      Returns ShaderEffect

      this effect for chaining

      // a shader that scrolls a static seamless noise texture over time
      const flow = new me.ShaderEffect(renderer, `
          uniform float uTime;
          vec4 apply(vec4 color, vec2 uv) {
              return texture2D(uSampler, uv + vec2(uTime * 0.05, 0.0));
          }`);
      mySprite.shader = flow;
      // then in your Stage's update(dt):
      flow.setTime(me.timer.getTime() / 1000);

    • Set the uniform to the given value

      Parameters

      • name: string

        the uniform name

      • value: object | Float32Array<ArrayBufferLike>

        the value to assign to that uniform

      Returns void

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods