@driftengine/core 3.61.0

package/src/render/globalMedium.ts

@@ -0,0 +1,154 @@
+/**
+ * A medium filling the whole frustum: what a caller may say about it, and what that resolves to.
+ *
+ * **Here rather than in either renderer, for the reason `lightVolumeDraw.ts` states at its own
+ * top**: two copies of a clamp is a fog that thins on one backend and not the other, and nothing
+ * raises, because either frame is a plausible one. Everything in this file is arithmetic both
+ * backends run before they bind anything.
+ *
+ * The pass this feeds is described in `shaders/globalMedium.ts`. The short version of why it is
+ * not `atmosphere.ts`: distance fog asks how much of a *surface* survives the journey to the eye,
+ * and this asks what the journey adds — which is every point along it the sun can see, and is the
+ * only one of the two that can put the shape of a doorway on a floor.
+ */
+
+/**
+ * The most steps a march may take, which is the shader's own loop bound.
+ *
+ * **Here rather than beside the GLSL, and the reason is bundle size rather than tidiness.**
+ * `renderQuality.ts` clamps against this and is imported by everything; importing one integer out
+ * of the shader module would carry seventeen kilobytes of shader text into every consumer's
+ * bundle, tree-shaken or not. The engine has paid that once already — see
+ * `docs/IMPROVEMENTS.md` on a constant imported from an offline module.
+ *
+ * Sixty-four is well past useful: at that count the step is centimetres across a room, and the
+ * picture stopped changing somewhere around a third of it.
+ */
+export const MAX_GLOBAL_MEDIUM_STEPS = 64;
+
+/**
+ * The most steps a part `isWeakGpuFamily` names gets, whatever the profile asked for.
+ *
+ * **The march is the only ceiling in `RenderQuality` that is a per-pixel loop**, so it is the one
+ * a weak part gains most from having lowered and the one a settings screen would otherwise have to
+ * know about by name. Sixteen still resolves a shaft across a room; what it gives up is the
+ * smoothness of a long march through a low sun, which is where the banding a step count buys off
+ * actually lives.
+ *
+ * A floor and not a verdict, like the two clamps beside it: `capabilityClamp: false` means "this
+ * person chose these numbers themselves", and a player who asks a weak part for a thick fog is
+ * entitled to it and to the frame rate that comes with it.
+ */
+export const WEAK_GPU_MEDIUM_STEPS = 16;
+
+/**
+ * How thick the air is, this frame.
+ *
+ * A per-frame dial and not a quality setting, in the split `renderQuality.ts` draws for depth of
+ * field: what a device can afford is `globalMediumSteps`, and what the weather is doing is this.
+ * A game walks into a fog bank; a profile decides how expensive being in one is allowed to be.
+ */
+export interface GlobalMediumOptions {
+  /**
+   * Extinction per metre. **0 is off, and off is free** — no target is allocated, no pass is
+   * built and the composite is skipped, so a game that never sets this pays nothing at all.
+   *
+   * As a scale: 0.02 leaves a wall at 50 m about a third obscured, 0.1 is thick weather, and
+   * above about 0.5 nothing is visible past a room.
+   */
+  readonly density: number;
+  /**
+   * How much of what the medium takes out of a ray comes back as light rather than as heat, 0 to 1.
+   *
+   * Near 1 for water droplets, which is fog, cloud and steam; lower for smoke, which is soot and
+   * absorbs most of what it intercepts. It is the difference between a white fog that a torch
+   * lights up and a black smoke that swallows the same torch.
+   */
+  readonly albedo: number;
+  /**
+   * Henyey-Greenstein anisotropy, -1 back to 1 forward. 0 is isotropic.
+   *
+   * **This is the term that makes a medium read as weather rather than as a grey wash.** Real haze
+   * is strongly forward-scattering, which is why the air around a low sun glows and the same air
+   * behind the viewer does not. Around 0.6 for atmospheric haze; 0 for a medium with nothing
+   * directional about it at all.
+   */
+  readonly anisotropy: number;
+  /**
+   * Where the march stops, in metres. Beyond it the medium is not sampled and nothing is added.
+   *
+   * A bound on the *integral*, not on the fog: extinction is still integrated over the whole
+   * distance a ray travels, so a far wall behind this bound is still obscured. What stops is the
+   * search for light to scatter, which is what costs — and past a few extinction lengths there is
+   * no transmittance left for a sample to contribute through.
+   */
+  readonly maxDistance: number;
+}
+
+/**
+ * What a renderer starts with: off, and everything else at a value that means "ordinary air".
+ *
+ * The three settings beside `density` are never consulted while it is zero, so they are chosen to
+ * make `setGlobalMedium(0.02)`-shaped calls — one number, the rest defaulted — land somewhere
+ * recognisable rather than on a black isotropic soup.
+ */
+export const DEFAULT_GLOBAL_MEDIUM: GlobalMediumOptions = {
+  density: 0,
+  albedo: 0.9,
+  anisotropy: 0.6,
+  maxDistance: 200,
+};
+
+/**
+ * A caller's numbers, clamped to what the shader can be handed.
+ *
+ * **Every bound here is a picture rather than a guard.** A negative density is `exp(+x)` and a
+ * frame that grows brighter with distance; an anisotropy of exactly 1 or -1 divides the phase
+ * function by zero, which is a NaN that a half-float target spreads over the whole screen rather
+ * than reporting; a `maxDistance` of zero is a march with no length that still costs its steps.
+ */
+export function resolveGlobalMedium(options: Partial<GlobalMediumOptions>): GlobalMediumOptions {
+  const d = DEFAULT_GLOBAL_MEDIUM;
+  return {
+    density: Math.max(0, options.density ?? d.density),
+    albedo: Math.min(1, Math.max(0, options.albedo ?? d.albedo)),
+    /* Short of the poles, where `(1 - g^2)` over `(1 + g^2 - 2g)^1.5` is 0/0. */
+    anisotropy: Math.min(0.95, Math.max(-0.95, options.anisotropy ?? d.anisotropy)),
+    maxDistance: Math.max(1e-3, options.maxDistance ?? d.maxDistance),
+  };
+}
+
+/**
+ * Whether this frame draws the medium at all.
+ *
+ * Both halves, in one place, because both backends have to agree about it exactly: the claim that
+ * `density: 0` is pixel-identical to the pass being absent is only true if neither backend runs a
+ * composite at zero, and a second copy of this test is where that stops being true.
+ */
+export function mediumActive(options: GlobalMediumOptions, steps: number): boolean {
+  return options.density > 0 && steps > 0;
+}
+
+/**
+ * The march's target size.
+ *
+ * **Half each way is a quarter of the march, which is the whole reason a global medium is
+ * affordable.** A step is a shadow lookup and an exponential, tens of times a pixel, where an
+ * occlusion tap is one depth fetch — which is why `ambientOcclusionPass.ts` can run at the frame's
+ * own size and this cannot. What half resolution costs is bought back by the upsample, which is
+ * depth-aware precisely because the one place a half-res medium is visible is a silhouette.
+ *
+ * Rounded up, never below one: a frame one pixel tall halved is zero, and a zero-height target is
+ * refused by both backends at creation.
+ */
+export function mediumTargetSize(
+  width: number,
+  height: number,
+  halfResolution: boolean,
+): { width: number; height: number } {
+  const divisor = halfResolution ? 2 : 1;
+  return {
+    width: Math.max(1, Math.ceil(Math.max(1, width) / divisor)),
+    height: Math.max(1, Math.ceil(Math.max(1, height) / divisor)),
+  };
+}

package/src/render/globalMediumPass.ts

@@ -0,0 +1,323 @@
+import { mat4 } from 'gl-matrix';
+import type { ReadonlyMat4 } from 'gl-matrix';
+
+import { mediumTargetSize } from './globalMedium.ts';
+import type { GlobalMediumOptions } from './globalMedium.ts';
+import { DEPTH_01_TO_CLIP } from './lightVolumeDraw.ts';
+import { compileProgram, uniformLocations } from './shader.ts';
+import { FULLSCREEN_VERT } from './shaders/fullscreen.ts';
+import { MEDIUM_FRAG, MEDIUM_UPSAMPLE_FRAG } from './shaders/globalMedium.ts';
+
+/** What the march needs about the light, which is the sun and the sky and nothing else. */
+export interface MediumLight {
+  /** Surface → sun, normalised. `Environment.directionalDir` unchanged. */
+  readonly sunDir: ArrayLike<number>;
+  readonly sunColor: ArrayLike<number>;
+  /** The sky's fill, scattered isotropically, so a shadowed medium is grey rather than black. */
+  readonly ambient: ArrayLike<number>;
+  /** How much of the medium the sun's shadow map removes, 0 to 1. At 0 no map is sampled. */
+  readonly sunShadow: number;
+  /** World → light clip, **uncorrected**: the shader does its own `* 0.5 + 0.5`. */
+  readonly lightViewProj: ReadonlyMat4;
+  readonly staticShadowMap: WebGLTexture;
+  readonly peeledShadowMap: WebGLTexture;
+  readonly dynamicShadowMap: WebGLTexture;
+  readonly peeledEnabled: boolean;
+}
+
+/**
+ * The global participating medium on WebGL2: a half-res march, then a depth-aware composite.
+ *
+ * **Its own module rather than more of `SceneTarget`**, on the split `ambientOcclusionPass.ts`
+ * draws: that class owns where the frame lands and how it reaches the canvas, and this owns one
+ * effect's target and programs. It is patterned on `SsrPass` more closely than on the occlusion
+ * pass, because it has the same shape — a march into a target of its own, then one composite done
+ * by the blend state, so neither pass ever samples the colour it is modifying.
+ *
+ * **One target and no ping-pong.** The march writes scattered light in `rgb` and transmittance in
+ * `a`; `(ONE, SRC_ALPHA)` against that is `dst * T + L`, which is the transfer equation for the
+ * segment written out. There is nothing to blur — a homogeneous medium is smooth by construction,
+ * and the only sharp thing in the integral is the shadow map, which the march dithers.
+ */
+export class GlobalMediumPass {
+  private readonly march: WebGLProgram;
+  private readonly marchUniforms: Record<string, WebGLUniformLocation | null>;
+  private readonly upsample: WebGLProgram;
+  private readonly upsampleUniforms: Record<string, WebGLUniformLocation | null>;
+  private readonly vao: WebGLVertexArrayObject;
+
+  private target: WebGLTexture | null = null;
+  private framebuffer: WebGLFramebuffer | null = null;
+  private width = 0;
+  private height = 0;
+  /** The frame size the current target was derived from, so a resize is noticed. */
+  private frameWidth = 0;
+  private frameHeight = 0;
+  private half = true;
+
+  /**
+   * Set once if the target will not complete, after which this pass does nothing and says so once.
+   *
+   * The same honest "off" `ambientOcclusionPass.ts` takes, and its note is the argument: *"the
+   * alternative to an honest off is a frame multiplied by a target 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."* Here the multiplication is literal — a composite reading an
+   * unwritten alpha would multiply the whole frame by whatever was in that memory.
+   */
+  private unavailable = false;
+
+  /** `inverse(viewProjection) * DEPTH_01_TO_CLIP`, rebuilt once a frame. See `SsrPass`. */
+  private readonly depthToWorld = new Float32Array(16);
+  /** The four terms the upsample linearises a depth with, so a per-frame pass allocates nothing. */
+  private readonly depthToViewZ = new Float32Array(4);
+  private readonly mediumTexel = new Float32Array(2);
+  private readonly invProjection = new Float32Array(16);
+
+  constructor(
+    private readonly gl: WebGL2RenderingContext,
+    /**
+     * Whether a half-float target is available, which is `EXT_color_buffer_float`.
+     *
+     * `RGBA8` is a real fallback rather than a refusal: transmittance lives in 0 to 1 by
+     * definition, and the inscatter only leaves that range against an HDR scene — where the
+     * fallback clips a bright fog to white instead of losing it. `SceneTarget.keepsRange` makes
+     * the same trade for the frame itself.
+     */
+    private readonly floatColor: boolean,
+  ) {
+    this.march = compileProgram(gl, FULLSCREEN_VERT, MEDIUM_FRAG, 'medium');
+    this.marchUniforms = uniformLocations(gl, this.march, 'medium');
+    this.upsample = compileProgram(gl, FULLSCREEN_VERT, MEDIUM_UPSAMPLE_FRAG, 'mediumUpsample');
+    this.upsampleUniforms = uniformLocations(gl, this.upsample, 'mediumUpsample');
+    const vao = gl.createVertexArray();
+    if (vao === null) throw new Error('GlobalMediumPass: createVertexArray failed');
+    this.vao = vao;
+  }
+
+  private ensureSize(frameWidth: number, frameHeight: number, half: boolean): boolean {
+    if (this.unavailable) return false;
+    if (
+      this.frameWidth === frameWidth &&
+      this.frameHeight === frameHeight &&
+      this.half === half &&
+      this.target !== null
+    ) {
+      return true;
+    }
+    const { gl } = this;
+    const size = mediumTargetSize(frameWidth, frameHeight, half);
+    this.frameWidth = frameWidth;
+    this.frameHeight = frameHeight;
+    this.half = half;
+    this.width = size.width;
+    this.height = size.height;
+
+    /* Unit 0, chosen rather than inherited, for the reason `SsrPass.ensureSize` gives. */
+    gl.activeTexture(gl.TEXTURE0);
+    if (this.target === null) this.target = gl.createTexture();
+    gl.bindTexture(gl.TEXTURE_2D, this.target);
+    gl.texImage2D(
+      gl.TEXTURE_2D,
+      0,
+      this.floatColor ? gl.RGBA16F : gl.RGBA8,
+      size.width,
+      size.height,
+      0,
+      gl.RGBA,
+      this.floatColor ? gl.HALF_FLOAT : gl.UNSIGNED_BYTE,
+      null,
+    );
+    /*
+     * NEAREST, and it is the upsample's design rather than a saving. That pass computes the four
+     * bilinear weights itself so that it can *refuse* one of them across a depth edge, and it
+     * fetches each texel at its own centre — where a linear filter returns the texel exactly.
+     * Asking the hardware to blend as well would blend the taps this pass exists to separate.
+     */
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    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);
+
+    if (this.framebuffer === null) this.framebuffer = gl.createFramebuffer();
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.target, 0);
+    const ready = gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE;
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+
+    if (!ready) {
+      this.unavailable = true;
+      console.warn(
+        "GlobalMediumPass: this driver will not render to the medium's target, so the global " +
+          'medium is off. The frame itself is unaffected.',
+      );
+      return false;
+    }
+    return true;
+  }
+
+  /**
+   * March the medium into this pass's own target. Returns false if it could not run, which the
+   * caller must read as "no medium" rather than composite something nobody wrote.
+   *
+   * `viewProjection` and `projection` are the **raw** camera matrices, as `SsrPass` takes them:
+   * `DEPTH_01_TO_CLIP` carries a stored depth back into the clip space the first was built in,
+   * and pairing either with a clip-corrected matrix applies the remap twice.
+   */
+  marchMedium(
+    depth: WebGLTexture,
+    frameWidth: number,
+    frameHeight: number,
+    half: boolean,
+    steps: number,
+    options: GlobalMediumOptions,
+    viewProjection: ReadonlyMat4,
+    projection: ReadonlyMat4,
+    eye: ArrayLike<number>,
+    light: MediumLight,
+  ): boolean {
+    if (!this.ensureSize(frameWidth, frameHeight, half)) return false;
+    const { gl } = this;
+    const u = this.marchUniforms;
+
+    mat4.invert(this.depthToWorld, viewProjection);
+    mat4.multiply(this.depthToWorld, this.depthToWorld, DEPTH_01_TO_CLIP);
+    /*
+     * The upsample's four terms, taken here because this is the frame the march ran against.
+     * Column major, so `[2][2]` is element 10 and `[3][3]` is element 15 — the same four
+     * `ambientOcclusionPass.ts` reads, in the same order.
+     */
+    mat4.invert(this.invProjection, projection);
+    this.depthToViewZ[0] = this.invProjection[10] ?? 0;
+    this.depthToViewZ[1] = this.invProjection[14] ?? 0;
+    this.depthToViewZ[2] = this.invProjection[11] ?? 0;
+    this.depthToViewZ[3] = this.invProjection[15] ?? 1;
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    gl.viewport(0, 0, this.width, this.height);
+    /* One triangle over a target with no depth attachment, so nothing inherited from the scene
+       pass is tested against a buffer that is not there. */
+    gl.disable(gl.DEPTH_TEST);
+    gl.depthMask(false);
+    gl.disable(gl.CULL_FACE);
+    gl.disable(gl.BLEND);
+    gl.disable(gl.SCISSOR_TEST);
+
+    gl.useProgram(this.march);
+    gl.bindVertexArray(this.vao);
+
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, depth);
+    gl.uniform1i(u['uDepth'] ?? null, 0);
+    gl.activeTexture(gl.TEXTURE1);
+    gl.bindTexture(gl.TEXTURE_2D, light.staticShadowMap);
+    gl.uniform1i(u['uStaticShadowMap'] ?? null, 1);
+    gl.activeTexture(gl.TEXTURE2);
+    gl.bindTexture(gl.TEXTURE_2D, light.peeledShadowMap);
+    gl.uniform1i(u['uPeeledShadowMap'] ?? null, 2);
+    gl.activeTexture(gl.TEXTURE3);
+    gl.bindTexture(gl.TEXTURE_2D, light.dynamicShadowMap);
+    gl.uniform1i(u['uDynamicShadowMap'] ?? null, 3);
+
+    gl.uniformMatrix4fv(u['uDepthToWorld'] ?? null, false, this.depthToWorld);
+    gl.uniform3f(u['uCameraPos'] ?? null, eye[0] ?? 0, eye[1] ?? 0, eye[2] ?? 0);
+    gl.uniform3f(
+      u['uSunDir'] ?? null,
+      light.sunDir[0] ?? 0,
+      light.sunDir[1] ?? 1,
+      light.sunDir[2] ?? 0,
+    );
+    gl.uniform3f(
+      u['uSunColor'] ?? null,
+      light.sunColor[0] ?? 0,
+      light.sunColor[1] ?? 0,
+      light.sunColor[2] ?? 0,
+    );
+    gl.uniform3f(
+      u['uAmbient'] ?? null,
+      light.ambient[0] ?? 0,
+      light.ambient[1] ?? 0,
+      light.ambient[2] ?? 0,
+    );
+    gl.uniform1f(u['uDensity'] ?? null, options.density);
+    gl.uniform1f(u['uAlbedo'] ?? null, options.albedo);
+    gl.uniform1f(u['uAnisotropy'] ?? null, options.anisotropy);
+    gl.uniform1f(u['uMaxDistance'] ?? null, options.maxDistance);
+    gl.uniform1i(u['uSteps'] ?? null, steps);
+    gl.uniform1f(u['uSunShadow'] ?? null, light.sunShadow);
+    gl.uniformMatrix4fv(u['uLightViewProj'] ?? null, false, light.lightViewProj as Float32Array);
+    gl.uniform1i(u['uPeeledShadowEnabled'] ?? null, light.peeledEnabled ? 1 : 0);
+
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+
+    gl.bindVertexArray(null);
+    /* Released down to unit 0, for the reason `SsrPass` records: a binding outlives the frame that
+       made it, and the next frame attaches one of these as a target while a sampler still names it. */
+    for (const unit of [gl.TEXTURE3, gl.TEXTURE2, gl.TEXTURE1, gl.TEXTURE0]) {
+      gl.activeTexture(unit);
+      gl.bindTexture(gl.TEXTURE_2D, null);
+    }
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    return true;
+  }
+
+  /**
+   * Composite the march over whatever framebuffer is bound, upsampled depth-aware.
+   *
+   * `(ONE, SRC_ALPHA)` on colour is `dst * transmittance + inscatter`; alpha is left alone with
+   * `(ZERO, ONE)`, because the frame's own alpha is not the medium's to spend.
+   */
+  compositeMedium(depth: WebGLTexture, frameWidth: number, frameHeight: number): void {
+    if (this.target === null || this.unavailable) return;
+    const { gl } = this;
+    const u = this.upsampleUniforms;
+
+    gl.viewport(0, 0, frameWidth, frameHeight);
+    gl.disable(gl.DEPTH_TEST);
+    gl.depthMask(false);
+    gl.disable(gl.CULL_FACE);
+    gl.enable(gl.BLEND);
+    gl.blendFuncSeparate(gl.ONE, gl.SRC_ALPHA, gl.ZERO, gl.ONE);
+
+    gl.useProgram(this.upsample);
+    gl.bindVertexArray(this.vao);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, this.target);
+    gl.uniform1i(u['uMedium'] ?? null, 0);
+    gl.activeTexture(gl.TEXTURE1);
+    gl.bindTexture(gl.TEXTURE_2D, depth);
+    gl.uniform1i(u['uDepth'] ?? null, 1);
+    this.mediumTexel[0] = 1 / Math.max(1, this.width);
+    this.mediumTexel[1] = 1 / Math.max(1, this.height);
+    gl.uniform2fv(u['uMediumTexel'] ?? null, this.mediumTexel);
+    gl.uniform4fv(u['uDepthToViewZ'] ?? null, this.depthToViewZ);
+
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+
+    gl.bindVertexArray(null);
+    gl.activeTexture(gl.TEXTURE1);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    /* Back to the blend every other pass in this renderer assumes it inherits. */
+    gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+    gl.disable(gl.BLEND);
+    gl.depthMask(true);
+    gl.enable(gl.DEPTH_TEST);
+  }
+
+  dispose(): void {
+    const { gl } = this;
+    if (this.framebuffer !== null) gl.deleteFramebuffer(this.framebuffer);
+    if (this.target !== null) gl.deleteTexture(this.target);
+    gl.deleteProgram(this.march);
+    gl.deleteProgram(this.upsample);
+    gl.deleteVertexArray(this.vao);
+    this.framebuffer = null;
+    this.target = null;
+    this.width = 0;
+    this.height = 0;
+    this.frameWidth = 0;
+    this.frameHeight = 0;
+  }
+}