feat(gsplat): apply vertex-modify to hybrid cast shadows

The hybrid (GPU-sort) gsplat shadow renderer draws per-light shadow casters
with their own ShaderMaterials, which did not pick up a user `gsplatModifyVS`
chunk set on the scene gsplat material. As a result, cast shadows did not
follow forward-pass per-vertex animation (e.g. animated splat positions).

GSplatShadowRenderer now applies the scene material's `gsplatModifyVS` chunk
to every per-light shadow material (recompiling only when the chunk changes)
and forwards the scene material's parameters (e.g. `uTime`) to them each
frame, so cast shadows stay in sync with the forward pass.

The Gaussian Splatting > Shadows example gains an "Animate" toggle that
enables a custom position/color vertex modifier, demonstrating the cast
shadow following the animation.

Author: Martin Valigursky

examples/src/examples/gaussian-splatting/shadows.controls.jsx

@@ -1,4 +1,4 @@
-import { BindingTwoWay, LabelGroup, SelectInput, SliderInput } from '@playcanvas/pcui/react';
+import { BindingTwoWay, BooleanInput, LabelGroup, SelectInput, SliderInput } from '@playcanvas/pcui/react';
 
 /**
  * @import { Observer } from '@playcanvas/observer'
@@ -44,6 +44,13 @@ export function Controls({ observer }) {
                     precision={0}
                 />
             </LabelGroup>
+            <LabelGroup text='Animate'>
+                <BooleanInput
+                    type='toggle'
+                    binding={new BindingTwoWay()}
+                    link={{ observer, path: 'shader' }}
+                />
+            </LabelGroup>
         </>
     );
 }

examples/src/examples/gaussian-splatting/shadows.example.mjs

@@ -15,6 +15,9 @@ import { ShadowCatcher } from 'playcanvas/scripts/esm/shadow-catcher.mjs';
 
 import { data, deviceType } from 'examples/context';
 
+import shaderGlslVert from './shader.glsl.vert';
+import shaderWgslVert from './shader.wgsl.vert';
+
 const canvas = /** @type {HTMLCanvasElement} */ (document.getElementById('application-canvas'));
 window.focus();
 
@@ -105,6 +108,24 @@ assetListLoader.load(() => {
     });
     data.set('alphaClip', 0.4);
 
+    // Optional custom vertex shader that animates each splat's position (via modifySplatCenter). The
+    // toggle verifies the cast shadow follows the animated position, since the shadow draw uses the
+    // same quad vertex shader as the forward pass.
+    const sceneMat = app.scene.gsplat.material;
+    const applyCustomShader = (enabled) => {
+        if (enabled) {
+            sceneMat.getShaderChunks('glsl').set('gsplatModifyVS', shaderGlslVert);
+            sceneMat.getShaderChunks('wgsl').set('gsplatModifyVS', shaderWgslVert);
+        } else {
+            sceneMat.getShaderChunks('glsl').delete('gsplatModifyVS');
+            sceneMat.getShaderChunks('wgsl').delete('gsplatModifyVS');
+        }
+        sceneMat.update();
+    };
+    data.on('shader:set', () => applyCustomShader(!!data.get('shader')));
+    applyCustomShader(false);
+    data.set('shader', false);
+
     // Create first splat entity
     const biker = new pc.Entity('biker');
     biker.addComponent('gsplat', {
@@ -194,12 +215,21 @@ assetListLoader.load(() => {
     });
     data.set('numLights', 2);
 
-    // Rotate all lights together (same direction), preserving each light's fixed azimuth offset.
+    // Rotate all lights together (same direction), preserving each light's fixed azimuth offset;
+    // also advance the custom-shader animation time.
     let lightAngle = 0;
+    let currentTime = 0;
     app.on('update', (/** @type {number} */ dt) => {
         lightAngle += dt * 20;
         lights.forEach((light, i) => {
             light.setEulerAngles(55, lightBaseAzimuths[i] + lightAngle, 0);
         });
+
+        currentTime += dt;
+        sceneMat.setParameter('uTime', currentTime);
+
+        // re-dirty the scene gsplat material each frame so the per-frame uTime propagates to the
+        // renderer's material copy (the quad renderer only re-copies template params when dirty)
+        sceneMat.update();
     });
 });

examples/src/examples/gaussian-splatting/shadows.shader.glsl.vert

@@ -0,0 +1,19 @@
+uniform float uTime;
+
+void modifySplatCenter(inout vec3 center) {
+    // animate the splat position (this must be reflected in the cast shadow too)
+    float heightIntensity = center.y * 0.5;
+    center.x += sin(uTime * 5.0 + center.y) * 0.3 * heightIntensity;
+}
+
+void modifySplatRotationScale(vec3 originalCenter, vec3 modifiedCenter, inout vec4 rotation, inout vec3 scale) {
+    // no modification
+}
+
+void modifySplatColor(vec3 center, inout vec4 clr) {
+    float sineValue = abs(sin(uTime * 5.0 + center.y));
+
+    vec3 gold = vec3(1.0, 0.85, 0.0);
+    float blend = smoothstep(0.9, 1.0, sineValue);
+    clr.xyz = mix(clr.xyz, gold, blend);
+}

examples/src/examples/gaussian-splatting/shadows.shader.wgsl.vert

@@ -0,0 +1,19 @@
+uniform uTime: f32;
+
+fn modifySplatCenter(center: ptr<function, vec3f>) {
+    // animate the splat position (this must be reflected in the cast shadow too)
+    let heightIntensity = (*center).y * 0.5;
+    (*center).x += sin(uniform.uTime * 5.0 + (*center).y) * 0.3 * heightIntensity;
+}
+
+fn modifySplatRotationScale(originalCenter: vec3f, modifiedCenter: vec3f, rotation: ptr<function, vec4f>, scale: ptr<function, vec3f>) {
+    // no modification
+}
+
+fn modifySplatColor(center: vec3f, clr: ptr<function, vec4f>) {
+    let sineValue = abs(sin(uniform.uTime * 5.0 + center.y));
+
+    let gold = vec3f(1.0, 0.85, 0.0);
+    let blend = smoothstep(0.9, 1.0, sineValue);
+    (*clr) = vec4f(mix((*clr).xyz, gold, blend), (*clr).a);
+}

src/scene/gsplat-unified/gsplat-shadow-renderer.js

@@ -130,6 +130,24 @@ class GSplatShadowRenderer {
      */
     _frustumPlanes = new Float32Array(24);
 
+    /**
+     * Change-detection key for the scene material's shader chunks; when it changes, the user
+     * `gsplatModifyVS` chunk is re-applied to the per-light shadow materials.
+     *
+     * @type {string}
+     * @private
+     */
+    _userChunksKey = '';
+
+    /**
+     * The scene material's user `gsplatModifyVS` WGSL chunk source (or null for the default no-op).
+     * The shadow path is WebGPU-only, so only the WGSL variant is tracked.
+     *
+     * @type {string|null}
+     * @private
+     */
+    _userModifyWgsl = null;
+
     // The cull/args shaders are shared, but each light entry gets its OWN Compute instances
     // (created in _createEntry). A Compute owns a persistent uniform buffer, so a single shared
     // Compute dispatched once per light per frame would have all dispatches read the last-written
@@ -332,6 +350,11 @@ class GSplatShadowRenderer {
         // current here (cheap: one matrix per splat placement, correct for moving splats).
         this.world.workBuffer.frustumCuller.updateTransformsData(worldState.boundsGroups);
 
+        // Apply the scene material's user vertex-modify chunk + forward its parameters to the
+        // per-light shadow materials, so cast shadows follow the same per-vertex animation as the
+        // forward pass (the shadow draw uses the same quad VS).
+        this._syncUserModify(gsplatParams);
+
         const numIntervals = worldState.totalIntervals;
         const totalActiveSplats = worldState.totalActiveSplats;
         const textureSize = this.world.workBuffer.textureSize;
@@ -341,6 +364,56 @@ class GSplatShadowRenderer {
         });
     }
 
+    /**
+     * Applies the scene material's user `gsplatModifyVS` chunk to every per-light shadow material
+     * (recompiling only when the chunk changes) and forwards the scene material's parameters (e.g.
+     * `uTime`) to them each frame. This keeps cast shadows in sync with any forward-pass vertex
+     * animation, since the shadow draw uses the same quad VS + modify hooks.
+     *
+     * @param {GSplatParams} gsplatParams - Scene gsplat params (carries the template material).
+     * @private
+     */
+    _syncUserModify(gsplatParams) {
+        const userMat = gsplatParams.material;
+        if (!userMat) return;
+
+        // re-apply the modify chunk to all entries when the scene material's chunks change
+        const chunksKey = userMat.shaderChunks?.key ?? '';
+        if (chunksKey !== this._userChunksKey) {
+            this._userChunksKey = chunksKey;
+            this._userModifyWgsl = userMat.getShaderChunks?.('wgsl')?.get('gsplatModifyVS') ?? null;
+            this.entries.forEach(entry => this._applyUserModify(entry));
+        }
+
+        // forward user material parameters (e.g. uTime) every frame. The entry's own bindings are
+        // set afterwards in _cullEntry, so they win on any name collision.
+        const params = userMat.parameters;
+        this.entries.forEach((entry) => {
+            for (const name in params) {
+                if (params.hasOwnProperty(name)) {
+                    entry.material.setParameter(name, params[name].data);
+                }
+            }
+        });
+    }
+
+    /**
+     * Sets (or clears) the tracked user `gsplatModifyVS` chunk on one entry's material and rebuilds
+     * its shader. Called when the chunk changes and when a new entry is created.
+     *
+     * @param {ShadowLightEntry} entry - The light entry.
+     * @private
+     */
+    _applyUserModify(entry) {
+        const wgsl = entry.material.shaderChunks.wgsl;
+        if (this._userModifyWgsl) {
+            wgsl.set('gsplatModifyVS', this._userModifyWgsl);
+        } else {
+            wgsl.delete('gsplatModifyVS');
+        }
+        entry.material.update();
+    }
+
     /**
      * Dispatches the cull + indirect-args for one light entry and binds the results.
      *
@@ -482,7 +555,7 @@ class GSplatShadowRenderer {
         const cullCompute = new Compute(device, this._cullShader, 'GSplatShadowCull');
         const argsCompute = new Compute(device, this._argsShader, 'GSplatShadowIndirectArgs');
 
-        return {
+        const entry = {
             light,
             material,
             meshInstance,
@@ -492,6 +565,11 @@ class GSplatShadowRenderer {
             cullCompute,
             argsCompute
         };
+
+        // apply the current user modify chunk so a newly-added light matches the existing ones
+        this._applyUserModify(entry);
+
+        return entry;
     }
 
     /**