@expofp/renderer 0.0.0-experimental.2d6c681

package/dist/objects/materials/effects/ao/ambient-occlusion-pass.d.ts

@@ -0,0 +1,77 @@
+import { type IUniform, Matrix4, type Texture, Vector2, Vector3 } from 'three';
+/** The AO pass's uniforms, as {@link createAoPassUniforms} builds them. */
+export type AoPassUniforms = ReturnType<typeof createAoPassUniforms>;
+/**
+ * Builds one AO pass's uniforms: its own kernel, its own rotation tile, and the matrices and sizes
+ * `OcclusionPasses` refreshes every frame.
+ *
+ * Per mount rather than per module: a `DataTexture` uploads into whichever GL context first draws
+ * with it, and disposal from one mounted scene takes it away from the other. The caller owns the
+ * rotation tile's disposal.
+ *
+ * The frame writes into the matrices and vectors rather than replacing them, so a frame costs no
+ * allocation and no shader recompile.
+ * @returns The uniform record, ready to hand to a `ShaderMaterial`.
+ */
+export declare function createAoPassUniforms(): {
+    /** The prepass's depth. The shader unprojects it per tap. `null` until the first pass runs. */
+    uDepth: IUniform<Texture | null>;
+    /** The rotation tile, which repeats over the target. See {@link createNoiseTexture}. */
+    uNoise: IUniform<Texture>;
+    /** The guard band's projection, which places a view-space tap back on the depth texture. */
+    uProjection: IUniform<Matrix4>;
+    /** Its inverse, which turns a stored depth back into a view position. */
+    uUnprojection: IUniform<Matrix4>;
+    /** One texel of the target in uv, the step the normal reconstruction walks. */
+    uTexel: IUniform<Vector2>;
+    /** The target's size in rotation tiles, so the tile repeats every {@link NOISE_TILE} texels. */
+    uNoiseScale: IUniform<Vector2>;
+    /** How far the kernel reaches, in view units. */
+    uRadius: IUniform<number>;
+    /**
+     * How many of the kernel's offsets to walk, from `1` to {@link AO_TAPS}. `OcclusionPasses`
+     * rewrites it each frame from `AmbientOcclusion.taps`, the way it rewrites the radius.
+     */
+    uTaps: IUniform<number>;
+    /** The hemisphere kernel around `+z`, which the shader rotates per fragment. */
+    uKernel: IUniform<Vector3[]>;
+};
+/** How many taps the kernel holds, which is the AO pass loop's bound and its default count. */
+export declare const AO_TAPS = 16;
+/**
+ * The rotation tile's edge in texels, which is the blur pass's kernel bound and its default side.
+ *
+ * One decision with the blur kernel rather than two: a `4 × 4` tile needs a `4 × 4` kernel to
+ * average out. The GUI reaches a smaller kernel, which trades structured noise for the fetches it
+ * skips.
+ */
+export declare const NOISE_TILE = 4;
+/**
+ * Both full-screen passes' vertex stage: a clip-space quad, the way `Background` draws one.
+ *
+ * `position.xy` of a `2 × 2` plane already spans clip space, so the stage reads no matrix and the
+ * camera means nothing. `z` sits at `0` rather than the far plane, because the passes draw with no
+ * depth test.
+ */
+export declare const AO_VERTEX_SHADER = "\n  varying vec2 vUv;\n\n  void main() {\n    vUv = uv;\n    gl_Position = vec4(position.xy, 0.0, 1.0);\n  }\n";
+/**
+ * The AO pass's fragment stage: a hemisphere-kernel occlusion pass, with the one substitution a
+ * floor plan renderer forces.
+ *
+ * There is no G-buffer. The pass unprojects the fragment's own view position from the prepass
+ * depth, and `normalAt` reconstructs the normal from that same depth.
+ *
+ * Every position and length below sits in view space, which is where three's own lighting works and
+ * where this pass's inverse projection lands. View space looks down `-z`, so a larger `z` is nearer
+ * the camera, and `occlusionTap` compares depths that way.
+ *
+ * The pass writes occlusion, not visibility: `0` is open, `1` is closed, raw and unblurred. A pass
+ * of its own smooths it, see `BLUR_FRAGMENT_SHADER`.
+ *
+ * `AO_BIAS` is the slack that keeps a tap on the fragment's own flat face from reading as an
+ * occluder. It is a share of the radius, so it holds at any zoom. A tap keeps its full value until
+ * the surface it found is a radius away in depth, then falls to nothing. That keeps a wall from
+ * darkening whatever stands far behind it.
+ */
+export declare const AO_FRAGMENT_SHADER = "\n  uniform sampler2D uDepth;\n  uniform sampler2D uNoise;\n  uniform mat4 uProjection;\n  uniform mat4 uUnprojection;\n  uniform vec2 uTexel;\n  uniform vec2 uNoiseScale;\n  uniform float uRadius;\n  uniform int uTaps;\n  uniform vec3 uKernel[16];\n  varying vec2 vUv;\n\n  const float AO_BIAS = 0.02;\n\n  // Where the grazing fade starts and ends, as the absolute dot of the normal against the view\n  // direction: fully faded about seventeen degrees from edge on, fully open by about forty. See the\n  // fade at the end of main.\n  const float AO_GRAZING_MIN = 0.30;\n  const float AO_GRAZING_MAX = 0.64;\n\n  // How far apart the two neighbors of an axis have to be before blendAxis takes the nearer one\n  // outright. Measured as a share of their sum. Larger crosses over more gently and softens a\n  // silhouette. Smaller sharpens the silhouette and brings the normal jump back.\n  const float AO_CROSSOVER = 0.45;\n\n  float depthAt(vec2 uv) {\n    return texture2D(uDepth, uv).x;\n  }\n\n  vec3 viewAt(vec2 uv, float depth) {\n    vec4 clip = vec4(uv * 2. - 1., depth * 2. - 1., 1.);\n    vec4 view = uUnprojection * clip;\n    return view.xyz / view.w;\n  }\n\n  vec3 blendAxis(vec3 back, vec3 forward, float backApart, float forwardApart) {\n    // Positive when the backward neighbor is the worse of the two, which moves the result toward\n    // the forward one. Normalized by the sum, so AO_CROSSOVER is a share rather than a depth.\n    float ratio = (backApart - forwardApart) / max(backApart + forwardApart, 1e-6);\n    return mix(back, forward, smoothstep(-AO_CROSSOVER, AO_CROSSOVER, ratio));\n  }\n\n  vec3 normalAt(vec2 uv, vec3 here, float depth) {\n    vec2 stepX = vec2(uTexel.x, 0.);\n    vec2 stepY = vec2(0., uTexel.y);\n    float left = depthAt(uv - stepX);\n    float right = depthAt(uv + stepX);\n    float down = depthAt(uv - stepY);\n    float up = depthAt(uv + stepY);\n\n    // blendAxis leans toward the neighbor that stays on this surface rather than switching to it. A\n    // hard pick makes a face turned side on jump: both depth differences are large and nearly equal\n    // there, so a small camera rotation crosses the comparison and the normal jumps with it. The\n    // smoothstep over their difference crosses that middle continuously.\n    vec3 alongX = blendAxis(here - viewAt(uv - stepX, left), viewAt(uv + stepX, right) - here,\n                            abs(depth - left), abs(right - depth));\n    vec3 alongY = blendAxis(here - viewAt(uv - stepY, down), viewAt(uv + stepY, up) - here,\n                            abs(depth - down), abs(up - depth));\n\n    vec3 normal = normalize(cross(alongX, alongY));\n    // A surface the camera sees faces the camera, and view space looks down -z. The flip matters in\n    // external mode, where the host's projection can mirror an axis and turn the cross product with\n    // it. The wrong side samples the hemisphere behind the surface.\n    return normal.z < 0. ? -normal : normal;\n  }\n\n  float occlusionTap(vec3 here, vec3 at) {\n    vec4 clip = uProjection * vec4(at, 1.);\n    // At or behind the eye, where the perspective divide has no answer. Orthographic keeps w at 1,\n    // so this costs a comparison there and nothing else.\n    if (clip.w <= 0.) return 0.;\n    vec2 uv = clip.xy / clip.w * .5 + .5;\n    // Screen space sees only what is on screen. A tap off the edge has no depth of its own, and\n    // clamped sampling answers with the border texel's depth, so the tap contributes nothing.\n    if (uv.x < 0. || uv.x > 1. || uv.y < 0. || uv.y > 1.) return 0.;\n    float stored = depthAt(uv);\n    // The prepass clears to the far plane, so a tap over open background lands there. This rejects\n    // that tap rather than darkening an edge.\n    if (stored >= 1.) return 0.;\n    float storedZ = viewAt(uv, stored).z;\n    // Nothing in front of the tap: this surface is open in that direction.\n    if (storedZ < at.z + uRadius * AO_BIAS) return 0.;\n    return smoothstep(0., 1., uRadius / abs(here.z - storedZ));\n  }\n\n  void main() {\n    float depth = depthAt(vUv);\n    // Nothing here, or nothing to reach with. The prepass clears to the far plane. A radius of zero\n    // puts every tap on the fragment itself, where the divide by its distance has no answer.\n    if (depth >= 1. || uRadius <= 0.) {\n      gl_FragColor = vec4(0., 0., 0., 1.);\n      return;\n    }\n\n    vec3 here = viewAt(vUv, depth);\n    vec3 normal = normalAt(vUv, here, depth);\n\n    // The tile's own rotation, turned into a basis around the normal. One kernel becomes a\n    // different kernel per pixel, with no second kernel to upload.\n    vec3 rotation = vec3(texture2D(uNoise, vUv * uNoiseScale).xy, 0.);\n    vec3 tangent = cross(normal, rotation);\n    // Degenerate only where the rotation lies along the normal, which is a wall seen edge on. The\n    // fallback is degenerate only where the normal is the view axis, the case this one covers, so\n    // between them there is always a tangent.\n    if (dot(tangent, tangent) < 1e-6) tangent = cross(normal, vec3(0., 0., 1.));\n    tangent = normalize(tangent);\n    mat3 orient = mat3(tangent, cross(normal, tangent), normal);\n\n    float occluded = 0.;\n    for (int tap = 0; tap < 16; tap++) {\n      // GLSL ES 1.00 on the old Android WebViews this SDK reaches needs a constant loop bound, and\n      // the break is what skips the taps.\n      if (tap >= uTaps) break;\n      occluded += occlusionTap(here, here + orient * uKernel[tap] * uRadius);\n    }\n\n    // The average divides by what the loop walked, not by what the kernel holds. The floor stops a\n    // tap count of zero from dividing by nothing. No control offers zero, and a stale upload can\n    // still hold it.\n    float term = occluded / max(float(uTaps), 1.);\n\n    // The fade drops the term where the surface turns edge on to the camera, because the normal\n    // that oriented this kernel stops being reliable there. A face turned nearly side on gives\n    // normalAt two neighbors that disagree by almost the same amount. A small camera rotation then\n    // still moves the normal, and the term moves with it.\n    //\n    // The fragment sits in view space here, where the camera is the origin, so its own direction is\n    // the view vector. The dot of that against the normal says how square on the surface is: one\n    // face on, zero edge on. Taken as an absolute value, since a normal reconstructed at a depth\n    // discontinuity can come back pointing away.\n    //\n    // An ordinary wall under this plan's camera reads about 0.82 square on at a 55 degree pitch.\n    // That is well clear of the band, so walls keep their full term.\n    float facing = abs(dot(normal, normalize(here)));\n    gl_FragColor = vec4(term * smoothstep(AO_GRAZING_MIN, AO_GRAZING_MAX, facing), 0., 0., 1.);\n  }\n";
+//# sourceMappingURL=ambient-occlusion-pass.d.ts.map

package/dist/objects/materials/effects/ao/ambient-occlusion-pass.js

@@ -0,0 +1,296 @@
+import { DataTexture, FloatType, Matrix4, NearestFilter, RepeatWrapping, RGBAFormat, Vector2, Vector3, } from 'three';
+/**
+ * Builds one AO pass's uniforms: its own kernel, its own rotation tile, and the matrices and sizes
+ * `OcclusionPasses` refreshes every frame.
+ *
+ * Per mount rather than per module: a `DataTexture` uploads into whichever GL context first draws
+ * with it, and disposal from one mounted scene takes it away from the other. The caller owns the
+ * rotation tile's disposal.
+ *
+ * The frame writes into the matrices and vectors rather than replacing them, so a frame costs no
+ * allocation and no shader recompile.
+ * @returns The uniform record, ready to hand to a `ShaderMaterial`.
+ */
+export function createAoPassUniforms() {
+    return {
+        /** The prepass's depth. The shader unprojects it per tap. `null` until the first pass runs. */
+        uDepth: { value: null },
+        /** The rotation tile, which repeats over the target. See {@link createNoiseTexture}. */
+        uNoise: { value: createNoiseTexture() },
+        /** The guard band's projection, which places a view-space tap back on the depth texture. */
+        uProjection: { value: new Matrix4() },
+        /** Its inverse, which turns a stored depth back into a view position. */
+        uUnprojection: { value: new Matrix4() },
+        /** One texel of the target in uv, the step the normal reconstruction walks. */
+        uTexel: { value: new Vector2(1, 1) },
+        /** The target's size in rotation tiles, so the tile repeats every {@link NOISE_TILE} texels. */
+        uNoiseScale: { value: new Vector2(1, 1) },
+        /** How far the kernel reaches, in view units. */
+        uRadius: { value: 1 },
+        /**
+         * How many of the kernel's offsets to walk, from `1` to {@link AO_TAPS}. `OcclusionPasses`
+         * rewrites it each frame from `AmbientOcclusion.taps`, the way it rewrites the radius.
+         */
+        uTaps: { value: AO_TAPS },
+        /** The hemisphere kernel around `+z`, which the shader rotates per fragment. */
+        uKernel: { value: createKernel() },
+    };
+}
+/**
+ * Builds the rotation tile: {@link NOISE_TILE} squared texels, each a unit vector in the tangent
+ * plane, `RGBA` floats at {@link NearestFilter} and {@link RepeatWrapping}. 256 bytes, and no asset
+ * ships with it.
+ *
+ * A texture rather than a hash of `gl_FragCoord`, for two reasons. The tile size and the blur
+ * kernel have to match: a `4 × 4` blur averages a `4 × 4` tile repeated over the screen. A hash
+ * gives every pixel its own rotation, and no fixed kernel averages that. And a hash leans on
+ * high-precision float arithmetic, which some drivers on the old Android WebViews this SDK reaches
+ * run at `mediump`.
+ *
+ * The angles step by the golden ratio's conjugate, so two neighboring texels sit about `222°`
+ * apart. Deterministic, because a screenshot baseline has to reproduce.
+ * @returns The tile, ready to upload.
+ */
+function createNoiseTexture() {
+    const texels = NOISE_TILE * NOISE_TILE;
+    const data = new Float32Array(texels * RGBA_CHANNELS);
+    for (let texel = 0; texel < texels; texel++) {
+        const angle = 2 * Math.PI * fraction(texel * GOLDEN_CONJUGATE);
+        data[texel * RGBA_CHANNELS] = Math.cos(angle);
+        data[texel * RGBA_CHANNELS + 1] = Math.sin(angle);
+        data[texel * RGBA_CHANNELS + 2] = 0;
+        data[texel * RGBA_CHANNELS + 3] = 1;
+    }
+    const noise = new DataTexture(data, NOISE_TILE, NOISE_TILE, RGBAFormat, FloatType);
+    noise.minFilter = NearestFilter;
+    noise.magFilter = NearestFilter;
+    noise.wrapS = RepeatWrapping;
+    noise.wrapT = RepeatWrapping;
+    noise.needsUpdate = true;
+    return noise;
+}
+/**
+ * Builds the hemisphere kernel: {@link AO_TAPS} offsets around `+z`, in view units of the radius.
+ *
+ * The directions come from the two-dimensional Roberts sequence, whose two irrational strides keep
+ * the pair of coordinates low-discrepancy. One stride drives the azimuth and the other the
+ * elevation's cosine, and the sequence's own half-step offset keeps the first tap off the tangent
+ * plane. The lengths climb with the index as a square, which clusters the taps near the fragment
+ * where an occluder matters most.
+ *
+ * Generated rather than tabulated, so the count and the pattern cannot drift apart. Deterministic,
+ * so a screenshot baseline reproduces.
+ * @returns The kernel, in the order the shader walks it.
+ */
+function createKernel() {
+    const kernel = [];
+    for (let tap = 0; tap < AO_TAPS; tap++) {
+        const azimuth = 2 * Math.PI * fraction(SEQUENCE_OFFSET + tap * ROBERTS_X);
+        const elevation = fraction(SEQUENCE_OFFSET + tap * ROBERTS_Y);
+        const ring = Math.sqrt(1 - elevation * elevation);
+        const length = KERNEL_FLOOR + (1 - KERNEL_FLOOR) * ((tap + 1) / AO_TAPS) ** 2;
+        kernel.push(new Vector3(Math.cos(azimuth) * ring * length, Math.sin(azimuth) * ring * length, elevation * length));
+    }
+    return kernel;
+}
+/**
+ * The fractional part of a number, which turns a low-discrepancy stride into a sequence.
+ * @param value - The number to take the fraction of.
+ * @returns Its fractional part, in `[0, 1)`.
+ */
+function fraction(value) {
+    return value - Math.floor(value);
+}
+/** How many taps the kernel holds, which is the AO pass loop's bound and its default count. */
+export const AO_TAPS = 16;
+/**
+ * The rotation tile's edge in texels, which is the blur pass's kernel bound and its default side.
+ *
+ * One decision with the blur kernel rather than two: a `4 × 4` tile needs a `4 × 4` kernel to
+ * average out. The GUI reaches a smaller kernel, which trades structured noise for the fetches it
+ * skips.
+ */
+export const NOISE_TILE = 4;
+/**
+ * Both full-screen passes' vertex stage: a clip-space quad, the way `Background` draws one.
+ *
+ * `position.xy` of a `2 × 2` plane already spans clip space, so the stage reads no matrix and the
+ * camera means nothing. `z` sits at `0` rather than the far plane, because the passes draw with no
+ * depth test.
+ */
+export const AO_VERTEX_SHADER = /* glsl */ `
+  varying vec2 vUv;
+
+  void main() {
+    vUv = uv;
+    gl_Position = vec4(position.xy, 0.0, 1.0);
+  }
+`;
+/**
+ * The AO pass's fragment stage: a hemisphere-kernel occlusion pass, with the one substitution a
+ * floor plan renderer forces.
+ *
+ * There is no G-buffer. The pass unprojects the fragment's own view position from the prepass
+ * depth, and `normalAt` reconstructs the normal from that same depth.
+ *
+ * Every position and length below sits in view space, which is where three's own lighting works and
+ * where this pass's inverse projection lands. View space looks down `-z`, so a larger `z` is nearer
+ * the camera, and `occlusionTap` compares depths that way.
+ *
+ * The pass writes occlusion, not visibility: `0` is open, `1` is closed, raw and unblurred. A pass
+ * of its own smooths it, see `BLUR_FRAGMENT_SHADER`.
+ *
+ * `AO_BIAS` is the slack that keeps a tap on the fragment's own flat face from reading as an
+ * occluder. It is a share of the radius, so it holds at any zoom. A tap keeps its full value until
+ * the surface it found is a radius away in depth, then falls to nothing. That keeps a wall from
+ * darkening whatever stands far behind it.
+ */
+export const AO_FRAGMENT_SHADER = /* glsl */ `
+  uniform sampler2D uDepth;
+  uniform sampler2D uNoise;
+  uniform mat4 uProjection;
+  uniform mat4 uUnprojection;
+  uniform vec2 uTexel;
+  uniform vec2 uNoiseScale;
+  uniform float uRadius;
+  uniform int uTaps;
+  uniform vec3 uKernel[${AO_TAPS}];
+  varying vec2 vUv;
+
+  const float AO_BIAS = 0.02;
+
+  // Where the grazing fade starts and ends, as the absolute dot of the normal against the view
+  // direction: fully faded about seventeen degrees from edge on, fully open by about forty. See the
+  // fade at the end of main.
+  const float AO_GRAZING_MIN = 0.30;
+  const float AO_GRAZING_MAX = 0.64;
+
+  // How far apart the two neighbors of an axis have to be before blendAxis takes the nearer one
+  // outright. Measured as a share of their sum. Larger crosses over more gently and softens a
+  // silhouette. Smaller sharpens the silhouette and brings the normal jump back.
+  const float AO_CROSSOVER = 0.45;
+
+  float depthAt(vec2 uv) {
+    return texture2D(uDepth, uv).x;
+  }
+
+  vec3 viewAt(vec2 uv, float depth) {
+    vec4 clip = vec4(uv * 2. - 1., depth * 2. - 1., 1.);
+    vec4 view = uUnprojection * clip;
+    return view.xyz / view.w;
+  }
+
+  vec3 blendAxis(vec3 back, vec3 forward, float backApart, float forwardApart) {
+    // Positive when the backward neighbor is the worse of the two, which moves the result toward
+    // the forward one. Normalized by the sum, so AO_CROSSOVER is a share rather than a depth.
+    float ratio = (backApart - forwardApart) / max(backApart + forwardApart, 1e-6);
+    return mix(back, forward, smoothstep(-AO_CROSSOVER, AO_CROSSOVER, ratio));
+  }
+
+  vec3 normalAt(vec2 uv, vec3 here, float depth) {
+    vec2 stepX = vec2(uTexel.x, 0.);
+    vec2 stepY = vec2(0., uTexel.y);
+    float left = depthAt(uv - stepX);
+    float right = depthAt(uv + stepX);
+    float down = depthAt(uv - stepY);
+    float up = depthAt(uv + stepY);
+
+    // blendAxis leans toward the neighbor that stays on this surface rather than switching to it. A
+    // hard pick makes a face turned side on jump: both depth differences are large and nearly equal
+    // there, so a small camera rotation crosses the comparison and the normal jumps with it. The
+    // smoothstep over their difference crosses that middle continuously.
+    vec3 alongX = blendAxis(here - viewAt(uv - stepX, left), viewAt(uv + stepX, right) - here,
+                            abs(depth - left), abs(right - depth));
+    vec3 alongY = blendAxis(here - viewAt(uv - stepY, down), viewAt(uv + stepY, up) - here,
+                            abs(depth - down), abs(up - depth));
+
+    vec3 normal = normalize(cross(alongX, alongY));
+    // A surface the camera sees faces the camera, and view space looks down -z. The flip matters in
+    // external mode, where the host's projection can mirror an axis and turn the cross product with
+    // it. The wrong side samples the hemisphere behind the surface.
+    return normal.z < 0. ? -normal : normal;
+  }
+
+  float occlusionTap(vec3 here, vec3 at) {
+    vec4 clip = uProjection * vec4(at, 1.);
+    // At or behind the eye, where the perspective divide has no answer. Orthographic keeps w at 1,
+    // so this costs a comparison there and nothing else.
+    if (clip.w <= 0.) return 0.;
+    vec2 uv = clip.xy / clip.w * .5 + .5;
+    // Screen space sees only what is on screen. A tap off the edge has no depth of its own, and
+    // clamped sampling answers with the border texel's depth, so the tap contributes nothing.
+    if (uv.x < 0. || uv.x > 1. || uv.y < 0. || uv.y > 1.) return 0.;
+    float stored = depthAt(uv);
+    // The prepass clears to the far plane, so a tap over open background lands there. This rejects
+    // that tap rather than darkening an edge.
+    if (stored >= 1.) return 0.;
+    float storedZ = viewAt(uv, stored).z;
+    // Nothing in front of the tap: this surface is open in that direction.
+    if (storedZ < at.z + uRadius * AO_BIAS) return 0.;
+    return smoothstep(0., 1., uRadius / abs(here.z - storedZ));
+  }
+
+  void main() {
+    float depth = depthAt(vUv);
+    // Nothing here, or nothing to reach with. The prepass clears to the far plane. A radius of zero
+    // puts every tap on the fragment itself, where the divide by its distance has no answer.
+    if (depth >= 1. || uRadius <= 0.) {
+      gl_FragColor = vec4(0., 0., 0., 1.);
+      return;
+    }
+
+    vec3 here = viewAt(vUv, depth);
+    vec3 normal = normalAt(vUv, here, depth);
+
+    // The tile's own rotation, turned into a basis around the normal. One kernel becomes a
+    // different kernel per pixel, with no second kernel to upload.
+    vec3 rotation = vec3(texture2D(uNoise, vUv * uNoiseScale).xy, 0.);
+    vec3 tangent = cross(normal, rotation);
+    // Degenerate only where the rotation lies along the normal, which is a wall seen edge on. The
+    // fallback is degenerate only where the normal is the view axis, the case this one covers, so
+    // between them there is always a tangent.
+    if (dot(tangent, tangent) < 1e-6) tangent = cross(normal, vec3(0., 0., 1.));
+    tangent = normalize(tangent);
+    mat3 orient = mat3(tangent, cross(normal, tangent), normal);
+
+    float occluded = 0.;
+    for (int tap = 0; tap < ${AO_TAPS}; tap++) {
+      // GLSL ES 1.00 on the old Android WebViews this SDK reaches needs a constant loop bound, and
+      // the break is what skips the taps.
+      if (tap >= uTaps) break;
+      occluded += occlusionTap(here, here + orient * uKernel[tap] * uRadius);
+    }
+
+    // The average divides by what the loop walked, not by what the kernel holds. The floor stops a
+    // tap count of zero from dividing by nothing. No control offers zero, and a stale upload can
+    // still hold it.
+    float term = occluded / max(float(uTaps), 1.);
+
+    // The fade drops the term where the surface turns edge on to the camera, because the normal
+    // that oriented this kernel stops being reliable there. A face turned nearly side on gives
+    // normalAt two neighbors that disagree by almost the same amount. A small camera rotation then
+    // still moves the normal, and the term moves with it.
+    //
+    // The fragment sits in view space here, where the camera is the origin, so its own direction is
+    // the view vector. The dot of that against the normal says how square on the surface is: one
+    // face on, zero edge on. Taken as an absolute value, since a normal reconstructed at a depth
+    // discontinuity can come back pointing away.
+    //
+    // An ordinary wall under this plan's camera reads about 0.82 square on at a 55 degree pitch.
+    // That is well clear of the band, so walls keep their full term.
+    float facing = abs(dot(normal, normalize(here)));
+    gl_FragColor = vec4(term * smoothstep(AO_GRAZING_MIN, AO_GRAZING_MAX, facing), 0., 0., 1.);
+  }
+`;
+/** Channels one `RGBA` texel carries. */
+const RGBA_CHANNELS = 4;
+/** The golden ratio's conjugate, whose multiples are the rotation tile's low-discrepancy angles. */
+const GOLDEN_CONJUGATE = 0.6180339887498949;
+/** The sequence's own half-step offset, which both Roberts strides count from. */
+const SEQUENCE_OFFSET = 0.5;
+/** The two-dimensional Roberts sequence's first stride, which drives the kernel's azimuth. */
+const ROBERTS_X = 0.7548776662466927;
+/** Its second stride, which drives the kernel's elevation. */
+const ROBERTS_Y = 0.5698402909980532;
+/** The shortest kernel offset, as a share of the radius, so no tap lands on its own texel. */
+const KERNEL_FLOOR = 0.1;

package/dist/objects/materials/effects/ao/ambient-occlusion-patch.d.ts

@@ -0,0 +1,29 @@
+import { type WebGLProgramParametersWithUniforms } from 'three';
+import { type ContactShadow } from '../contact-shadow';
+import { type AmbientOcclusion } from './index';
+/**
+ * Installs this term's read into a lit shader about to be compiled: the upsample and the blend, in
+ * two texture fetches.
+ *
+ * The blur is not here. It is a pass of its own, see `BLUR_FRAGMENT_SHADER`, and that pass bills
+ * per texel of a quarter-area target. Everything in this function bills per lit fragment at full
+ * resolution and once per overdraw. A kernel folded in here costs `2 · side²` fetches a fragment.
+ *
+ * The depth fetch stays. Translucent content draws into no prepass, so no stored depth agrees with
+ * it, the weight falls to zero, and the term leaves it alone. The main pass binds no framebuffer
+ * that carries the depth texture, so the sample is legal. Two of the three occlusion targets carry
+ * no depth attachment for that reason.
+ *
+ * The term lands at the anchor the contact shadow and the dim patch use, above three's output
+ * chain. It mixes toward the shade the contact shadow blends toward, so a plan has one shadow
+ * color. three has a line where occlusion physically belongs, `#include <aomap_fragment>`, and the
+ * design spec's D8 records why it loses here: it multiplies a light term rather than mixing toward
+ * a color, and the fill it scales is a minority of a lit wall's light.
+ * @param parameters - The shader being compiled.
+ * @param occlusion - The mount's own effect state, whose uniform objects the compiled program
+ *   captures. The shade is the contact shadow's, because the two terms share one.
+ * @throws {Error} If the shader has no output chain, which leaves the term silently absent from a
+ *   material that asked for it.
+ */
+export declare function applyAmbientOcclusion(parameters: WebGLProgramParametersWithUniforms, occlusion: AmbientOcclusion & ContactShadow): void;
+//# sourceMappingURL=ambient-occlusion-patch.d.ts.map

package/dist/objects/materials/effects/ao/ambient-occlusion-patch.js

@@ -0,0 +1,115 @@
+import { declareBeforeMain, sceneColorAnchor } from '../../../../core/shader-source';
+import { AO_EDGE_TOLERANCE } from './blur-pass';
+/**
+ * Installs this term's read into a lit shader about to be compiled: the upsample and the blend, in
+ * two texture fetches.
+ *
+ * The blur is not here. It is a pass of its own, see `BLUR_FRAGMENT_SHADER`, and that pass bills
+ * per texel of a quarter-area target. Everything in this function bills per lit fragment at full
+ * resolution and once per overdraw. A kernel folded in here costs `2 · side²` fetches a fragment.
+ *
+ * The depth fetch stays. Translucent content draws into no prepass, so no stored depth agrees with
+ * it, the weight falls to zero, and the term leaves it alone. The main pass binds no framebuffer
+ * that carries the depth texture, so the sample is legal. Two of the three occlusion targets carry
+ * no depth attachment for that reason.
+ *
+ * The term lands at the anchor the contact shadow and the dim patch use, above three's output
+ * chain. It mixes toward the shade the contact shadow blends toward, so a plan has one shadow
+ * color. three has a line where occlusion physically belongs, `#include <aomap_fragment>`, and the
+ * design spec's D8 records why it loses here: it multiplies a light term rather than mixing toward
+ * a color, and the fill it scales is a minority of a lit wall's light.
+ * @param parameters - The shader being compiled.
+ * @param occlusion - The mount's own effect state, whose uniform objects the compiled program
+ *   captures. The shade is the contact shadow's, because the two terms share one.
+ * @throws {Error} If the shader has no output chain, which leaves the term silently absent from a
+ *   material that asked for it.
+ */
+export function applyAmbientOcclusion(parameters, occlusion) {
+    // Already installed, which is how a repeated compile stays harmless.
+    if (parameters.fragmentShader.includes(AO_FUNCTION))
+        return;
+    const anchor = sceneColorAnchor(parameters.fragmentShader);
+    if (!anchor) {
+        throw new Error('applyAmbientOcclusion: the shader has no output chain to darken before.');
+    }
+    // The rewrite runs before any write, so this either installs the term or leaves the parameters as
+    // it found them. `declareBeforeMain` throws on a shader with no `main`, and a caller that carries
+    // on must not hold seven bindings for a program nothing patched.
+    const fragmentShader = declareBeforeMain(parameters.fragmentShader, AO_LIT_DEFS).replace(anchor, `${AO_LIT_APPLY}\n${anchor}`);
+    parameters.uniforms[AO_MAP] = occlusion.aoMap;
+    parameters.uniforms[AO_DEPTH] = occlusion.aoDepth;
+    parameters.uniforms[AO_ACTIVE] = occlusion.aoActive;
+    parameters.uniforms[AO_GUARD] = occlusion.aoGuard;
+    parameters.uniforms[AO_STRENGTH] = occlusion.aoStrength;
+    parameters.uniforms[AO_VIEWPORT] = occlusion.aoViewport;
+    // The contact shadow's own object, under a name of this term's. One shade for both terms, and no
+    // GLSL contract between two patches about who declares it.
+    parameters.uniforms[AO_COLOR] = occlusion.shadowColor;
+    parameters.fragmentShader = fragmentShader;
+}
+/** The uniform carrying the smoothed occlusion the blur pass wrote. */
+const AO_MAP = 'uAoMap';
+/** The uniform carrying the prepass's depth, which weights the one sample this read takes. */
+const AO_DEPTH = 'uAoDepth';
+/** The uniform that gates the read, `1` while the passes drew this frame. */
+const AO_ACTIVE = 'uAoActive';
+/** The uniform carrying the guard band, which turns `gl_FragCoord` into a uv. */
+const AO_GUARD = 'uAoGuard';
+/** The uniform carrying how far an occluded fragment blends toward the shade. */
+const AO_STRENGTH = 'uAoStrength';
+/** The uniform carrying the drawing buffer's size, the unit `gl_FragCoord` counts in. */
+const AO_VIEWPORT = 'uAoViewport';
+/** The uniform carrying the shade to blend toward, which is the contact shadow's own. */
+const AO_COLOR = 'uAoColor';
+/** The signature {@link applyAmbientOcclusion} looks for in an already patched shader. */
+const AO_FUNCTION = 'vec3 ambientOcclusion(';
+/**
+ * The lit-stage declarations: this term's uniforms, and the read that upsamples and blends in two
+ * texture fetches.
+ *
+ * The fragment's own depth is `gl_FragCoord.z` rather than another read of the depth texture. That
+ * is exact, where a read of a half-resolution texture is an approximation. The comparison buys
+ * translucent content: it drew into no prepass, so the stored depth disagrees, the weight falls to
+ * zero, and the term leaves it alone. The prepass keeps the same rule on the casting side.
+ */
+const AO_LIT_DEFS = /* glsl */ `
+  uniform sampler2D ${AO_MAP};
+  uniform sampler2D ${AO_DEPTH};
+  uniform float ${AO_ACTIVE};
+  uniform float ${AO_GUARD};
+  uniform float ${AO_STRENGTH};
+  uniform vec2 ${AO_VIEWPORT};
+  uniform vec3 ${AO_COLOR};
+
+  const float AO_EDGE = ${AO_EDGE_TOLERANCE};
+
+  ${AO_FUNCTION}vec3 rgb, float depth) {
+    // A frame that skipped the passes shades correctly rather than sampling a stale texture.
+    if (${AO_ACTIVE} < .5) return rgb;
+
+    // The guard band undone. Every pass ran on a frustum (1 + g) wider than this one. This
+    // fragment's place in the AO texture is its ndc shrunk by that factor.
+    vec2 uv = ((gl_FragCoord.xy / ${AO_VIEWPORT}) * 2. - 1.) / (1. + ${AO_GUARD}) * .5 + .5;
+
+    // Whether the term measured the surface this fragment shades. Stored depth is not linear, so
+    // the difference is a share of the range still ahead of this fragment.
+    float stored = texture2D(${AO_DEPTH}, uv).x;
+    float apart = abs(stored - depth) / max(1. - depth, 1e-6);
+    float weight = 1. - smoothstep(0., AO_EDGE, apart);
+    // Nothing here describes the surface this fragment is on, a translucent one most of all. There
+    // is no term to apply and no second fetch worth taking.
+    if (weight <= 0.) return rgb;
+
+    return mix(rgb, ${AO_COLOR}, ${AO_STRENGTH} * texture2D(${AO_MAP}, uv).r * weight);
+  }
+`;
+/**
+ * The call that applies the term while the color is still linear and scene-referred, after the
+ * contact shadow and before the dim patch.
+ *
+ * The call is spelled out rather than built from {@link AO_FUNCTION}, which stays the
+ * already-patched detector and nothing else.
+ */
+const AO_LIT_APPLY = /* glsl */ `
+  gl_FragColor.rgb = ambientOcclusion(gl_FragColor.rgb, gl_FragCoord.z);
+`;

package/dist/objects/materials/effects/ao/blur-pass.d.ts

@@ -0,0 +1,61 @@
+import { type IUniform, type Texture, Vector2 } from 'three';
+import { type AmbientOcclusion } from './index';
+/** The blur pass's uniforms, as {@link createBlurPassUniforms} builds them. */
+export type BlurPassUniforms = ReturnType<typeof createBlurPassUniforms>;
+/**
+ * Builds one blur pass's uniforms: the two textures it reads, its own texel step, and the scene's
+ * own kernel side.
+ *
+ * Per mount rather than per module, for the reason `createAoPassUniforms` is. These carry textures
+ * allocated in whichever GL context drew them, and a second mounted scene has a second set.
+ *
+ * {@link AmbientOcclusion.aoBlur} arrives by identity rather than by copy, so the debug GUI's write
+ * lands in this shader with nothing in between. The frame writes into everything else in place, so
+ * a frame costs no allocation and no shader recompile.
+ * @param occlusion - The mounted scene's own occlusion state, for the kernel side the debug GUI
+ *   tunes.
+ * @returns The uniform record, ready to hand to a `ShaderMaterial`.
+ */
+export declare function createBlurPassUniforms(occlusion: AmbientOcclusion): {
+    /** The raw term the AO pass wrote, which this pass smooths. `null` until the AO pass runs. */
+    uOcclusion: IUniform<Texture | null>;
+    /** The prepass's depth, which weights every tap. `null` until the prepass runs. */
+    uDepth: IUniform<Texture | null>;
+    /** One texel of this pass's own target in uv, the step the kernel walks. */
+    uTexel: IUniform<Vector2>;
+    /** The kernel's side in texels, the scene's own object. See {@link AmbientOcclusion.aoBlur}. */
+    uBlur: IUniform<number>;
+};
+/**
+ * How far apart two depths sit before a read stops treating them as one surface. Measured as a
+ * share of the range still ahead of the nearer one.
+ *
+ * One number for both readers, because they ask the same question. The blur pass asks it of every
+ * tap, so occlusion does not bleed across the edge between a wall and whatever stands behind it.
+ * The lit read asks it once, so a translucent surface, which drew into no prepass, takes no
+ * occlusion from whatever stands behind it.
+ *
+ * Too tight, and the tile's rotation survives the blur as visible noise, because the pass throws
+ * most taps away. Too loose, and occlusion bleeds a few pixels past a silhouette. The bleed is the
+ * gentler failure, so this number errs generous.
+ */
+export declare const AO_EDGE_TOLERANCE = 0.05;
+/**
+ * The blur pass's fragment stage: the depth-weighted square kernel that smooths the raw term.
+ *
+ * The kernel runs here rather than inside the lit material's read. There it bills per lit fragment
+ * at full resolution and once per overdraw, at `2 · side²` fetches. Measured on a real plan: `2 ms`
+ * with no occlusion at all, `4 ms` at side `1`, and `8 ms` at side `4`. The AO pass's tap count
+ * makes no measurable difference. Here the kernel bills once per texel of a quarter-area target
+ * with no overdraw, and the lit read drops to two fetches.
+ *
+ * The pass samples the depth texture while it writes a color texture, so it binds a target with no
+ * depth attachment. A write through the prepass's own target is a rendering feedback loop, which
+ * WebGL2 leaves undefined and browsers refuse. That is what the third render target is for, see
+ * `occlusion-targets.ts`.
+ *
+ * This fragment's own depth comes from the texture, because the pass carries no geometry that
+ * writes one. One fetch, at this texel's own center.
+ */
+export declare const BLUR_FRAGMENT_SHADER = "\n  uniform sampler2D uOcclusion;\n  uniform sampler2D uDepth;\n  uniform vec2 uTexel;\n  uniform int uBlur;\n  varying vec2 vUv;\n\n  const float AO_EDGE = 0.05;\n\n  void main() {\n    float depth = texture2D(uDepth, vUv).x;\n    // Symmetric at any side, and this texel alone at side 1.\n    float center = float(uBlur - 1) * .5;\n    float occluded = 0.;\n    float total = 0.;\n    // GLSL ES 1.00 on the old Android WebViews this SDK reaches needs constant loop bounds, and the\n    // break is what skips the fetches.\n    for (int y = 0; y < 4; y++) {\n      if (y >= uBlur) break;\n      for (int x = 0; x < 4; x++) {\n        if (x >= uBlur) break;\n        vec2 at = vUv + (vec2(float(x), float(y)) - center) * uTexel;\n        // Depth-aware, so occlusion does not bleed across the edge between a wall and whatever\n        // stands behind it. Stored depth is not linear, so the difference is a share of the range\n        // still ahead of this texel.\n        float stored = texture2D(uDepth, at).x;\n        float apart = abs(stored - depth) / max(1. - depth, 1e-6);\n        float weight = 1. - smoothstep(0., AO_EDGE, apart);\n        occluded += texture2D(uOcclusion, at).r * weight;\n        total += weight;\n      }\n    }\n\n    // Nothing around this texel describes the surface it is on, so there is no term to write and no\n    // total to divide by. Open, which a lit read of it leaves alone.\n    if (total <= 0.) {\n      gl_FragColor = vec4(0., 0., 0., 1.);\n      return;\n    }\n    gl_FragColor = vec4(occluded / total, 0., 0., 1.);\n  }\n";
+//# sourceMappingURL=blur-pass.d.ts.map