emeraldengine 2.2.0 → 3.0.0

package/src/PostEffects.js

@@ -0,0 +1,296 @@
+import { PostEffect } from "./PostProcessor.js";
+
+/**
+ * @class BloomEffect
+ * @description Multi-pass bloom: extract bright pixels above a threshold, blur
+ * them with a separable Gaussian, then add the result back over the scene. Built
+ * via {@link PostEffects.bloom}.
+ */
+class BloomEffect extends PostEffect {
+  constructor(options = {}) {
+    super("bloom", `void main(){ gl_FragColor = texture2D(uScene, vUV); }`);
+    this.threshold = options.threshold ?? 0.7;
+    this.intensity = options.intensity ?? 1.0;
+    this.spread = options.spread ?? 1.0;
+
+    /** @private */
+    this._threshold = new PostEffect(
+      "bloom:threshold",
+      `
+      uniform float uThreshold;
+      void main() {
+        vec4 c = texture2D(uScene, vUV);
+        float l = dot(c.rgb, vec3(0.2126, 0.7152, 0.0722));
+        gl_FragColor = l > uThreshold ? c : vec4(0.0, 0.0, 0.0, 1.0);
+      }`,
+      {
+        setUniforms: (gl, loc) =>
+          gl.uniform1f(loc("uThreshold"), this.threshold),
+      }
+    );
+
+    const blur = (horizontal) => `
+      uniform float uSpread;
+      void main() {
+        vec2 texel = (${horizontal ? "vec2(1.0, 0.0)" : "vec2(0.0, 1.0)"}) / uResolution * uSpread;
+        float w[5];
+        w[0] = 0.227027; w[1] = 0.1945946; w[2] = 0.1216216; w[3] = 0.054054; w[4] = 0.016216;
+        vec3 result = texture2D(uScene, vUV).rgb * w[0];
+        for (int i = 1; i < 5; i++) {
+          result += texture2D(uScene, vUV + texel * float(i)).rgb * w[i];
+          result += texture2D(uScene, vUV - texel * float(i)).rgb * w[i];
+        }
+        gl_FragColor = vec4(result, 1.0);
+      }`;
+    const blurUniforms = {
+      setUniforms: (gl, loc) => gl.uniform1f(loc("uSpread"), this.spread),
+    };
+    /** @private */
+    this._blurH = new PostEffect("bloom:blurH", blur(true), blurUniforms);
+    /** @private */
+    this._blurV = new PostEffect("bloom:blurV", blur(false), blurUniforms);
+
+    /** @private */
+    this._composite = new PostEffect(
+      "bloom:composite",
+      `
+      uniform sampler2D uBloom;
+      uniform float uIntensity;
+      void main() {
+        vec4 scene = texture2D(uScene, vUV);
+        vec3 bloom = texture2D(uBloom, vUV).rgb;
+        gl_FragColor = vec4(scene.rgb + bloom * uIntensity, scene.a);
+      }`,
+      {
+        setUniforms: (gl, loc) => {
+          gl.uniform1f(loc("uIntensity"), this.intensity);
+          gl.activeTexture(gl.TEXTURE1);
+          gl.bindTexture(gl.TEXTURE_2D, this._bloomTex);
+          gl.uniform1i(loc("uBloom"), 1);
+          gl.activeTexture(gl.TEXTURE0);
+        },
+      }
+    );
+  }
+
+  /** @private */
+  _compile(gl) {
+    super._compile(gl);
+    this._threshold._compile(gl);
+    this._blurH._compile(gl);
+    this._blurV._compile(gl);
+    this._composite._compile(gl);
+  }
+
+  render(ctx) {
+    const temp0 = ctx.acquireTemp(0);
+    const temp1 = ctx.acquireTemp(1);
+    ctx.blit(this._threshold, ctx.input, temp0);
+    ctx.blit(this._blurH, temp0.texture, temp1);
+    ctx.blit(this._blurV, temp1.texture, temp0);
+    /** @private */
+    this._bloomTex = temp0.texture;
+    ctx.blit(this._composite, ctx.input, ctx.output);
+  }
+}
+
+/**
+ * @namespace PostEffects
+ * @description Factory functions for the built-in post-processing effects. Pass
+ * the returned PostEffect to `emerald.addPostEffect(...)`.
+ *
+ * @example
+ * emerald.enablePostProcessing();
+ * emerald.addPostEffect(PostEffects.bloom({ threshold: 0.6, intensity: 1.2 }));
+ * emerald.addPostEffect(PostEffects.vignette({ intensity: 0.5 }));
+ * emerald.addPostEffect(PostEffects.crt());
+ */
+const PostEffects = {
+  /**
+   * @method grayscale
+   * @description Desaturates the image.
+   */
+  grayscale() {
+    return new PostEffect(
+      "grayscale",
+      `void main() {
+        vec4 c = texture2D(uScene, vUV);
+        float l = dot(c.rgb, vec3(0.299, 0.587, 0.114));
+        gl_FragColor = vec4(vec3(l), c.a);
+      }`
+    );
+  },
+
+  /**
+   * @method vignette
+   * @description Darkens the edges of the screen.
+   * @param {Object} [options] - { intensity = 0.5, radius = 0.75, softness = 0.45 }
+   */
+  vignette(options = {}) {
+    const intensity = options.intensity ?? 0.5;
+    const radius = options.radius ?? 0.75;
+    const softness = options.softness ?? 0.45;
+    return new PostEffect(
+      "vignette",
+      `
+      uniform float uIntensity;
+      uniform float uRadius;
+      uniform float uSoftness;
+      void main() {
+        vec4 c = texture2D(uScene, vUV);
+        float d = distance(vUV, vec2(0.5));
+        float v = smoothstep(uRadius, uRadius - uSoftness, d);
+        c.rgb *= mix(1.0 - uIntensity, 1.0, v);
+        gl_FragColor = c;
+      }`,
+      {
+        setUniforms: (gl, loc) => {
+          gl.uniform1f(loc("uIntensity"), intensity);
+          gl.uniform1f(loc("uRadius"), radius);
+          gl.uniform1f(loc("uSoftness"), softness);
+        },
+      }
+    );
+  },
+
+  /**
+   * @method colorGrade
+   * @description Adjusts brightness, contrast and saturation.
+   * @param {Object} [options] - { brightness = 0, contrast = 1, saturation = 1 }
+   */
+  colorGrade(options = {}) {
+    const brightness = options.brightness ?? 0;
+    const contrast = options.contrast ?? 1;
+    const saturation = options.saturation ?? 1;
+    return new PostEffect(
+      "colorGrade",
+      `
+      uniform float uBrightness;
+      uniform float uContrast;
+      uniform float uSaturation;
+      void main() {
+        vec4 c = texture2D(uScene, vUV);
+        vec3 col = c.rgb + uBrightness;
+        col = (col - 0.5) * uContrast + 0.5;
+        float l = dot(col, vec3(0.299, 0.587, 0.114));
+        col = mix(vec3(l), col, uSaturation);
+        gl_FragColor = vec4(clamp(col, 0.0, 1.0), c.a);
+      }`,
+      {
+        setUniforms: (gl, loc) => {
+          gl.uniform1f(loc("uBrightness"), brightness);
+          gl.uniform1f(loc("uContrast"), contrast);
+          gl.uniform1f(loc("uSaturation"), saturation);
+        },
+      }
+    );
+  },
+
+  /**
+   * @method chromaticAberration
+   * @description Splits the RGB channels toward the screen edges.
+   * @param {Object} [options] - { amount = 0.003 }
+   */
+  chromaticAberration(options = {}) {
+    const amount = options.amount ?? 0.003;
+    return new PostEffect(
+      "chromaticAberration",
+      `
+      uniform float uAmount;
+      void main() {
+        vec2 dir = vUV - 0.5;
+        vec2 off = dir * uAmount;
+        float r = texture2D(uScene, vUV + off).r;
+        float g = texture2D(uScene, vUV).g;
+        float b = texture2D(uScene, vUV - off).b;
+        float a = texture2D(uScene, vUV).a;
+        gl_FragColor = vec4(r, g, b, a);
+      }`,
+      { setUniforms: (gl, loc) => gl.uniform1f(loc("uAmount"), amount) }
+    );
+  },
+
+  /**
+   * @method scanlines
+   * @description Overlays horizontal scanlines.
+   * @param {Object} [options] - { intensity = 0.15, count = 480 }
+   */
+  scanlines(options = {}) {
+    const intensity = options.intensity ?? 0.15;
+    const count = options.count ?? 480;
+    return new PostEffect(
+      "scanlines",
+      `
+      uniform float uIntensity;
+      uniform float uCount;
+      void main() {
+        vec4 c = texture2D(uScene, vUV);
+        float s = sin(vUV.y * uCount * 3.14159265);
+        c.rgb *= 1.0 - uIntensity * (0.5 + 0.5 * s) ;
+        gl_FragColor = c;
+      }`,
+      {
+        setUniforms: (gl, loc) => {
+          gl.uniform1f(loc("uIntensity"), intensity);
+          gl.uniform1f(loc("uCount"), count);
+        },
+      }
+    );
+  },
+
+  /**
+   * @method crt
+   * @description Retro CRT look: barrel distortion, scanlines and edge vignette.
+   * @param {Object} [options] - { curvature = 4.0, scanlineIntensity = 0.2, vignette = 0.3 }
+   */
+  crt(options = {}) {
+    const curvature = options.curvature ?? 4.0;
+    const scanlineIntensity = options.scanlineIntensity ?? 0.2;
+    const vignette = options.vignette ?? 0.3;
+    return new PostEffect(
+      "crt",
+      `
+      uniform float uCurvature;
+      uniform float uScanline;
+      uniform float uVignette;
+      vec2 curve(vec2 uv) {
+        uv = uv * 2.0 - 1.0;
+        vec2 offset = abs(uv.yx) / uCurvature;
+        uv = uv + uv * offset * offset;
+        return uv * 0.5 + 0.5;
+      }
+      void main() {
+        vec2 uv = curve(vUV);
+        if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) {
+          gl_FragColor = vec4(0.0, 0.0, 0.0, 1.0);
+          return;
+        }
+        vec4 c = texture2D(uScene, uv);
+        float scan = sin(uv.y * uResolution.y * 3.14159265);
+        c.rgb *= 1.0 - uScanline * (0.5 + 0.5 * scan);
+        float d = distance(uv, vec2(0.5));
+        c.rgb *= 1.0 - uVignette * d * d * 2.0;
+        gl_FragColor = c;
+      }`,
+      {
+        setUniforms: (gl, loc) => {
+          gl.uniform1f(loc("uCurvature"), curvature);
+          gl.uniform1f(loc("uScanline"), scanlineIntensity);
+          gl.uniform1f(loc("uVignette"), vignette);
+        },
+      }
+    );
+  },
+
+  /**
+   * @method bloom
+   * @description Glow around bright areas (multi-pass).
+   * @param {Object} [options] - { threshold = 0.7, intensity = 1.0, spread = 1.0 }
+   */
+  bloom(options = {}) {
+    return new BloomEffect(options);
+  },
+};
+
+export default PostEffects;
+export { BloomEffect };

package/src/PostProcessor.js

@@ -0,0 +1,304 @@
+import { initShaderProgram } from "./GLUtils.js";
+import GLManager from "./managers/GLManager.js";
+import RenderStats from "./managers/RenderStats.js";
+import RenderTarget from "./RenderTarget.js";
+
+const FULLSCREEN_VERTEX_SHADER = `
+  attribute vec2 aPos;
+  varying vec2 vUV;
+  void main() {
+    vUV = aPos * 0.5 + 0.5;
+    gl_Position = vec4(aPos, 0.0, 1.0);
+  }
+`;
+
+const FRAGMENT_HEADER = `
+  #ifdef GL_ES
+  precision highp float;
+  #endif
+  varying vec2 vUV;
+  uniform sampler2D uScene;
+  uniform vec2 uResolution;
+  uniform float uTime;
+`;
+
+/**
+ * @class PostEffect
+ * @description A single full-screen post-processing pass: a fragment shader that
+ * samples the previous pass (`uScene`) and writes the next image. The shader
+ * automatically has `vUV`, `uScene`, `uResolution`, and `uTime` available; add
+ * your own uniforms and set them with the `setUniforms` callback.
+ *
+ * @example
+ * const tint = new PostEffect("tint", `
+ *   uniform vec3 uTint;
+ *   void main() { gl_FragColor = texture2D(uScene, vUV) * vec4(uTint, 1.0); }
+ * `, { setUniforms: (gl, loc) => gl.uniform3f(loc("uTint"), 1.0, 0.8, 0.8) });
+ */
+class PostEffect {
+  /**
+   * @param {string} name - A label (for debugging)
+   * @param {string} fragmentSource - Fragment shader body (declares void main)
+   * @param {Object} [options] - { setUniforms(gl, loc, ctx), enabled = true }
+   */
+  constructor(name, fragmentSource, options = {}) {
+    this.name = name;
+    this.fragmentSource = fragmentSource;
+    this.setUniforms = options.setUniforms || null;
+    this.enabled = options.enabled !== false;
+    this.program = null;
+    /** @private */
+    this._locCache = new Map();
+  }
+
+  /** @private */
+  _compile(gl) {
+    if (this.program) return;
+    this.program = initShaderProgram(
+      gl,
+      FULLSCREEN_VERTEX_SHADER,
+      FRAGMENT_HEADER + this.fragmentSource
+    );
+  }
+
+  /**
+   * @method _restoreGL
+   * @description Drops the dead program/locations after a context loss so the
+   * next _compile builds fresh ones.
+   * @private
+   */
+  _restoreGL() {
+    this.program = null;
+    this._locCache.clear();
+  }
+
+  loc(gl, name) {
+    if (!this._locCache.has(name)) {
+      this._locCache.set(name, gl.getUniformLocation(this.program, name));
+    }
+    return this._locCache.get(name);
+  }
+
+  /**
+   * @method render
+   * @description Renders this effect from ctx.input into ctx.output. Override for
+   * multi-pass effects.
+   * @param {Object} ctx - Provided by the PostProcessor
+   */
+  render(ctx) {
+    ctx.blit(this, ctx.input, ctx.output);
+  }
+}
+
+/**
+ * @class PostProcessor
+ * @description Drives a chain of full-screen {@link PostEffect}s. The scene is
+ * rendered into a texture, then each effect is applied in sequence (ping-ponging
+ * between two render targets), and the final result is drawn to the screen.
+ *
+ * Created and managed by Emerald when you call `emerald.enablePostProcessing()`;
+ * you usually just add effects via `emerald.addPostEffect(PostEffects.bloom())`.
+ */
+class PostProcessor {
+  constructor() {
+    this.gl = GLManager.getGL();
+    this.effects = [];
+    this.enabled = true;
+
+    const gl = this.gl;
+    /** @private */
+    this._quad = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, this._quad);
+    gl.bufferData(
+      gl.ARRAY_BUFFER,
+      new Float32Array([-1, -1, 1, -1, -1, 1, 1, 1]),
+      gl.STATIC_DRAW
+    );
+
+    /** @private */
+    this._rtA = new RenderTarget(2, 2);
+    /** @private */
+    this._rtB = new RenderTarget(2, 2);
+    /** @private */
+    this._temps = [];
+    /** @private */
+    this._width = 2;
+    /** @private */
+    this._height = 2;
+
+    GLManager.registerRestorable(this);
+  }
+
+  /**
+   * @method _restoreGL
+   * @description Rebuilds the fullscreen quad, ping-pong render targets, and
+   * every effect's program after a WebGL context loss.
+   * @private
+   */
+  _restoreGL() {
+    const gl = this.gl;
+    if (!gl) return;
+    this._quad = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, this._quad);
+    gl.bufferData(
+      gl.ARRAY_BUFFER,
+      new Float32Array([-1, -1, 1, -1, -1, 1, 1, 1]),
+      gl.STATIC_DRAW
+    );
+    this._rtA = new RenderTarget(2, 2);
+    this._rtB = new RenderTarget(2, 2);
+    this._temps = [];
+    this._width = 2;
+    this._height = 2;
+    for (const effect of this.effects) {
+      effect._restoreGL();
+      effect._compile(gl);
+    }
+  }
+
+  /**
+   * @method addEffect
+   * @description Appends an effect to the chain.
+   * @param {PostEffect} effect
+   * @returns {PostProcessor} - this
+   */
+  addEffect(effect) {
+    effect._compile(this.gl);
+    this.effects.push(effect);
+    return this;
+  }
+
+  /**
+   * @method removeEffect
+   * @description Removes an effect from the chain.
+   */
+  removeEffect(effect) {
+    const i = this.effects.indexOf(effect);
+    if (i !== -1) this.effects.splice(i, 1);
+    return this;
+  }
+
+  /**
+   * @method clear
+   * @description Removes all effects.
+   */
+  clear() {
+    this.effects.length = 0;
+    return this;
+  }
+
+  /**
+   * @method hasEffects
+   * @returns {boolean} - Whether any enabled effects exist.
+   */
+  hasEffects() {
+    return this.enabled && this.effects.some((e) => e.enabled);
+  }
+
+  /** @private */
+  _acquireTemp(index) {
+    while (this._temps.length <= index) {
+      this._temps.push(new RenderTarget(this._width, this._height));
+    }
+    const t = this._temps[index];
+    t.resize(this._width, this._height);
+    return t;
+  }
+
+  /**
+   * @method process
+   * @description Applies the effect chain, drawing the final image to the canvas.
+   * @param {WebGLTexture} sceneTexture - The rendered scene
+   * @param {number} width - Canvas width in pixels
+   * @param {number} height - Canvas height in pixels
+   * @param {number} time - Seconds (for time-based effects)
+   */
+  process(sceneTexture, width, height, time) {
+    const gl = this.gl;
+    this._width = width;
+    this._height = height;
+    this._rtA.resize(width, height);
+    this._rtB.resize(width, height);
+
+    const active = this.effects.filter((e) => e.enabled);
+
+    gl.disable(gl.DEPTH_TEST);
+    gl.disable(gl.BLEND);
+    gl.disable(gl.SCISSOR_TEST);
+
+    const ctx = {
+      gl,
+      time,
+      width,
+      height,
+      processor: this,
+      input: sceneTexture,
+      output: null,
+      blit: (effect, input, output) => this._blit(effect, input, output, ctx),
+      acquireTemp: (i) => this._acquireTemp(i),
+    };
+
+    let input = sceneTexture;
+    for (let i = 0; i < active.length; i++) {
+      const isLast = i === active.length - 1;
+      const output = isLast ? null : i % 2 === 0 ? this._rtA : this._rtB;
+      ctx.input = input;
+      ctx.output = output;
+      active[i].render(ctx);
+      input = output ? output.texture : null;
+    }
+  }
+
+  /**
+   * @method _blit
+   * @description Renders one effect program from `input` into `output` (null =
+   * screen), setting the standard uniforms.
+   * @private
+   */
+  _blit(effect, input, output, ctx) {
+    const gl = this.gl;
+    if (output) {
+      output.bind();
+    } else {
+      gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+      gl.viewport(0, 0, this._width, this._height);
+    }
+
+    gl.useProgram(effect.program);
+
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, input);
+    RenderStats.textureBinds++;
+    gl.uniform1i(effect.loc(gl, "uScene"), 0);
+
+    const resLoc = effect.loc(gl, "uResolution");
+    if (resLoc) gl.uniform2f(resLoc, this._width, this._height);
+    const timeLoc = effect.loc(gl, "uTime");
+    if (timeLoc) gl.uniform1f(timeLoc, ctx.time);
+
+    if (effect.setUniforms) {
+      effect.setUniforms(gl, (n) => effect.loc(gl, n), ctx);
+    }
+
+    gl.bindBuffer(gl.ARRAY_BUFFER, this._quad);
+    const posLoc = gl.getAttribLocation(effect.program, "aPos");
+    gl.enableVertexAttribArray(posLoc);
+    gl.vertexAttribPointer(posLoc, 2, gl.FLOAT, false, 0, 0);
+    gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
+    RenderStats.drawCalls++;
+  }
+
+  /**
+   * @method dispose
+   * @description Frees the render targets owned by this processor.
+   */
+  dispose() {
+    this._rtA.dispose();
+    this._rtB.dispose();
+    for (const t of this._temps) t.dispose();
+    this._temps.length = 0;
+  }
+}
+
+export default PostProcessor;
+export { PostEffect };