@woosh/meep-engine 2.138.13 → 2.138.15

package/src/engine/graphics/impostors/octahedral/prototypeBaker.js

@@ -22,7 +22,12 @@ import { ShadedGeometryFlags } from "../../ecs/mesh-v2/ShadedGeometryFlags.js";
 import { ShadedGeometrySystem } from "../../ecs/mesh-v2/ShadedGeometrySystem.js";
 import { ImpostorBaker } from "./ImpostorBaker.js";
 import { ImpostorCaptureType } from "./ImpostorCaptureType.js";
+import { ImpostorShaderDepthV0 } from "./shader/ImpostorShaderDepthV0.js";
+import { ImpostorShaderLitV0 } from "./shader/ImpostorShaderLitV0.js";
+import { ImpostorShaderNormalsV0 } from "./shader/ImpostorShaderNormalsV0.js";
+import { ImpostorShaderPerPixelV0 } from "./shader/ImpostorShaderPerPixelV0.js";
 import { ImpostorShaderV0 } from "./shader/ImpostorShaderV0.js";
+import { ImpostorShaderViewportDepthV0 } from "./shader/ImpostorShaderViewportDepthV0.js";
 import { ImpostorShaderWireframeV0 } from "./shader/ImpostorShaderWireframeV0.js";
 import { build_geometry_from_cutout_shape } from "./util/build_geometry_from_cutout_shape.js";
 import { load_mesh_for_bake } from "./util/load_mesh_for_bake.js";
@@ -42,6 +47,13 @@ async function main(engine) {
         enableLights: true,
         enableShadows: true,
         cameraAutoClip: true,
+        // Default terrain is 20x20 (size 10 * gridScale 2). The impostor
+        // lineup below stretches x=10..25, so widen the plane to fit
+        // everything plus a small margin on each side.
+        terrainSize: new Vector2(18, 12),
+        // Recentre the camera focus on the lineup's midpoint so the
+        // wider terrain is framed correctly rather than slid off-screen.
+        focus: new Vector3(17, 0, 10),
     });
 
 
@@ -73,7 +85,7 @@ async function main(engine) {
     const id = baker.bake({
         objects,
         frames: 32,
-        resolution: 1024,
+        resolution: 1024*8,
         type: ImpostorCaptureType.FullSphere
     });
     // console.profileEnd('bake');
@@ -95,7 +107,12 @@ async function main(engine) {
         .add(GUIElement.fromView(ctrl))
         // .build(ecd);
 
-    // build out preview scene with impostor and the original
+    // build out preview scene: lay out the five variants side-by-side
+    // (V0 / per-pixel V0 / lit / world-normal viz / true mesh) so they
+    // share the same scene lighting and the differences are easy to
+    // compare. The normals viz sits next to lit because it shows exactly
+    // what the lit shader is feeding to the lighting equations — handy
+    // for diagnosing wrong-looking shading.
     const t0 = Transform.fromJSON({
         position: { x: 10, y: 0.5, z: 10 },
         scale: 3,
@@ -104,15 +121,45 @@ async function main(engine) {
 
     t0.scale.setScalar(3 / (id.sphere_radius * 2));
 
+    // Slot 0: original V0 + its wireframe overlay.
     const entity_impostor = make_impostor_entity(id, t0);
     entity_impostor.build(ecd);
 
     const entity_impostor_wireframe = make_impostor_wireframe(id, t0);
     entity_impostor_wireframe.build(ecd);
 
-    const t1 = new Transform();
-    t1.copy(t0);
-    t1.position._add(3, 0, 0);
+    // Slot 1: per-pixel projection variant (visually identical to V0).
+    const t_per_pixel = new Transform();
+    t_per_pixel.copy(t0);
+    t_per_pixel.position._add(3, 0, 0);
+    make_impostor_per_pixel_entity(id, t_per_pixel).build(ecd);
+
+    // Slot 2: lit variant — only one that responds to scene lights and
+    // receives shadows from neighbours.
+    const t_lit = new Transform();
+    t_lit.copy(t0);
+    t_lit.position._add(6, 0, 0);
+    make_impostor_lit_entity(id, t_lit).build(ecd);
+
+    // Slot 3: world-space normal viz (debug pair for the lit variant).
+    const t_normals = new Transform();
+    t_normals.copy(t0);
+    t_normals.position._add(9, 0, 0);
+    make_impostor_normals_entity(id, t_normals).build(ecd);
+
+    // Slot 4: viewport-depth viz — shows the parallax surface's
+    // gl_FragCoord.z-equivalent as grayscale. Same construction the
+    // caster's gl_FragDepth uses; useful for spotting where the lit
+    // shader's shadow coord diverges from what the shadow map holds.
+    const t_depth = new Transform();
+    t_depth.copy(t0);
+    t_depth.position._add(12, 0, 0);
+    make_impostor_viewport_depth_entity(id, t_depth).build(ecd);
+
+    // Slot 5: original mesh as ground-truth reference.
+    const t_truth = new Transform();
+    t_truth.copy(t0);
+    t_truth.position._add(15, 0, 0);
 
     const sg_mesh = SGMesh.fromURL(path);
 
@@ -122,7 +169,7 @@ async function main(engine) {
     const entity_true_mesh = new Entity();
     entity_true_mesh
         .add(sg_mesh)
-        .add(t1)
+        .add(t_truth)
         .build(ecd);
 
 
@@ -153,7 +200,7 @@ function make_spin(entity, speed = 1, axis = Vector3.up) {
 
 /**
  *
- * @param {{tBase,tGeometry,uFrames,uOffset,uRadius,uIsFullSphere}} uniforms
+ * @param {{tBase,tGeometry,uFrames,uOffset,uRadius,uIsFullSphere,tMaterial?}} uniforms
  * @param {ImpostorDescription} id
  */
 function write_impostor_definition_to_material_uniforms(uniforms, id) {
@@ -164,6 +211,12 @@ function write_impostor_definition_to_material_uniforms(uniforms, id) {
     uniforms.uOffset.value.set(id.offset[0], id.offset[1], id.offset[2]);
     uniforms.uRadius.value = id.sphere_radius;
     uniforms.uIsFullSphere.value = id.capture_type === ImpostorCaptureType.FullSphere;
+
+    // ORM texture is only consumed by the lit shader; older variants
+    // declare the uniform but never read it, so the assignment is harmless.
+    if (uniforms.tMaterial !== undefined) {
+        uniforms.tMaterial.value = id.rt.texture[2];
+    }
 }
 
 function make_impostor_wireframe(id, t = new Transform()) {
@@ -188,6 +241,19 @@ function make_impostor_wireframe(id, t = new Transform()) {
         ;
 }
 
+/**
+ * Build a `depth_material` instance for shadow casting that mirrors the
+ * card geometry of whichever colour material we're using. Pulling this
+ * out keeps the per-variant factories below short.
+ *
+ * @param {ImpostorDescription} id
+ */
+function make_impostor_depth_material(id) {
+    const depth_mat = new ImpostorShaderDepthV0();
+    write_impostor_definition_to_material_uniforms(depth_mat.uniforms, id);
+    return depth_mat;
+}
+
 /**
  *
  * @param {ImpostorDescription} id
@@ -206,7 +272,104 @@ function make_impostor_entity(id, t = new Transform()) {
 
     const sg = ShadedGeometry.from(build_geometry_from_cutout_shape(id.cutout), mat);
 
-    sg.depth_material = mat;
+    // V0 is unlit so it has no shadow to receive; it can still CAST a
+    // shadow using ImpostorShaderDepthV0, which traces the same parallax
+    // surface so the silhouette matches.
+    sg.depth_material = make_impostor_depth_material(id);
+    sg.clearFlag(ShadedGeometryFlags.ReceiveShadow);
+
+    return new Entity()
+        .add(transform)
+        .add(sg)
+        ;
+
+}
+
+/**
+ * Same as {@link make_impostor_entity} but with the per-pixel projection
+ * variant. Visually identical at the same camera distance — the difference
+ * is purely where the projection math runs on the GPU.
+ *
+ * @param {ImpostorDescription} id
+ * @param {Transform} t
+ * @returns {Entity}
+ */
+function make_impostor_per_pixel_entity(id, t = new Transform()) {
+
+    const mat = new ImpostorShaderPerPixelV0();
+
+    write_impostor_definition_to_material_uniforms(mat.uniforms, id);
+
+    const transform = new Transform();
+    transform.copy(t);
+
+    const sg = ShadedGeometry.from(build_geometry_from_cutout_shape(id.cutout), mat);
+
+    sg.depth_material = make_impostor_depth_material(id);
+    sg.clearFlag(ShadedGeometryFlags.ReceiveShadow);
+
+    return new Entity()
+        .add(transform)
+        .add(sg)
+        ;
+}
+
+/**
+ * Debug viz: shows the world-space surface normal at each impostor pixel
+ * as RGB. Same parallax + atlas-decode math as the lit shader, so any
+ * weirdness here is also producing the lit shader's lighting.
+ *
+ * @param {ImpostorDescription} id
+ * @param {Transform} t
+ * @returns {Entity}
+ */
+function make_impostor_normals_entity(id, t = new Transform()) {
+
+    const mat = new ImpostorShaderNormalsV0();
+
+    write_impostor_definition_to_material_uniforms(mat.uniforms, id);
+
+    const transform = new Transform();
+    transform.copy(t);
+
+    const sg = ShadedGeometry.from(build_geometry_from_cutout_shape(id.cutout), mat);
+
+    // Viz pass: don't participate in shadow casting/receiving — otherwise
+    // it'd influence its lit neighbour's shadow and confuse the comparison.
+    sg.depth_material = make_impostor_depth_material(id);
+    sg.clearFlag(ShadedGeometryFlags.CastShadow);
+    sg.clearFlag(ShadedGeometryFlags.ReceiveShadow);
+
+    return new Entity()
+        .add(transform)
+        .add(sg)
+        ;
+}
+
+/**
+ * Debug viz: shows the parallax-corrected surface's VIEWPORT depth as
+ * grayscale (closer = brighter). Same surface-position math as the lit
+ * shader's shadow coord and the depth material's gl_FragDepth write, so
+ * if shadows look wrong this slot is the most direct check.
+ *
+ * @param {ImpostorDescription} id
+ * @param {Transform} t
+ * @returns {Entity}
+ */
+function make_impostor_viewport_depth_entity(id, t = new Transform()) {
+
+    const mat = new ImpostorShaderViewportDepthV0();
+
+    write_impostor_definition_to_material_uniforms(mat.uniforms, id);
+
+    const transform = new Transform();
+    transform.copy(t);
+
+    const sg = ShadedGeometry.from(build_geometry_from_cutout_shape(id.cutout), mat);
+
+    // Same as normals viz — opt out of shadow casting/receiving so it
+    // doesn't influence what its neighbours see.
+    sg.depth_material = make_impostor_depth_material(id);
     sg.clearFlag(ShadedGeometryFlags.CastShadow);
     sg.clearFlag(ShadedGeometryFlags.ReceiveShadow);
 
@@ -214,7 +377,38 @@ function make_impostor_entity(id, t = new Transform()) {
         .add(transform)
         .add(sg)
         ;
+}
+
+/**
+ * Lit impostor — applies three.js's STANDARD lighting model and receives
+ * shadow maps in addition to casting them.
+ *
+ * @param {ImpostorDescription} id
+ * @param {Transform} t
+ * @returns {Entity}
+ */
+function make_impostor_lit_entity(id, t = new Transform()) {
+
+    const mat = new ImpostorShaderLitV0();
 
+    write_impostor_definition_to_material_uniforms(mat.uniforms, id);
+
+    const transform = new Transform();
+    transform.copy(t);
+
+    const sg = ShadedGeometry.from(build_geometry_from_cutout_shape(id.cutout), mat);
+
+    sg.depth_material = make_impostor_depth_material(id);
+    // CastShadow + ReceiveShadow on by default. Self-cast works because
+    // both sides (caster via gl_FragDepth, receiver via per-fragment
+    // customShadowCoord computed from the same atlas-derived parallax
+    // surface) agree on where the impostor's surface actually is in
+    // world space.
+
+    return new Entity()
+        .add(transform)
+        .add(sg)
+        ;
 }
 
 new EngineHarness().initialize({

package/src/engine/graphics/impostors/octahedral/shader/ImpostorShaderDepthV0.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Depth-pass companion to ImpostorShaderV0. Use this as
+ * ShadedGeometry.depth_material so the impostor casts a shadow whose
+ * silhouette matches the visible card.
+ */
+export class ImpostorShaderDepthV0 extends RawShaderMaterial {
+    constructor();
+}
+import { RawShaderMaterial } from "three";
+//# sourceMappingURL=ImpostorShaderDepthV0.d.ts.map

package/src/engine/graphics/impostors/octahedral/shader/ImpostorShaderDepthV0.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImpostorShaderDepthV0.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/impostors/octahedral/shader/ImpostorShaderDepthV0.js"],"names":[],"mappings":"AA+VA;;;;GAIG;AACH;IACI,cAoCC;CACJ;kCArYM,OAAO"}

package/src/engine/graphics/impostors/octahedral/shader/ImpostorShaderDepthV0.js

@@ -0,0 +1,395 @@
+import {
+    GLSL3,
+    NoBlending,
+    RawShaderMaterial,
+    Vector3
+} from "three";
+
+// Shadow-pass depth material that matches ImpostorShaderV0's surface so the
+// shadow caster silhouette agrees with what the colour pass draws. We need
+// the full TBN + per-frame xform machinery so that parallax in the fragment
+// reproduces the same UV displacement as V0 — otherwise the alpha discard
+// would cut a different silhouette than the visible card.
+//
+// We DO write gl_FragDepth here. Reason: the caster card orients toward
+// the light (modelViewMatrix in the shadow pass is light_view * model),
+// while the visible card orients toward the camera. The two cards
+// intersect at the bounding-sphere centre plane but diverge — without
+// per-pixel depth the caster's silhouette would be a thin disc at that
+// plane and any visible fragment "below" the centre (in light space)
+// would read as self-shadowed. Projecting the parallaxed surface point
+// through MVP and writing it as gl_FragDepth fixes the silhouette: the
+// shadow map records the actual depth of the impostor surface at each
+// (light_x, light_y), matching what the visible card produces.
+// Cost: this disables early-Z in the shadow pass, but shadow passes are
+// usually fillrate-light and the geometry is just a card.
+//
+// Output is RGBA-packed depth — that's the format three.js's PCFShadowMap
+// reads, and it's what the default MeshDepthMaterial would write here.
+const shader_vx = `
+
+    in vec2 uv;
+    in vec3 position;
+
+    out vec2 vUv;
+    out vec3 vViewPos;
+
+    // Card position and normal in OBJECT space — the fragment shader uses
+    // these to project the parallaxed surface point through MVP for the
+    // gl_FragDepth write. Position interpolates between vertices; the
+    // normal is the same for every card vertex so we mark it flat.
+    out vec3 vCardPos_OS;
+    flat out vec3 vCardNormal_OS;
+
+    flat out vec2 vGridFloor;
+    flat out vec4 vWeights;
+
+    flat out vec3 vTangent;
+    flat out vec3 vBinormal;
+    flat out vec3 vNormal;
+
+    flat out vec4 vFrameXform00;
+    flat out vec4 vFrameXform10;
+    flat out vec4 vFrameXform01;
+    flat out vec4 vFrameXform11;
+
+    uniform mat4 modelViewMatrix;
+    uniform mat4 projectionMatrix;
+
+    uniform vec3 uOffset;
+    uniform float uRadius;
+    uniform float uFrames;
+    uniform bool uIsFullSphere;
+
+    vec2 VecToSphereOct(vec3 pivotToCamera)
+    {
+        vec3 octant = sign(pivotToCamera);
+        float sum = dot(pivotToCamera, octant);
+        vec3 octahedron = pivotToCamera / sum;
+        if (octahedron.y < 0.0) {
+            vec3 absolute = abs(octahedron);
+            octahedron.xz = octant.xz * vec2(1.0 - absolute.z, 1.0 - absolute.x);
+        }
+        return octahedron.xz;
+    }
+
+    vec2 VecToHemiSphereOct(vec3 v)
+    {
+        v.y = max(v.y, 0.001);
+        v = normalize(v);
+        vec3 octant = sign(v);
+        float sum = dot(v, octant);
+        vec3 octahedron = v / sum;
+        return vec2(
+            octahedron.x + octahedron.z,
+            octahedron.z - octahedron.x
+        );
+    }
+
+    vec2 VectorToGrid(vec3 v)
+    {
+        return uIsFullSphere ? VecToSphereOct(v) : VecToHemiSphereOct(v);
+    }
+
+    vec3 OctaSphereDec(vec2 coord)
+    {
+        coord = (coord - 0.5) * 2.0;
+        vec3 p = vec3(coord.x, 0.0, coord.y);
+        vec2 a = abs(p.xz);
+        p.y = 1.0 - a.x - a.y;
+        if (p.y < 0.0) {
+            p.xz = sign(p.xz) * vec2(1.0 - a.y, 1.0 - a.x);
+        }
+        return p;
+    }
+
+    vec3 OctaHemiSphereDec(vec2 coord)
+    {
+        vec3 p = vec3(coord.x - coord.y, 0.0, -1.0 + coord.x + coord.y);
+        vec2 a = abs(p.xz);
+        p.y = 1.0 - a.x - a.y;
+        return p;
+    }
+
+    vec3 GridToVector(vec2 coord)
+    {
+        return uIsFullSphere ? OctaSphereDec(coord) : OctaHemiSphereDec(coord);
+    }
+
+    vec3 FrameToRay(vec2 frame, vec2 framesMinusOne)
+    {
+        vec2 f = clamp(frame / framesMinusOne, 0.0, 1.0);
+        return normalize(GridToVector(f));
+    }
+
+    vec4 ComputeFrameXform(vec3 D_frame, vec3 tangent_OS, vec3 binormal_OS)
+    {
+        vec3 D = abs(D_frame.y) > 0.99999
+                 ? normalize(D_frame + vec3(0.0, 0.0, 0.0001))
+                 : D_frame;
+        vec3 bake_right = normalize(cross(vec3(0.0, 1.0, 0.0), D));
+        vec3 bake_up    = cross(D, bake_right);
+        return vec4(
+            dot(tangent_OS,  bake_right),
+            dot(binormal_OS, bake_right),
+            dot(tangent_OS,  bake_up),
+            dot(binormal_OS, bake_up)
+        );
+    }
+
+    vec4 BilinearWeights(vec2 frac_uv)
+    {
+        vec2 omuv = vec2(1.0) - frac_uv;
+        return vec4(
+            omuv.x * omuv.y,
+            frac_uv.x * omuv.y,
+            omuv.x * frac_uv.y,
+            frac_uv.x * frac_uv.y
+        );
+    }
+
+    void main() {
+        vUv = uv;
+
+        // For shadow casting, modelViewMatrix = light_view * model. The
+        // camera in object space is therefore the LIGHT's position in
+        // object space, so the impostor card naturally orients to face the
+        // light — exactly what we want for a shadow caster.
+        vec3 cameraPos_OS = (inverse(modelViewMatrix) * vec4(0.0, 0.0, 0.0, 1.0)).xyz;
+        // Atlas lookup must be relative to the bounding-sphere centre
+        // (uOffset), since the bake's D_frame is measured from the centre,
+        // not from the object origin. In the shadow pass "camera" is the
+        // light, so this is the direction from the centre to the light.
+        vec3 pivotToCameraRay = normalize(cameraPos_OS - uOffset);
+
+        vec2 framesMinusOne = vec2(uFrames - 1.0);
+        vec2 octahedral_uv = clamp(VectorToGrid(pivotToCameraRay) * 0.5 + 0.5, 0.0, 1.0);
+        vec2 grid = octahedral_uv * framesMinusOne;
+        vec2 gridFloor = min(floor(grid), framesMinusOne - 1.0);
+        vec4 weights = BilinearWeights(grid - gridFloor);
+
+        vGridFloor = gridFloor;
+        vWeights = weights;
+
+        vec3 ray00 = FrameToRay(gridFloor + vec2(0.0, 0.0), framesMinusOne);
+        vec3 ray10 = FrameToRay(gridFloor + vec2(1.0, 0.0), framesMinusOne);
+        vec3 ray01 = FrameToRay(gridFloor + vec2(0.0, 1.0), framesMinusOne);
+        vec3 ray11 = FrameToRay(gridFloor + vec2(1.0, 1.0), framesMinusOne);
+        vec3 projectedRay = normalize(
+            ray00 * weights.x +
+            ray10 * weights.y +
+            ray01 * weights.z +
+            ray11 * weights.w
+        );
+
+        vec3 normal_OS = projectedRay;
+        vec3 up_OS = abs(normal_OS.y) > 0.999
+                     ? vec3(0.0, 0.0, -1.0)
+                     : vec3(0.0, 1.0,  0.0);
+        vec3 tangent_OS  = normalize(cross(up_OS, normal_OS));
+        vec3 binormal_OS = cross(normal_OS, tangent_OS);
+
+        float card_diameter = uRadius * 2.0;
+        vec3 pos_OS = uOffset
+                    + position.x * card_diameter * tangent_OS
+                    + position.y * card_diameter * binormal_OS;
+
+        vCardPos_OS    = pos_OS;
+        vCardNormal_OS = normal_OS;
+
+        vec4 mvPosition = modelViewMatrix * vec4(pos_OS, 1.0);
+        vViewPos = mvPosition.xyz;
+        gl_Position = projectionMatrix * mvPosition;
+
+        mat3 m3 = mat3(modelViewMatrix);
+        vTangent  = normalize(m3 * tangent_OS);
+        vBinormal = normalize(m3 * binormal_OS);
+        vNormal   = normalize(m3 * normal_OS);
+
+        vFrameXform00 = ComputeFrameXform(ray00, tangent_OS, binormal_OS);
+        vFrameXform10 = ComputeFrameXform(ray10, tangent_OS, binormal_OS);
+        vFrameXform01 = ComputeFrameXform(ray01, tangent_OS, binormal_OS);
+        vFrameXform11 = ComputeFrameXform(ray11, tangent_OS, binormal_OS);
+    }
+`;
+const shader_fg = `
+    precision highp float;
+    precision highp int;
+
+    in vec2 vUv;
+    in vec3 vViewPos;
+
+    in vec3 vCardPos_OS;
+    flat in vec3 vCardNormal_OS;
+
+    flat in vec2 vGridFloor;
+    flat in vec4 vWeights;
+
+    flat in vec3 vTangent;
+    flat in vec3 vBinormal;
+    flat in vec3 vNormal;
+
+    flat in vec4 vFrameXform00;
+    flat in vec4 vFrameXform10;
+    flat in vec4 vFrameXform01;
+    flat in vec4 vFrameXform11;
+
+    out vec4 color_out;
+
+    // Needed in the fragment to re-project the parallax-shifted surface
+    // point. three.js's WebGLRenderer sets both unconditionally for any
+    // ShaderMaterial-derived material (RawShaderMaterial included).
+    uniform mat4 modelViewMatrix;
+    uniform mat4 projectionMatrix;
+
+    uniform sampler2D tBase;
+    uniform sampler2D tGeometry;
+    uniform float uFrames;
+    uniform float uRadius;
+    uniform float uDepthScale;
+
+    // Mirrors three.js's packing.glsl chunk so the shadow map reader (PCF
+    // sampler in shadowmap_pars_fragment) can unpack our output.
+    const float PackUpscale = 256.0 / 255.0;
+    const vec3 PackFactors = vec3(256.0 * 256.0 * 256.0, 256.0 * 256.0, 256.0);
+    const float ShiftRight8 = 1.0 / 256.0;
+
+    vec4 packDepthToRGBA(const in float v) {
+        vec4 r = vec4(fract(v * PackFactors), v);
+        r.yzw -= r.xyz * ShiftRight8;
+        return r * PackUpscale;
+    }
+
+    vec2 apply_frame_xform(vec2 card_uv, vec4 xform)
+    {
+        vec2 c = card_uv - 0.5;
+        return vec2(
+            xform.x * c.x + xform.y * c.y,
+            xform.z * c.x + xform.w * c.y
+        ) + 0.5;
+    }
+
+    vec4 blend_4_frames(
+        sampler2D tex, vec2 card_uv,
+        vec2 gridFloor, vec4 w,
+        vec4 x00, vec4 x10, vec4 x01, vec4 x11
+    ) {
+        vec2 frame_size = vec2(1.0 / uFrames);
+        vec2 uv00 = clamp(apply_frame_xform(card_uv, x00), 0.0, 1.0);
+        vec2 uv10 = clamp(apply_frame_xform(card_uv, x10), 0.0, 1.0);
+        vec2 uv01 = clamp(apply_frame_xform(card_uv, x01), 0.0, 1.0);
+        vec2 uv11 = clamp(apply_frame_xform(card_uv, x11), 0.0, 1.0);
+        vec4 s00 = texture(tex, (gridFloor + vec2(0.0, 0.0) + uv00) * frame_size);
+        vec4 s10 = texture(tex, (gridFloor + vec2(1.0, 0.0) + uv10) * frame_size);
+        vec4 s01 = texture(tex, (gridFloor + vec2(0.0, 1.0) + uv01) * frame_size);
+        vec4 s11 = texture(tex, (gridFloor + vec2(1.0, 1.0) + uv11) * frame_size);
+        return s00 * w.x + s10 * w.y + s01 * w.z + s11 * w.w;
+    }
+
+    void main() {
+        // Same parallax shift as V0 so the silhouette we test matches the
+        // visible silhouette — otherwise the shadow would clip a slightly
+        // different cutout than the colour pass.
+        vec3 view_dir_view = normalize(-vViewPos);
+        vec3 view_dir = vec3(
+            dot(vTangent,  view_dir_view),
+            dot(vBinormal, view_dir_view),
+            dot(vNormal,   view_dir_view)
+        );
+
+        vec2 base_uv = vUv;
+        float depth = blend_4_frames(
+            tGeometry, base_uv,
+            vGridFloor, vWeights,
+            vFrameXform00, vFrameXform10, vFrameXform01, vFrameXform11
+        ).a;
+        base_uv += (view_dir.xy / view_dir.z) * (depth - 0.5) * uDepthScale;
+        base_uv = clamp(base_uv, 0.0, 1.0);
+
+        vec4 texel_color = blend_4_frames(
+            tBase, base_uv,
+            vGridFloor, vWeights,
+            vFrameXform00, vFrameXform10, vFrameXform01, vFrameXform11
+        );
+
+        if (texel_color.a <= 0.5) {
+            discard;
+        }
+
+        // Re-sample depth at the parallax-shifted UV. We want the surface
+        // depth at the post-parallax location, not the un-shifted one.
+        // For a single-step parallax these usually round-trip to a
+        // similar value, but the second sample keeps us self-consistent
+        // when the parallax shift is non-trivial.
+        float surface_depth = blend_4_frames(
+            tGeometry, base_uv,
+            vGridFloor, vWeights,
+            vFrameXform00, vFrameXform10, vFrameXform01, vFrameXform11
+        ).a;
+
+        // Convention from BakeShaderStandard: depth=1 at the bounding
+        // sphere's near plane (front, +radius along bake camera), 0.5 at
+        // the centre (= the card plane), 0 at the far plane (-radius).
+        // So (depth - 0.5) is the signed height along the card normal in
+        // half-bounding-sphere units; multiply by 2*radius to get
+        // object-space height.
+        float height_OS = (surface_depth - 0.5) * 2.0 * uRadius;
+
+        vec3 surface_OS = vCardPos_OS + height_OS * vCardNormal_OS;
+        vec4 surface_clip = projectionMatrix * modelViewMatrix * vec4(surface_OS, 1.0);
+        float surface_ndc_z = surface_clip.z / surface_clip.w;
+
+        // gl_FragCoord.z / gl_FragDepth are in [0, 1] (assuming default
+        // depth range). Map NDC z (-1..+1) to that range, then clamp so
+        // out-of-frustum surface points don't write garbage into the
+        // shadow map.
+        gl_FragDepth = clamp(surface_ndc_z * 0.5 + 0.5, 0.0, 1.0);
+
+        color_out = packDepthToRGBA(gl_FragDepth);
+    }
+`;
+
+/**
+ * Depth-pass companion to ImpostorShaderV0. Use this as
+ * ShadedGeometry.depth_material so the impostor casts a shadow whose
+ * silhouette matches the visible card.
+ */
+export class ImpostorShaderDepthV0 extends RawShaderMaterial {
+    constructor() {
+        super({
+            fragmentShader: shader_fg,
+            vertexShader: shader_vx,
+            uniforms: {
+                tBase: {
+                    value: null
+                },
+                tGeometry: {
+                    value: null
+                },
+                tMaterial: {
+                    value: null
+                },
+                uFrames: {
+                    value: 0
+                },
+                uRadius: {
+                    value: 0
+                },
+                uOffset: {
+                    value: new Vector3(0, 0, 0)
+                },
+                uIsFullSphere: {
+                    value: false
+                },
+                uDepthScale: {
+                    value: 0.5
+                }
+            },
+            glslVersion: GLSL3
+        });
+
+        // Shadow pass writes a single RGBA depth value per fragment — no
+        // need for blending.
+        this.blending = NoBlending;
+    }
+}