reze-engine 0.55.0 → 0.55.2

package/dist/engine.js

@@ -675,6 +675,13 @@ export class Engine {
         this.lightCount = 0;
         this.resizeObserver = null;
         this.resizePending = false;
+        /** The soft-edge variant, built the first time a scene asks for one. Null while
+         *  no scene has, which is most of them — a pipeline nobody draws with is still
+         *  a shader compile at load. */
+        this.groundShadowSoftPipeline = null;
+        /** How the ground's own pipeline is chosen, kept beside the uniform that sets
+         *  it so the draw does not have to read the buffer back. */
+        this.groundSoft = false;
         this.selectedMaterial = null;
         this.overlayInstanceBuffer = null;
         this.overlayInstanceCapacity = 0;
@@ -1053,6 +1060,8 @@ export class Engine {
             contrast: DEFAULT_COLOR_GRADING.contrast,
             saturation: DEFAULT_COLOR_GRADING.saturation,
         };
+        /** Sensor grain: how much, and whether it moves. */
+        this.grain = { amount: 0, animated: true };
         /** Debug/diagnostic: skip every inverted-hull outline draw. */
         // OFF by default — the product aesthetic. Modern high-detail models read
         // better without hulls (babylon-mmd's own demos disable its outline renderer
@@ -1065,6 +1074,17 @@ export class Engine {
         /** When set, render resolution is pinned to this size instead of tracking the
          *  canvas's CSS size × devicePixelRatio (see setRenderSize). */
         this.fixedRenderSize = null;
+        // ── VMD camera track ──
+        // A dedicated camera VMD (target / rotation / distance / fov animated). Motion VMDs loaded
+        // via model.loadVmd never touch the camera — the camera shot is opt-in through here.
+        /** Whether a loaded camera track is allowed to drive (setCameraVmdEnabled).
+         *  Held separately from `camera.vmdDriven` because that flag now answers to
+         *  two sources, and a track switched off must stay off when the other one
+         *  releases the camera. */
+        this.cameraVmdEnabled = true;
+        /** A pose pushed in from outside — see setCameraPose. Reapplied every frame,
+         *  so it outranks the orbit AND a loaded track for as long as it is set. */
+        this.cameraPoseOverride = null;
         /** Per cascade: does its map currently hold nothing but the cleared far plane?
          *  Set by the cascade loop, which skips a cascade that is unwanted and already
          *  cleared rather than re-clearing it every frame. */
@@ -1400,6 +1420,30 @@ export class Engine {
             saturation: g.saturation,
         };
     }
+    /**
+     * Film grain over the rendered scene, 0–1.
+     *
+     * A property of a SENSOR, so it belongs to the camera rather than to any one
+     * subject, and it lands on what the engine drew and on nothing else — never on
+     * a background image or a backdrop video, which arrived with grain of their
+     * own and would be graded rather than matched by a second helping.
+     *
+     * `animated` false freezes it. A still photograph's grain does not move, and
+     * noise crawling over a frozen picture makes the rendering look more alive
+     * than the thing it is standing in.
+     *
+     * Costs one hash per pixel in a pass that already runs, and nothing at all at
+     * zero — the branch is on a uniform.
+     */
+    setFilmGrain(amount, animated = true) {
+        this.grain.amount = Math.min(Math.max(amount, 0), 1);
+        this.grain.animated = animated;
+        if (this.device && this.compositeUniformBuffer)
+            this.writeCompositeViewUniforms();
+    }
+    getFilmGrain() {
+        return this.grain;
+    }
     setViewTransformOptions(patch) {
         const v = this.viewTransform;
         if (patch.exposure !== undefined)
@@ -1442,8 +1486,11 @@ export class Engine {
         // compiler doesn't fold `pow(x, 1/g)` into identity when g=1, so also emit
         // a uniform branch that skips the pow entirely in the common case.
         u[1] = 1.0 / Math.max(v.gamma, 1e-4);
-        u[2] = 0.0;
-        u[3] = 0.0;
+        u[2] = this.grain.amount;
+        // The seed. Zero means STILL: a plate that is one photograph has grain that
+        // does not move, and CG noise crawling over a frozen picture makes the CG
+        // look more alive than the footage — the opposite of the point.
+        u[3] = this.grain.animated ? Math.floor(this.sceneClock * 24) % 1024 : 0;
         u[4] = b.color.x;
         u[5] = b.color.y;
         u[6] = b.color.z;
@@ -4878,14 +4925,9 @@ export class Engine {
                 { binding: 12, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
             ],
         });
-        const groundShadowShader = this.device.createShaderModule({
-            label: "ground shadow",
-            code: groundShaderWgsl(),
-        });
-        this.groundShadowPipeline = this.createRenderPipeline({
+        this.groundShadowPipelineDesc = {
             label: "ground shadow pipeline",
             layout: this.device.createPipelineLayout({ bindGroupLayouts: [this.groundShadowBindGroupLayout] }),
-            shaderModule: groundShadowShader,
             // Slot 0 only — the ground has no skinning, and declaring the full
             // 3-slot layout while renderGround binds one buffer is a WebGPU
             // validation error that invalidates the whole command buffer.
@@ -4893,7 +4935,8 @@ export class Engine {
             fragmentTargets: sceneTargetsFor("ground", this.sceneFormats),
             cullMode: "back",
             depthStencil: { format: this.depthFormat, depthWriteEnabled: true, depthCompare: this.depthAhead },
-        });
+        };
+        this.groundShadowPipeline = this.buildGroundPipeline(false);
         // Outline: group 0 = per-frame (camera), group 1 = per-instance (skinMats), group 2 = per-material (edge uniforms)
         this.outlinePerFrameBindGroupLayout = this.device.createBindGroupLayout({
             label: "outline per-frame bind group layout",
@@ -6323,21 +6366,60 @@ export class Engine {
         this.cameraFollowSmoothing = Math.max(0, smoothing ?? 0);
         this.cameraFollowSeeded = false;
     }
-    // ── VMD camera track ──
-    // A dedicated camera VMD (target / rotation / distance / fov animated). Motion VMDs loaded
-    // via model.loadVmd never touch the camera — the camera shot is opt-in through here.
+    /** The one place that decides who is holding the camera. An external pose
+     *  wins; a track drives when it is loaded and enabled; otherwise orbit. */
+    refreshCameraDrive() {
+        this.camera.setVmdDriven(this.cameraPoseOverride !== null || (this.cameraVmdEnabled && this.cameraAnimation !== null));
+    }
+    /**
+     * Aim the camera from outside — a solved match-move, a saved shot, a rig
+     * driving the view from the host's own clock.
+     *
+     * The exact partner of `getCameraPose`, and the same five channels: the shot
+     * as MMD states it, roll included. Orbit cannot express roll, so this is the
+     * only way a tilted camera reaches the engine.
+     *
+     * Reapplied every frame while set, which makes it authoritative rather than
+     * advisory — nothing the transport or a loaded track does moves it. Pass null
+     * to release, and whatever was driving before takes the camera back.
+     */
+    setCameraPose(pose) {
+        if (pose) {
+            // Copied, not held: a host reusing one object per frame is the normal
+            // shape of a track, and storing the reference would make the value we
+            // reapply depend on when the caller next touched theirs.
+            this.cameraPoseOverride = {
+                target: new Vec3(pose.target.x, pose.target.y, pose.target.z),
+                rotation: new Vec3(pose.rotation.x, pose.rotation.y, pose.rotation.z),
+                distance: pose.distance,
+                fov: pose.fov,
+            };
+        }
+        else {
+            this.cameraPoseOverride = null;
+        }
+        this.refreshCameraDrive();
+        if (this.cameraPoseOverride)
+            this.camera.setVmdPose(this.cameraPoseOverride);
+    }
+    /** The pose currently forced from outside, or null when nothing is. */
+    getCameraPoseOverride() {
+        return this.cameraPoseOverride;
+    }
     /** Load a camera VMD (dedicated camera file, or any VMD's camera block) and drive the shot
      *  from it. Default-on once a non-empty track loads; toggle with setCameraVmdEnabled. */
     async loadCameraVmd(url) {
         const frames = await VMDLoader.loadCamera(url);
         this.cameraAnimation = frames.length ? new CameraAnimation(frames) : null;
-        this.camera.setVmdDriven(this.cameraAnimation !== null);
+        this.cameraVmdEnabled = true;
+        this.refreshCameraDrive();
     }
     /** Load a camera VMD from an already-fetched buffer (e.g. a File the user dropped). */
     loadCameraVmdFromBuffer(buffer) {
         const frames = VMDLoader.loadCameraFromBuffer(buffer);
         this.cameraAnimation = frames.length ? new CameraAnimation(frames) : null;
-        this.camera.setVmdDriven(this.cameraAnimation !== null);
+        this.cameraVmdEnabled = true;
+        this.refreshCameraDrive();
     }
     /**
      * Drive the shot from camera keyframes built in JS — the camera's answer to
@@ -6354,7 +6436,8 @@ export class Engine {
      */
     loadCameraClip(frames) {
         this.cameraAnimation = frames.length ? new CameraAnimation([...frames]) : null;
-        this.camera.setVmdDriven(this.cameraAnimation !== null);
+        this.cameraVmdEnabled = true;
+        this.refreshCameraDrive();
     }
     /** The loaded camera track as editable keyframes, or [] with none loaded.
      *  Copies — mutating them does not reach the track being sampled. */
@@ -6372,7 +6455,8 @@ export class Engine {
     }
     /** Turn the loaded camera VMD on/off (falls back to orbit when off). No-op if none loaded. */
     setCameraVmdEnabled(enabled) {
-        this.camera.setVmdDriven(enabled && this.cameraAnimation !== null);
+        this.cameraVmdEnabled = enabled;
+        this.refreshCameraDrive();
         if (!enabled && this.cameraTargetModel) {
             // Follow resumes with a clean snap to bone + configured offset — one
             // predictable cut to the scene's framing, no easing from the shot.
@@ -6630,7 +6714,7 @@ export class Engine {
     /** Drop the loaded camera VMD and return to orbit control. */
     clearCameraVmd() {
         this.cameraAnimation = null;
-        this.camera.setVmdDriven(false);
+        this.refreshCameraDrive();
     }
     /**
      * THE TRANSPORT'S CLOCK — where the scene is in its own playback.
@@ -6673,6 +6757,28 @@ export class Engine {
     getCameraPosition() {
         return this.camera.getPosition();
     }
+    /**
+     * The live orbit, read in ONE call.
+     *
+     * A host that stores the shot has to be able to ask where the camera actually
+     * IS, because a drag on the canvas moves this and nothing else — and a
+     * document that never asks will happily write back the angle it last set,
+     * discarding whatever the person just did with the mouse. Reading the four
+     * separately invites a torn set across a frame boundary; this cannot tear.
+     *
+     * `target` is the orbit's own centre. While the engine is following a bone
+     * that point rides the bone, so a caller storing a FOLLOW offset must keep its
+     * own and take only the angles from here.
+     */
+    getCameraOrbit() {
+        const c = this.camera;
+        return {
+            alpha: c.alpha,
+            beta: c.beta,
+            distance: c.radius,
+            target: new Vec3(c.target.x, c.target.y, c.target.z),
+        };
+    }
     getCameraDistance() {
         return this.camera.radius;
     }
@@ -6691,6 +6797,21 @@ export class Engine {
     setCameraBeta(b) {
         this.camera.beta = b;
     }
+    /**
+     * Roll the orbiting shot, radians — the lean alpha and beta cannot state.
+     *
+     * Tips the up vector about the eye→target line, so the camera stays exactly
+     * where it was and keeps looking at exactly what it looked at. Everything the
+     * orbit does still works underneath it: following a bone, dragging, zooming.
+     *
+     * A camera VMD carries its own roll and ignores this while it drives.
+     */
+    setCameraRoll(r) {
+        this.camera.roll = r;
+    }
+    getCameraRoll() {
+        return this.camera.roll;
+    }
     /** Vertical field of view in radians (default π/4). While a camera VMD
      *  drives the view it animates fov itself; the orbit value set here is
      *  restored when the VMD releases the camera. */
@@ -6822,6 +6943,7 @@ export class Engine {
             opacity: 1.0,
             mirror: false,
             mirrorBlur: 0,
+            shadowSoftness: 0,
             ...options,
         };
         this.createGroundGeometry(opts.width, opts.height);
@@ -9014,8 +9136,25 @@ export class Engine {
         });
         this.device.queue.writeBuffer(this.groundIndexBuffer, 0, indices);
     }
+    buildGroundPipeline(soft) {
+        return this.createRenderPipeline({
+            ...this.groundShadowPipelineDesc,
+            label: soft ? "ground shadow pipeline (soft)" : "ground shadow pipeline",
+            shaderModule: this.device.createShaderModule({
+                label: soft ? "ground shadow (soft)" : "ground shadow",
+                code: groundShaderWgsl(soft),
+            }),
+        });
+    }
+    /** Built on the first frame that actually needs it. A shader compile costs
+     *  load time, and the overwhelming majority of scenes never soften a shadow. */
+    ensureGroundSoftPipeline() {
+        if (!this.groundShadowSoftPipeline)
+            this.groundShadowSoftPipeline = this.buildGroundPipeline(true);
+        return this.groundShadowSoftPipeline;
+    }
     createShadowGroundResources(opts) {
-        const { diffuseColor, fadeStart, fadeEnd, shadowStrength, gridSpacing, gridLineWidth, gridLineOpacity, gridLineColor, noiseStrength, opacity, mirror, mirrorBlur, } = opts;
+        const { diffuseColor, fadeStart, fadeEnd, shadowStrength, gridSpacing, gridLineWidth, gridLineOpacity, gridLineColor, noiseStrength, opacity, mirror, mirrorBlur, shadowSoftness, } = opts;
         // Shadow map is already created in setupPipelines()
         // 20 floats: 16 for the original block, then (mirrorBlur, pad, pad, pad)
         // keeping the uniform vec4-aligned.
@@ -9040,6 +9179,12 @@ export class Engine {
         this.groundMirror = gb[15];
         gb[16] = Math.min(Math.max(mirrorBlur, 0), 1);
         this.groundMirrorBlur = gb[16];
+        // gb[18] — shadow edge softness. Was padding; the shader reads it as the
+        // Vogel disk's radius, and 0 takes the sharp nine-tap path unchanged.
+        gb[18] = Math.min(Math.max(shadowSoftness, 0), 1);
+        // Which variant the draw picks. Zero is the sharp shader, which is the one
+        // that existed before softness did.
+        this.groundSoft = gb[18] > 0;
         // gb[17] — does the FAR cascade hold anything?
         //
         // It holds something only when a stage is loaded; that is what it exists for
@@ -9677,7 +9822,7 @@ export class Engine {
             return;
         if (!this.hasGround || !this.groundVertexBuffer || !this.groundIndexBuffer || !this.groundDrawCall)
             return;
-        pass.setPipeline(this.groundShadowPipeline);
+        pass.setPipeline(this.groundSoft ? this.ensureGroundSoftPipeline() : this.groundShadowPipeline);
         pass.setVertexBuffer(0, this.groundVertexBuffer);
         pass.setIndexBuffer(this.groundIndexBuffer, "uint16");
         pass.setBindGroup(0, this.groundDrawCall.bindGroup);
@@ -10200,15 +10345,65 @@ export class Engine {
         return new Vec3(x / w, y / w, z / w);
     }
     // World-space ray from camera through a canvas pixel. Uses WebGPU's NDC z ∈ [0,1].
+    /**
+     * Where a point on the canvas lands on a horizontal plane.
+     *
+     * `px,py` are canvas-relative pixels, top-left origin — what a pointer event
+     * gives you after subtracting the element's rect. Returns null when the ray
+     * cannot reach the plane: parallel to it, or pointing the other way, which is
+     * what a click on the sky above the horizon is.
+     *
+     * The one primitive a placement UI needs. Dragging a thing across the floor is
+     * otherwise three sliders in world units, which asks someone to guess numbers
+     * that have no visible relation to the picture they are looking at — and it
+     * throws away the property that makes pointing work at all: under perspective,
+     * moving something further away makes it smaller by exactly the right amount,
+     * so position and size stop being two controls to tune against each other.
+     */
+    groundPointAt(px, py, planeY = 0) {
+        const ray = this.buildMouseRay(px, py);
+        if (!ray)
+            return null;
+        // Parallel to the plane: no intersection, and a huge one is not an answer.
+        if (Math.abs(ray.dir.y) < 1e-6)
+            return null;
+        const t = (planeY - ray.origin.y) / ray.dir.y;
+        // Behind the camera — the plane is there, but not in this shot.
+        if (!(t > 0) || !isFinite(t))
+            return null;
+        return new Vec3(ray.origin.x + ray.dir.x * t, planeY, ray.origin.z + ray.dir.z * t);
+    }
+    /** Hand the pointer to something else — a placement drag, a gizmo, a host's own
+     *  overlay — so the orbit does not also act on it. */
+    setCameraInputLocked(locked) {
+        this.camera?.setInputLocked(locked);
+    }
     buildMouseRay(px, py) {
         if (!this.camera)
             return null;
         const width = this.canvas.clientWidth;
         const height = this.canvas.clientHeight;
-        if (width <= 0 || height <= 0)
+        if (width <= 0 || height <= 0 || this.canvas.width <= 0 || this.canvas.height <= 0)
             return null;
-        const ndcX = (px / width) * 2 - 1;
-        const ndcY = -((py / height) * 2 - 1);
+        // THE PICTURE, NOT THE ELEMENT.
+        //
+        // The projection's aspect comes from the DRAWING BUFFER, while a pointer
+        // arrives in the CSS box — and the two do not have to agree. The canvas is
+        // laid out `object-contain`, so whenever they differ the rendered image sits
+        // letterboxed inside the element with bars either side of it, and dividing
+        // by the element's own size lands the ray somewhere the picture is not.
+        // They disagree on every resize until the observer catches up, and
+        // permanently wherever a host frames the canvas to a shape of its own.
+        //
+        // So: work out where the image actually sits, and take the ray from that.
+        const bufAspect = this.canvas.width / this.canvas.height;
+        const boxAspect = width / height;
+        const imgW = bufAspect > boxAspect ? width : height * bufAspect;
+        const imgH = bufAspect > boxAspect ? width / bufAspect : height;
+        const ox = (width - imgW) / 2;
+        const oy = (height - imgH) / 2;
+        const ndcX = ((px - ox) / imgW) * 2 - 1;
+        const ndcY = -(((py - oy) / imgH) * 2 - 1);
         const view = this.camera.getViewMatrix();
         const proj = this.camera.getProjectionMatrix();
         const invVP = proj.multiply(view).inverse();
@@ -10491,8 +10686,14 @@ export class Engine {
                 }
             }
         }
-        // Drive the shot from the camera VMD (synced to the animated model's clock).
-        if (this.camera.vmdDriven && this.cameraAnimation) {
+        // Who holds the shot this frame. An external pose is a statement about
+        // where the camera IS, so it is reapplied rather than sampled — and it
+        // outranks a loaded track, which is scene data.
+        if (this.cameraPoseOverride) {
+            this.camera.setVmdPose(this.cameraPoseOverride);
+        }
+        else if (this.camera.vmdDriven && this.cameraAnimation) {
+            // Drive the shot from the camera VMD (synced to the animated model's clock).
             const pose = this.cameraAnimation.sample(this.transportTime());
             if (pose)
                 this.camera.setVmdPose(pose);
@@ -11724,6 +11925,12 @@ export class Engine {
             // clock is already per effect, which is the one that actually breaks
             // things (rzGridFrame()==0 is a grid's only chance to seed).
             u[24] = this.sceneClock - (this.effects[0]?.epochScene ?? 0);
+            // The grain's seed rides the same per-frame refresh, because it is the
+            // only thing that makes it move — a seed written once by its setter is a
+            // still pattern welded to the picture. On the SCENE clock like everything
+            // else here, so an export reproduces the editor exactly rather than
+            // scattering differently at whatever rate the encoder ran.
+            u[3] = this.grain.animated ? Math.floor((this.sceneClock * 24) % 1024) : 0;
             u[26] = this.canvas.width;
             u[27] = this.canvas.height;
             // Camera world position (viewU[10]) — the other half of bgWorldPos. It

package/dist/shaders/passes/composite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/composite.ts"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+BAgC+B;AAC/B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAAE,CAIhG;AAID,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAEzG,KAAK,qBAAqB,GAAG;IAC3B,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,aAAa,EAAE,OAAO,CAAA;IACtB,oEAAoE;IACpE,aAAa,EAAE,OAAO,CAAA;IACtB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAA;IAChB;mFAC+E;IAC/E,GAAG,CAAC,EAAE,OAAO,CAAA;IACb;;;yEAGqE;IACrE,UAAU,EAAE,MAAM,CAAA;IAClB;;8EAE0E;IAC1E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB,CAAA;AA6LD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,yqaA+H5B,CAAA;AA4LD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,IAAI,GAAG,MAAM,CAQlF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAiFtE;AAED,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,QAA6B,CAAA"}
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/composite.ts"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+BAgC+B;AAC/B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAAE,CAIhG;AAID,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAEzG,KAAK,qBAAqB,GAAG;IAC3B,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,aAAa,EAAE,OAAO,CAAA;IACtB,oEAAoE;IACpE,aAAa,EAAE,OAAO,CAAA;IACtB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAA;IAChB;mFAC+E;IAC/E,GAAG,CAAC,EAAE,OAAO,CAAA;IACb;;;yEAGqE;IACrE,UAAU,EAAE,MAAM,CAAA;IAClB;;8EAE0E;IAC1E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB,CAAA;AA6LD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,yqaA+H5B,CAAA;AA6MD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,IAAI,GAAG,MAAM,CAQlF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAiFtE;AAED,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,QAA6B,CAAA"}

package/dist/shaders/passes/composite.js

@@ -109,7 +109,7 @@ override APPLY_GAMMA: bool = true;
 // monotone-cubic (Fritsch–Carlson) fit through the same 14 anchors — same values, C1
 // continuity kills the banding — sampled with hardware linear filtering.
 @group(0) @binding(5) var filmicLut: texture_2d<f32>;
-// viewU[0] = (exposure, invGamma, _, _);  viewU[1] = (tint.rgb, intensity)
+// viewU[0] = (exposure, invGamma, grain amount, grain seed);  viewU[1] = (tint.rgb, intensity)
 // viewU[2] = (background.rgb, mode) — display-space sRGB, composited UNDER the
 //            scene post-tonemap. BASE-layer mode: 0 transparent (DOM shows),
 //            1 solid color, 2 = 360 equirect skybox sampled by view ray. A user
@@ -495,6 +495,23 @@ const COMPOSITE_BODY = /* wgsl */ `
   if (APPLY_GAMMA) {
     disp = pow(disp, vec3f(viewU[0].y));
   }
+  // ── Film grain, on the SCENE ONLY ─────────────────────────────────────────
+  //
+  // Applied here, before the background is composited under, so it rides on what
+  // the engine drew and nothing else. That placement is the whole point when the
+  // background is footage: the plate came off a real sensor and already carries
+  // its own grain, and a second helping over the top would grade the photograph
+  // rather than match it. A clean CG figure on a grainy plate is one of the
+  // loudest tells there is — the noise gives it away long before the geometry.
+  //
+  // Multiplicative and weighted toward the mid-tones, which is how film behaves:
+  // little grain in the blacks, and the highlights clip it off.
+  if (viewU[0].z > 0.0) {
+    let gp = fragCoord.xy + vec2f(viewU[0].w, viewU[0].w * 1.7);
+    let gn = fract(sin(dot(gp, vec2f(12.9898, 78.233))) * 43758.5453) - 0.5;
+    let glum = dot(disp, vec3f(0.2126, 0.7152, 0.0722));
+    disp = max(disp * (1.0 + gn * viewU[0].z * 4.0 * glum * (1.0 - glum)), vec3f(0.0));
+  }
   // Composite over the background in display space (premultiplied out). The
   // background is TWO layers: a base (transparent / solid color / 360 equirect)
   // and an optional user WGSL effect over-composited onto it.

package/dist/shaders/passes/ground.d.ts

@@ -1,4 +1,8 @@
-export declare function groundShaderWgsl(): string;
+/**
+ * The ground's shader. `soft` selects the shadow-edge variant — see pcfWgsl for
+ * why this is a compiled flag and not a uniform the shader branches on.
+ */
+export declare function groundShaderWgsl(soft?: boolean): string;
 /**
  * The ground belongs to no model instance, so it takes ids of its own — at the
  * TOP of the u16 range, not at the bottom.

package/dist/shaders/passes/ground.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ground.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/ground.ts"],"names":[],"mappings":"AAYA,wBAAgB,gBAAgB,IAAI,MAAM,CAkUzC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAA;AACxC,eAAO,MAAM,gBAAgB,QAAS,CAAA;AAEtC;;;oEAGoE;AACpE,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAErC;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,+oCAiClC,CAAA"}
+{"version":3,"file":"ground.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/ground.ts"],"names":[],"mappings":"AAgFA;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,UAAQ,GAAG,MAAM,CA+TrD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAA;AACxC,eAAO,MAAM,gBAAgB,QAAS,CAAA;AAEtC;;;oEAGoE;AACpE,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAErC;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,+oCAiClC,CAAA"}

package/dist/shaders/passes/ground.js

@@ -8,7 +8,77 @@ import { WORLD_AMBIENT_WGSL } from "../lights";
 // A FUNCTION, not a constant, since the id attachment is a device capability:
 // the struct this returns depends on what the probe at init found, and a string
 // baked at import time cannot know that. Called once, when the module is built.
-export function groundShaderWgsl() {
+// How far the softest setting spreads the taps, in units of the sharp kernel's
+// own step, and how many taps carry that spread. Sixteen is what keeps a wide
+// disk reading as a penumbra instead of sixteen shadows.
+const SOFT_TAPS = 16;
+const SOFT_MAX_SPREAD = 14;
+/**
+ * PCF taps for one cascade, emitted per shadow map.
+ *
+ * At softness 0 this is the 3x3 box the ground has always used — same offsets,
+ * same weights, same result to the bit. Above it the taps spread over a Vogel
+ * disk whose radius IS the penumbra: an overcast sky throws no edge, and a
+ * razor-edged shadow under one is the loudest thing wrong in a composite.
+ *
+ * The branch is on a uniform, so a scene at softness 0 genuinely takes the
+ * nine-tap side rather than masking the wide one — the same reasoning the
+ * shadowStrength branch above it already documents.
+ *
+ * A string rather than a WGSL function because a texture is the one handle type
+ * this shader has never passed as a parameter, and the file is already a
+ * template that interpolates its constants.
+ *
+ * `acc` must already be declared and zeroed; the caller reads it back
+ * normalised, so there is no `/ 9.0` left at the call site.
+ */
+function pcfWgsl(map, uv, texel, z, acc, pad, soft) {
+    const golden = 2.39996323;
+    // ONE BRANCH IS COMPILED, NOT BOTH.
+    //
+    // A runtime `if` on the softness uniform was the first cut, and it costs a
+    // scene that never softens a shadow. Both bodies land in the module, the wide
+    // one needs more live registers than the narrow one, and occupancy on this
+    // draw is set by the worst of them — so the frame gets slower whether or not
+    // the branch is ever taken. That is expensive HERE in particular: this file
+    // already records that the ground is a full-coverage draw costing tens of
+    // millions of shadow fetches, and that bisection on a slow device pinned the
+    // whole cost to it.
+    //
+    // So the flag is the COMPILED VARIANT, which is the idiom the composite pass
+    // already uses for its effects. A scene at softness 0 gets byte-for-byte the
+    // shader it had before any of this existed, and cannot pay for a feature it
+    // is not using.
+    const sharp = [
+        `let st = ${texel} * 2.0;`,
+        `for (var y = -1; y <= 1; y++) {`,
+        `  for (var x = -1; x <= 1; x++) {`,
+        // ...Level, not the implicit-derivative form: identical on a single-mip
+        // shadow map, and legal inside a branch.
+        `    ${acc} += textureSampleCompareLevel(${map}, shadowSampler, ${uv} + vec2f(f32(x), f32(y)) * st, ${z});`,
+        `  }`,
+        `}`,
+        `${acc} *= ${1 / 9};`,
+    ];
+    const wide = [
+        `let radius = ${texel} * 2.0 * (1.0 + material.shadowSoftness * ${SOFT_MAX_SPREAD}.0);`,
+        `for (var s = 0; s < ${SOFT_TAPS}; s++) {`,
+        `  let fs = f32(s);`,
+        // sqrt of the index spaces the ring radii evenly by AREA; the golden angle
+        // keeps successive taps from lining up into spokes.
+        `  let r = sqrt((fs + 0.5) * ${1 / SOFT_TAPS});`,
+        `  let a = fs * ${golden} + rot;`,
+        `  ${acc} += textureSampleCompareLevel(${map}, shadowSampler, ${uv} + vec2f(cos(a), sin(a)) * (r * radius), ${z});`,
+        `}`,
+        `${acc} *= ${1 / SOFT_TAPS};`,
+    ];
+    return (soft ? wide : sharp).map((l) => pad + l).join("\n");
+}
+/**
+ * The ground's shader. `soft` selects the shadow-edge variant — see pcfWgsl for
+ * why this is a compiled flag and not a uniform the shader branches on.
+ */
+export function groundShaderWgsl(soft = false) {
     return /* wgsl */ `
 struct CameraUniforms { view: mat4x4f, projection: mat4x4f, viewPos: vec3f, _p: f32, };
 struct Light { direction: vec4f, color: vec4f, };
@@ -20,7 +90,7 @@ struct GroundShadowMat {
   gridLineColor: vec3f, mirror: f32,
   // farCascade: 1 while a stage is loaded, 0 otherwise. See the branch below —
   // with no stage the far map is never drawn into, so its taps are known.
-  mirrorBlur: f32, farCascade: f32, _mb1: f32, _mb2: f32,
+  mirrorBlur: f32, farCascade: f32, shadowSoftness: f32, _mb2: f32,
   // Every shadow caster in one sphere, refreshed per frame. w = radius; 0 means
   // nothing casts, negative means "do not use this" (a rigid caster has no
   // sphere, so a scene with a stage keeps the taps). See rzShadowPossible.
@@ -150,6 +220,13 @@ ${sceneFsOutWgsl()}@fragment fn fs(i: VO) -> FSOut {
   // The same reasoning the noise tint below already got, applied to the term
   // that costs a hundred times more.
   if (material.shadowStrength > 0.0 && shadowPossible) {
+${soft
+        ? `  // Per-pixel rotation for the soft disk, so its rings break up into fine
+  // noise rather than banding. Interleaved gradient noise: a function of the
+  // pixel alone, so a still camera gives a still shadow.
+  let ign = fract(52.9829189 * fract(dot(i.position.xy, vec2f(0.06711056, 0.00583715))));
+  let rot = ign * 6.28318530718;`
+        : ""}
   // The far cascade's taps, skipped entirely when nothing ever drew into it.
   //
   // This branch is the expensive one on a wide floor: it runs wherever the NEAR
@@ -163,32 +240,20 @@ ${sceneFsOutWgsl()}@fragment fn fs(i: VO) -> FSOut {
   if (material.farCascade > 0.0 && frustum < 1.0 && frustum1 > 0.0) {
     let suv1 = vec2f(ndc1.x * 0.5 + 0.5, 0.5 - ndc1.y * 0.5);
     let suv1_c = clamp(suv1, vec2f(0.02), vec2f(0.98));
-    let st1 = ${1 / SHADOW_CASCADES[SHADOW_CASCADES.length - 1].mapSize} * 2.0;
     let compareZ1 = ndc1.z - 0.0035;
     var acc1 = 0.0;
-    for (var y = -1; y <= 1; y++) {
-      for (var x = -1; x <= 1; x++) {
-        acc1 += textureSampleCompareLevel(shadowMapFar, shadowSampler, suv1_c + vec2f(f32(x), f32(y)) * st1, compareZ1);
-      }
-    }
-    vis = mix(1.0, acc1 * (1.0 / 9.0), frustum1);
+${pcfWgsl("shadowMapFar", "suv1_c", `${1 / SHADOW_CASCADES[SHADOW_CASCADES.length - 1].mapSize}`, "compareZ1", "acc1", "    ", soft)}
+    vis = mix(1.0, acc1, frustum1);
   }
   if (frustum > 0.0) {
     let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
     let suv_c = clamp(suv, vec2f(0.02), vec2f(0.98));
-    let st = material.pcfTexel * 2.0;
     let compareZ = ndc.z - 0.0035;
     var acc = 0.0;
-    for (var y = -1; y <= 1; y++) {
-      for (var x = -1; x <= 1; x++) {
-        // ...Level, not the implicit-derivative form: identical on a single-mip
-        // shadow map, and legal inside this branch.
-        acc += textureSampleCompareLevel(shadowMap, shadowSampler, suv_c + vec2f(f32(x), f32(y)) * st, compareZ);
-      }
-    }
+${pcfWgsl("shadowMap", "suv_c", "material.pcfTexel", "compareZ", "acc", "    ", soft)}
     // The base is whatever the far cascade decided, so the near border blends
     // cascade to cascade rather than snapping to lit mid-floor.
-    vis = mix(vis, acc * (1.0 / 9.0), frustum);
+    vis = mix(vis, acc, frustum);
   }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.55.0",
+  "version": "0.55.2",
   "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",