@driftengine/core 3.61.0

package/src/render/ambientOcclusionPass.ts

@@ -0,0 +1,200 @@
+import { AO_BLUR_FRAG, AO_FRAG } from './shaders/ambientOcclusion.ts';
+import { FULLSCREEN_VERT } from './shaders/fullscreen.ts';
+import { compileProgram, uniformLocations } from './shader.ts';
+
+/**
+ * The screen-space ambient occlusion pass: estimate from depth, then blur.
+ *
+ * Its own module rather than more of `SceneTarget`, because it is its own responsibility —
+ * that class owns where the frame lands and how it reaches the canvas, and this owns one
+ * effect's targets and programs. The composite pass consumes the texture this returns and
+ * knows nothing else about it.
+ *
+ * **Two single-channel targets, ping-ponged.** The estimate lands in one, the horizontal
+ * blur writes the other, the vertical blur writes back into the first, and that one is
+ * returned. `R8` rather than `RGBA8`: occlusion is one number, and three channels of padding
+ * over a 4K frame is 24 MB of bandwidth per pass to carry nothing.
+ */
+export class AmbientOcclusionPass {
+  private width = 0;
+  private height = 0;
+  private estimate: WebGLTexture | null = null;
+  private scratch: WebGLTexture | null = null;
+  private estimateFramebuffer: WebGLFramebuffer | null = null;
+  private scratchFramebuffer: WebGLFramebuffer | null = null;
+  /**
+   * Set once if a single-channel target will not complete, after which this pass does
+   * nothing and says so once.
+   *
+   * `R8` is colour-renderable in WebGL2 by specification, so this is not expected. It is here
+   * because the alternative to an honest "off" is a frame multiplied by a texture that was
+   * never written, and the last time an effect in this renderer sampled a target nobody had
+   * filled, the failure presented as the driver being at fault. See `sceneTarget.ts`.
+   */
+  private unavailable = false;
+
+  private readonly estimateProgram: WebGLProgram;
+  private readonly estimateUniforms: Record<string, WebGLUniformLocation | null>;
+  private readonly blurProgram: WebGLProgram;
+  private readonly blurUniforms: Record<string, WebGLUniformLocation | null>;
+  private readonly vao: WebGLVertexArrayObject;
+  /** Scratch for the blur direction, so a per-frame pass allocates nothing. */
+  private readonly step = new Float32Array(2);
+  /** Scratch for the four inverse-projection terms the blur linearises depth with. */
+  private readonly depthToViewZ = new Float32Array(4);
+
+  constructor(private readonly gl: WebGL2RenderingContext) {
+    this.estimateProgram = compileProgram(gl, FULLSCREEN_VERT, AO_FRAG, 'ao');
+    this.estimateUniforms = uniformLocations(gl, this.estimateProgram, 'ao');
+    this.blurProgram = compileProgram(gl, FULLSCREEN_VERT, AO_BLUR_FRAG, 'aoBlur');
+    this.blurUniforms = uniformLocations(gl, this.blurProgram, 'aoBlur');
+
+    const vao = gl.createVertexArray();
+    if (vao === null) throw new Error('AmbientOcclusionPass: createVertexArray failed');
+    this.vao = vao;
+  }
+
+  private ensureSize(width: number, height: number): boolean {
+    if (this.unavailable) return false;
+    if (this.width === width && this.height === height && this.estimate !== null) return true;
+    const { gl } = this;
+    this.width = width;
+    this.height = height;
+
+    this.estimate = this.allocate(this.estimate, width, height);
+    this.scratch = this.allocate(this.scratch, width, height);
+
+    if (this.estimateFramebuffer === null) this.estimateFramebuffer = gl.createFramebuffer();
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.estimateFramebuffer);
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.estimate, 0);
+    const estimateReady = gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE;
+
+    if (this.scratchFramebuffer === null) this.scratchFramebuffer = gl.createFramebuffer();
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.scratchFramebuffer);
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.scratch, 0);
+    const scratchReady = gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE;
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+
+    if (!estimateReady || !scratchReady) {
+      this.unavailable = true;
+      console.warn(
+        'AmbientOcclusionPass: this driver will not render to a single-channel target, so ' +
+          'ambient occlusion is off. The frame itself is unaffected.',
+      );
+      return false;
+    }
+    return true;
+  }
+
+  private allocate(
+    existing: WebGLTexture | null,
+    width: number,
+    height: number,
+  ): WebGLTexture | null {
+    const { gl } = this;
+    const texture = existing ?? gl.createTexture();
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.R8, width, height, 0, gl.RED, gl.UNSIGNED_BYTE, null);
+    /* NEAREST, because every read of this is at a texel centre: the blur steps whole pixels
+       and the composite reads the pixel it is shading. Linear would only cost filtering. */
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    /* Clamped, so a tap past the edge repeats the edge rather than wrapping the opposite
+       side of the frame into a corner. */
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    return texture;
+  }
+
+  /**
+   * Estimate occlusion from the frame's depth and blur it. Returns the texture to multiply
+   * by, or null if this pass could not run, which the caller must read as "no occlusion"
+   * rather than as black.
+   *
+   * `invProjection` is column-major, as `gl-matrix` produces it.
+   */
+  run(
+    depth: WebGLTexture,
+    width: number,
+    height: number,
+    radius: number,
+    projScale: Float32Array,
+    invProjection: Float32Array,
+  ): WebGLTexture | null {
+    if (!this.ensureSize(width, height)) return null;
+    const { gl } = this;
+
+    /* One triangle over a target with no depth attachment. Anything inherited from the scene
+       pass would be tested against a buffer that is not there. */
+    gl.disable(gl.DEPTH_TEST);
+    gl.disable(gl.BLEND);
+    gl.disable(gl.CULL_FACE);
+    gl.depthMask(false);
+    gl.bindVertexArray(this.vao);
+    gl.viewport(0, 0, width, height);
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.estimateFramebuffer);
+    gl.useProgram(this.estimateProgram);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, depth);
+    gl.uniform1i(this.estimateUniforms['uDepth'] ?? null, 0);
+    gl.uniform2fv(this.estimateUniforms['uProjScale'] ?? null, projScale);
+    gl.uniform1f(this.estimateUniforms['uRadius'] ?? null, radius);
+    gl.uniformMatrix4fv(this.estimateUniforms['uInvProjection'] ?? null, false, invProjection);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+
+    /*
+     * The four terms that carry a depth back to metres, read out of the inverse projection.
+     * Column major, so `[2][2]` is element 10 and `[3][3]` is element 15.
+     */
+    this.depthToViewZ[0] = invProjection[10] ?? 0;
+    this.depthToViewZ[1] = invProjection[14] ?? 0;
+    this.depthToViewZ[2] = invProjection[11] ?? 0;
+    this.depthToViewZ[3] = invProjection[15] ?? 1;
+
+    gl.useProgram(this.blurProgram);
+    gl.uniform1i(this.blurUniforms['uAo'] ?? null, 0);
+    gl.uniform1i(this.blurUniforms['uDepth'] ?? null, 1);
+    gl.uniform4fv(this.blurUniforms['uDepthToViewZ'] ?? null, this.depthToViewZ);
+    gl.activeTexture(gl.TEXTURE1);
+    gl.bindTexture(gl.TEXTURE_2D, depth);
+
+    /* Across, into the scratch target. */
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.scratchFramebuffer);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, this.estimate);
+    this.step[0] = 1 / width;
+    this.step[1] = 0;
+    gl.uniform2fv(this.blurUniforms['uStep'] ?? null, this.step);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+
+    /* And down, back into the estimate, which is the texture handed out. */
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.estimateFramebuffer);
+    gl.bindTexture(gl.TEXTURE_2D, this.scratch);
+    this.step[0] = 0;
+    this.step[1] = 1 / height;
+    gl.uniform2fv(this.blurUniforms['uStep'] ?? null, this.step);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+
+    gl.bindVertexArray(null);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    return this.estimate;
+  }
+
+  dispose(): void {
+    const { gl } = this;
+    if (this.estimateFramebuffer !== null) gl.deleteFramebuffer(this.estimateFramebuffer);
+    if (this.scratchFramebuffer !== null) gl.deleteFramebuffer(this.scratchFramebuffer);
+    if (this.estimate !== null) gl.deleteTexture(this.estimate);
+    if (this.scratch !== null) gl.deleteTexture(this.scratch);
+    gl.deleteProgram(this.estimateProgram);
+    gl.deleteProgram(this.blurProgram);
+    gl.deleteVertexArray(this.vao);
+    this.estimateFramebuffer = null;
+    this.scratchFramebuffer = null;
+    this.estimate = null;
+    this.scratch = null;
+  }
+}

package/src/render/areaLights.ts

@@ -0,0 +1,194 @@
+/** Rectangular area lights: what a caller declares, and the arrays a shader wants. */
+
+/**
+ * How many rectangles the lit pass shades against at once.
+ *
+ * **Four, because a rectangle is a fixture rather than a lamp.** A window, a softbox, a lit panel:
+ * a scene with more than a handful of these is a scene that wants them baked into an environment,
+ * which is what the prefilter and the loader are for. Raising it is a uniform-array size and an
+ * iteration of the loop, exactly as `MAX_POINT_LIGHTS` is.
+ */
+export const MAX_AREA_LIGHTS = 4;
+
+/**
+ * One rectangular emitter, as a consumer describes it.
+ *
+ * Positions, colours and sizes, and nothing that means anything in one game — the rule
+ * `AGENTS.md` opens with. `right` and `up` are the rectangle's own in-plane axes, and their cross
+ * product is the direction it emits.
+ */
+export interface AreaLightSource {
+  x: number;
+  y: number;
+  z: number;
+  r: number;
+  g: number;
+  b: number;
+  /** In-plane axes. Normalised on the way in, because the form factor assumes unit length. */
+  rightX: number;
+  rightY: number;
+  rightZ: number;
+  upX: number;
+  upY: number;
+  upZ: number;
+  /** Half extents along `right` and `up`, in metres. */
+  halfWidth: number;
+  halfHeight: number;
+  /**
+   * Whether the rectangle emits from both faces. Default false.
+   *
+   * A window is one-sided and a hanging panel is two-sided, and the difference is visible rather
+   * than pedantic: a one-sided light must contribute nothing to a surface behind it, or the wall
+   * it is set into is lit by it and reads as glowing.
+   */
+  twoSided?: boolean;
+  /**
+   * Whether this rectangle is worth a shadow layer at all. **Default false**, which is the
+   * opposite of what a point light's identically named field defaults to.
+   *
+   * A point light has cast since before there was a budget to ration, so `true` is what its
+   * existing callers already rely on. An area light shipped in 3.2.0 with no occlusion at all —
+   * `AGENTS.md` calls that a bug rather than a limitation, and it is the row this field closes —
+   * so every scene that already declares one was authored against a rectangle that lights
+   * through walls. Defaulting to `true` here would hand each of them two octahedral layers,
+   * 8.39 MB, and a six-face bake over the static world, for a change in the picture nobody asked
+   * for. `RenderQuality`'s own rule is that a feature's default reproduces today's frame.
+   *
+   * **It also rides `RenderQuality.pointShadows`**, because an area light's occlusion is read out
+   * of the same array texture a point light's is. WebGL2 guarantees sixteen texture units and the
+   * lit pass binds sixteen, so a seventeenth sampler is not available to declare — see
+   * `FlatShaderOptions.environmentProbe` for the same wall reached from the other side. With that
+   * flag off there is no array to bake into, and the renderer says so once by name rather than
+   * quietly drawing an unoccluded rectangle.
+   */
+  castsShadow?: boolean;
+  /**
+   * How far from the rectangle occlusion is tracked, in metres: the shadow map's far plane.
+   *
+   * **Required when `castsShadow` is true, and deliberately not defaulted.** A point light's map
+   * gets its far plane from `radius`, the distance at which the light itself reaches zero — a
+   * rectangle has no such distance, because its falloff is the solid angle it subtends and that is
+   * never exactly zero. So the number is a statement about how much of the scene this fixture is
+   * responsible for occluding, which is a decision about the content: a panel in a corridor wants
+   * the corridor's length and a sky panel over a courtyard wants the courtyard's.
+   *
+   * Guessing it would produce one of two failures, both of which read as a renderer bug rather
+   * than a missing field: too short and the shadow stops in a straight line partway across the
+   * floor, too long and the depth precision spent on the near metres is what a fixture actually
+   * needed. A rectangle that declares it casts and names no range is refused with a warning
+   * naming the field.
+   */
+  shadowRange?: number;
+  /**
+   * Where casting begins, in metres from the rectangle's plane. Defaults to `POINT_SHADOW_NEAR`.
+   *
+   * The same knob a point light carries and for the same reason: a fixture's own housing sits
+   * within centimetres of the emitter, occludes an enormous solid angle from it, and throws that
+   * across the floor as a hard square much larger than the housing. Keep it small — it clips
+   * every caster, not just the fixture.
+   */
+  shadowNear?: number;
+}
+
+/** The five arrays the shader declares, filled once a frame from whatever a caller supplied. */
+export interface AreaLightBuffer {
+  count: number;
+  readonly positions: Float32Array;
+  readonly colors: Float32Array;
+  readonly right: Float32Array;
+  readonly up: Float32Array;
+  readonly sizes: Float32Array;
+  readonly twoSided: Float32Array;
+}
+
+export function createAreaLightBuffer(capacity: number = MAX_AREA_LIGHTS): AreaLightBuffer {
+  return {
+    count: 0,
+    positions: new Float32Array(capacity * 3),
+    colors: new Float32Array(capacity * 3),
+    right: new Float32Array(capacity * 3),
+    up: new Float32Array(capacity * 3),
+    sizes: new Float32Array(capacity * 2),
+    twoSided: new Float32Array(capacity),
+  };
+}
+
+/**
+ * Fill the buffer from a caller's list, normalising the axes and orthogonalising them.
+ *
+ * **Both corrections are here rather than trusted**, and neither is defensive tidying:
+ *
+ * - The form factor treats `right` and `up` as unit vectors, so a caller's un-normalised axis
+ *   scales the rectangle it describes. That is a light of the wrong *size*, which reads as the
+ *   half extents having been set wrong.
+ * - The two axes are made perpendicular, because a rectangle whose axes are not describes a
+ *   parallelogram — and the form factor is defined for the polygon its four corners make, so what
+ *   comes out is the irradiance of a shape the caller did not ask for and cannot see the outline
+ *   of.
+ *
+ * Allocation-free: it fills a target the caller owns, because this runs per frame.
+ */
+export function selectAreaLights(
+  lights: readonly AreaLightSource[],
+  out: AreaLightBuffer,
+): AreaLightBuffer {
+  const capacity = Math.floor(out.sizes.length / 2);
+  const count = Math.min(lights.length, capacity);
+  out.count = count;
+
+  for (let slot = 0; slot < count; slot++) {
+    const light = lights[slot];
+    if (light === undefined) continue;
+
+    out.positions[slot * 3] = light.x;
+    out.positions[slot * 3 + 1] = light.y;
+    out.positions[slot * 3 + 2] = light.z;
+    out.colors[slot * 3] = light.r;
+    out.colors[slot * 3 + 1] = light.g;
+    out.colors[slot * 3 + 2] = light.b;
+
+    const rx = light.rightX;
+    const ry = light.rightY;
+    const rz = light.rightZ;
+    const rLen = Math.sqrt(rx * rx + ry * ry + rz * rz) || 1;
+    const nrx = rx / rLen;
+    const nry = ry / rLen;
+    const nrz = rz / rLen;
+
+    /* Gram-Schmidt: up loses whatever component it shared with right, then is normalised. */
+    const ux = light.upX;
+    const uy = light.upY;
+    const uz = light.upZ;
+    const along = ux * nrx + uy * nry + uz * nrz;
+    let oux = ux - nrx * along;
+    let ouy = uy - nry * along;
+    let ouz = uz - nrz * along;
+    const uLen = Math.sqrt(oux * oux + ouy * ouy + ouz * ouz);
+    if (uLen < 1e-6) {
+      /*
+       * Parallel axes describe no rectangle at all. Any perpendicular will do rather than leaving
+       * a zero vector, which would make every corner the same point and every form factor NaN —
+       * a light that blanks whatever it touches, from two numbers a caller got wrong.
+       */
+      const fallback = Math.abs(nry) < 0.9 ? [0, 1, 0] : [1, 0, 0];
+      oux = (fallback[1] ?? 0) * nrz - (fallback[2] ?? 0) * nry;
+      ouy = (fallback[2] ?? 0) * nrx - (fallback[0] ?? 0) * nrz;
+      ouz = (fallback[0] ?? 0) * nry - (fallback[1] ?? 0) * nrx;
+    }
+    const finalLen = Math.sqrt(oux * oux + ouy * ouy + ouz * ouz) || 1;
+
+    out.right[slot * 3] = nrx;
+    out.right[slot * 3 + 1] = nry;
+    out.right[slot * 3 + 2] = nrz;
+    out.up[slot * 3] = oux / finalLen;
+    out.up[slot * 3 + 1] = ouy / finalLen;
+    out.up[slot * 3 + 2] = ouz / finalLen;
+
+    /* Never zero: a rectangle with no extent has no solid angle and no light. */
+    out.sizes[slot * 2] = Math.max(1e-4, light.halfWidth);
+    out.sizes[slot * 2 + 1] = Math.max(1e-4, light.halfHeight);
+    out.twoSided[slot] = light.twoSided === true ? 1 : 0;
+  }
+
+  return out;
+}