[BREAKING] Update gsplat component material API (#7749)

Author: slimbuck

examples/src/examples/loaders/gsplat-many.example.mjs

@@ -70,11 +70,13 @@ assetListLoader.load(() => {
     camera.setLocalPosition(-3, 1, 2);
 
     // instantiate guitar with a custom shader
-    const guitar = assets.guitar.resource.instantiate({
-        vertex: files['shader.vert']
+    const guitar = new pc.Entity('guitar');
+    guitar.addComponent('gsplat', {
+        asset: assets.guitar
     });
-    guitar.name = 'guitar';
+    guitar.gsplat.material.getShaderChunks('glsl').set('gsplatVS', files['shader.vert']);
     guitar.setLocalPosition(0, 0.8, 0);
+    guitar.setLocalEulerAngles(0, 0, 180);
     guitar.setLocalScale(0.4, 0.4, 0.4);
     app.root.addChild(guitar);
 
@@ -118,25 +120,35 @@ assetListLoader.load(() => {
     data.on('shader:set', () => {
         // Apply custom or default material options to the splats when the button is clicked. Note
         // that this uses non-public API, which is subject to change when a proper API is added.
-        const materialOptions = {
-            fragment: files['shader.frag'],
-            vertex: files['shader.vert']
-        };
-        biker1.gsplat.materialOptions = useCustomShader ? materialOptions : null;
-        biker2.gsplat.materialOptions = useCustomShader ? materialOptions : null;
+        const vs = files['shader.vert'];
 
-        // biker 2 uses a different shader variant
-        biker2.gsplat.material.setDefine('CUTOUT', true);
+        const mat1 = biker1.gsplat.material;
+        if (useCustomShader) {
+            mat1.getShaderChunks('glsl').set('gsplatVS', vs);
+        } else {
+            mat1.getShaderChunks('glsl').delete('gsplatVS');
+        }
+        mat1.update();
+
+        const mat2 = biker2.gsplat.material;
+        if (useCustomShader) {
+            mat2.getShaderChunks('glsl').set('gsplatVS', vs);
+        } else {
+            mat2.getShaderChunks('glsl').delete('gsplatVS');
+        }
+        mat2.setDefine('CUTOUT', true);
+        mat2.update();
 
         useCustomShader = !useCustomShader;
     });
 
+    const uTime = app.graphicsDevice.scope.resolve('uTime');
+
     let currentTime = 0;
     app.on('update', (dt) => {
         currentTime += dt;
 
-        const material = guitar.gsplat?.material;
-        material?.setParameter('uTime', currentTime);
+        uTime.setValue(currentTime);
 
         biker2.rotate(0, 80 * dt, 0);
     });

src/framework/components/gsplat/component.js

@@ -9,8 +9,7 @@ import { Component } from '../component.js';
  * @import { Entity } from '../../entity.js'
  * @import { EventHandle } from '../../../core/event-handle.js'
  * @import { GSplatComponentSystem } from './system.js'
- * @import { Material } from '../../../scene/materials/material.js'
- * @import { SplatMaterialOptions } from '../../../scene/gsplat/gsplat-material.js'
+ * @import { ShaderMaterial } from '../../../scene/materials/shader-material.js'
  */
 
 /**
@@ -56,22 +55,22 @@ class GSplatComponent extends Component {
     _instance = null;
 
     /**
-     * @type {BoundingBox|null}
+     * @type {ShaderMaterial|null}
      * @private
      */
-    _customAabb = null;
+    _materialTmp = null;
 
     /**
-     * @type {AssetReference}
+     * @type {BoundingBox|null}
      * @private
      */
-    _assetReference;
+    _customAabb = null;
 
     /**
-     * @type {SplatMaterialOptions|null}
+     * @type {AssetReference}
      * @private
      */
-    _materialOptions = null;
+    _assetReference;
 
     /**
      * @type {EventHandle|null}
@@ -158,22 +157,16 @@ class GSplatComponent extends Component {
 
         this._instance = value;
 
-        if (this._instance?.meshInstance) {
+        if (this._instance) {
 
             // if mesh instance was created without a node, assign it here
             const mi = this._instance.meshInstance;
             if (!mi.node) {
                 mi.node = this.entity;
             }
-
             mi.castShadow = this._castShadows;
             mi.setCustomAabb(this._customAabb);
 
-            // if we have custom shader options, apply them
-            if (this._materialOptions) {
-                this._instance.createMaterial(this._materialOptions);
-            }
-
             if (this.enabled && this.entity.enabled) {
                 this.addToLayers();
             }
@@ -190,26 +183,26 @@ class GSplatComponent extends Component {
         return this._instance;
     }
 
-    set materialOptions(value) {
-        this._materialOptions = Object.assign({}, value);
-
-        // apply them on the instance if it exists
+    /**
+     * Sets the material used to render the gsplat.
+     *
+     * @param {ShaderMaterial} value - The material instance.
+     */
+    set material(value) {
         if (this._instance) {
-            this._instance.createMaterial(this._materialOptions);
+            this._instance.material = value;
+        } else {
+            this._materialTmp = value;
         }
     }
 
-    get materialOptions() {
-        return this._materialOptions;
-    }
-
     /**
      * Gets the material used to render the gsplat.
      *
-     * @type {Material|undefined}
+     * @type {ShaderMaterial|null}
      */
     get material() {
-        return this._instance?.material;
+        return this._instance?.material ?? this._materialTmp ?? null;
     }
 
     /**
@@ -326,18 +319,6 @@ class GSplatComponent extends Component {
         return this._assetReference.id;
     }
 
-    /**
-     * Assign asset id to the component, without updating the component with the new asset.
-     * This can be used to assign the asset id to already fully created component.
-     *
-     * @param {Asset|number} asset - The gsplat asset or asset id to assign.
-     * @ignore
-     */
-    assignAsset(asset) {
-        const id = asset instanceof Asset ? asset.id : asset;
-        this._assetReference.id = id;
-    }
-
     /** @private */
     destroyInstance() {
         if (this._instance) {
@@ -487,7 +468,8 @@ class GSplatComponent extends Component {
         // create new instance
         const asset = this._assetReference.asset;
         if (asset) {
-            this.instance = new GSplatInstance(asset.resource, this._materialOptions || {});
+            this.instance = new GSplatInstance(asset.resource, this._materialTmp);
+            this._materialTmp = null;
             this.customAabb = this.instance.resource.aabb.clone();
         }
     }

src/framework/components/gsplat/system.js

@@ -16,9 +16,9 @@ const _schema = [
 // order matters here
 const _properties = [
     'castShadows',
-    'instance',
     'asset',
-    'layers'
+    'layers',
+    'material'
 ];
 
 /**
@@ -71,22 +71,16 @@ class GSplatComponentSystem extends ComponentSystem {
 
         // copy properties
         const data = {};
-        for (let i = 0; i < _properties.length; i++) {
-            data[_properties[i]] = gSplatComponent[_properties[i]];
-        }
+        _properties.forEach((prop) => {
+            if (prop !== 'material') {
+                data[prop] = gSplatComponent[prop];
+            }
+        });
         data.enabled = gSplatComponent.enabled;
 
-        // gsplat instance cannot be used this way, remove it and manually clone it later
-        delete data.instance;
-
         // clone component
         const component = this.addComponent(clone, data);
 
-        // clone gsplat instance
-        if (gSplatComponent.instance) {
-            component.instance = gSplatComponent.instance.clone();
-        }
-
         if (gSplatComponent.customAabb) {
             component.customAabb = gSplatComponent.customAabb.clone();
         }

src/scene/gsplat/gsplat-compressed-resource.js

@@ -2,15 +2,12 @@ import { Vec2 } from '../../core/math/vec2.js';
 import {
     PIXELFORMAT_RGBA32F, PIXELFORMAT_RGBA32U
 } from '../../platform/graphics/constants.js';
-import { createGSplatMaterial } from './gsplat-material.js';
 import { GSplatResourceBase } from './gsplat-resource-base.js';
 
 /**
  * @import { GSplatCompressedData } from './gsplat-compressed-data.js'
  * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js'
  * @import { Texture } from '../../platform/graphics/texture.js';
- * @import { Material } from '../materials/material.js'
- * @import { SplatMaterialOptions } from './gsplat-material.js'
  */
 
 // copy data with padding
@@ -93,24 +90,18 @@ class GSplatCompressedResource extends GSplatResourceBase {
         this.shTexture2?.destroy();
     }
 
-    /**
-     * @param {SplatMaterialOptions} options - The splat material options.
-     * @returns {Material} material - The material to set up for the splat rendering.
-     */
-    createMaterial(options) {
-        const result = createGSplatMaterial(this.device, options);
-        result.setDefine('GSPLAT_COMPRESSED_DATA', true);
-        result.setParameter('packedTexture', this.packedTexture);
-        result.setParameter('chunkTexture', this.chunkTexture);
+    configureMaterial(material) {
+        material.setDefine('GSPLAT_COMPRESSED_DATA', true);
+        material.setParameter('packedTexture', this.packedTexture);
+        material.setParameter('chunkTexture', this.chunkTexture);
         if (this.shTexture0) {
-            result.setDefine('SH_BANDS', 3);
-            result.setParameter('shTexture0', this.shTexture0);
-            result.setParameter('shTexture1', this.shTexture1);
-            result.setParameter('shTexture2', this.shTexture2);
+            material.setDefine('SH_BANDS', 3);
+            material.setParameter('shTexture0', this.shTexture0);
+            material.setParameter('shTexture1', this.shTexture1);
+            material.setParameter('shTexture2', this.shTexture2);
         } else {
-            result.setDefine('SH_BANDS', 0);
+            material.setDefine('SH_BANDS', 0);
         }
-        return result;
     }
 
     /**