[BREAKING] Update gsplat component material API

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

@@ -70,11 +70,12 @@ 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.setLocalPosition(0, 0.8, 0);
+    guitar.setLocalEulerAngles(0, 0, 180);
     guitar.setLocalScale(0.4, 0.4, 0.4);
     app.root.addChild(guitar);
 

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;
+    _materialStore = 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,24 @@ class GSplatComponent extends Component {
         return this._instance;
     }
 
-    set materialOptions(value) {
-        this._materialOptions = Object.assign({}, value);
-
-        // apply them on the instance if it exists
+    /**
+     * @param {ShaderMaterial} value - The material instance.
+     */
+    set material(value) {
         if (this._instance) {
-            this._instance.createMaterial(this._materialOptions);
+            this._instance.material = value;
+        } else {
+            this._materialStore = 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._materialStore ?? null;
     }
 
     /**
@@ -326,18 +317,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 +466,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._materialStore);
+            this._materialStore = null;
             this.customAabb = this.instance.resource.aabb.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;
     }
 
     /**

src/scene/gsplat/gsplat-instance.js

@@ -1,16 +1,15 @@
 import { Mat4 } from '../../core/math/mat4.js';
 import { Vec3 } from '../../core/math/vec3.js';
-import { PIXELFORMAT_R32U } from '../../platform/graphics/constants.js';
-import { DITHER_NONE } from '../constants.js';
+import { CULLFACE_NONE, SEMANTIC_ATTR13, SEMANTIC_POSITION, PIXELFORMAT_R32U } from '../../platform/graphics/constants.js';
 import { MeshInstance } from '../mesh-instance.js';
 import { GSplatSorter } from './gsplat-sorter.js';
+import { ShaderMaterial } from '../materials/shader-material.js';
+import { BLEND_NONE, BLEND_PREMULTIPLIED } from '../constants.js';
 
 /**
  * @import { Camera } from '../camera.js'
  * @import { GSplatResourceBase } from './gsplat-resource-base.js'
  * @import { GraphNode } from '../graph-node.js'
- * @import { Material } from '../materials/material.js'
- * @import { SplatMaterialOptions } from './gsplat-material.js'
  * @import { Texture } from '../../platform/graphics/texture.js'
  */
 
@@ -24,15 +23,15 @@ class GSplatInstance {
     /** @type {GSplatResourceBase} */
     resource;
 
-    /** @type {MeshInstance} */
-    meshInstance;
-
-    /** @type {Material} */
-    material;
-
     /** @type {Texture} */
     orderTexture;
 
+    /** @type {ShaderMaterial} */
+    _material;
+
+    /** @type {MeshInstance} */
+    meshInstance;
+
     options = {};
 
     /** @type {GSplatSorter | null} */
@@ -52,25 +51,43 @@ class GSplatInstance {
 
     /**
      * @param {GSplatResourceBase} resource - The splat instance.
-     * @param {SplatMaterialOptions} options - The options.
+     * @param {ShaderMaterial|null} material - The material instance.
      */
-    constructor(resource, options) {
+    constructor(resource, material) {
         this.resource = resource;
 
-        // clone options object
-        options = Object.assign(this.options, options);
-
         // create the order texture
         this.orderTexture = resource.createTexture(
             'splatOrder',
             PIXELFORMAT_R32U,
             resource.evalTextureSize(resource.numSplats)
         );
 
-        // material
-        this.createMaterial(options);
+        if (material) {
+            // material is provided
+            this._material = material;
+        } else {
+            // construct the material
+            this._material = new ShaderMaterial({
+                uniqueName: 'SplatMaterial',
+                vertexGLSL: '#include "gsplatVS"',
+                fragmentGLSL: '#include "gsplatPS"',
+                vertexWGSL: '#include "gsplatVS"',
+                fragmentWGSL: '#include "gsplatPS"',
+                attributes: {
+                    vertex_position: SEMANTIC_POSITION,
+                    vertex_id_attrib: SEMANTIC_ATTR13
+                }
+            });
+
+            // default configure
+            this.configureMaterial(this._material);
+
+            // update
+            this._material.update();
+        }
 
-        this.meshInstance = new MeshInstance(resource.mesh, this.material);
+        this.meshInstance = new MeshInstance(resource.mesh, this._material);
         this.meshInstance.setInstancing(resource.instanceIndices, true);
         this.meshInstance.gsplatInstance = this;
 
@@ -82,17 +99,15 @@ class GSplatInstance {
         const chunks = resource.chunks?.slice();
 
         // create sorter
-        if (!options.dither || options.dither === DITHER_NONE) {
-            this.sorter = new GSplatSorter();
-            this.sorter.init(this.orderTexture, centers, chunks);
-            this.sorter.on('updated', (count) => {
-                // limit splat render count to exclude those behind the camera
-                this.meshInstance.instancingCount = Math.ceil(count / resource.instanceSize);
-
-                // update splat count on the material
-                this.material.setParameter('numSplats', count);
-            });
-        }
+        this.sorter = new GSplatSorter();
+        this.sorter.init(this.orderTexture, centers, chunks);
+        this.sorter.on('updated', (count) => {
+            // limit splat render count to exclude those behind the camera
+            this.meshInstance.instancingCount = Math.ceil(count / resource.instanceSize);
+
+            // update splat count on the material
+            this.material.setParameter('numSplats', count);
+        });
     }
 
     destroy() {
@@ -102,18 +117,46 @@ class GSplatInstance {
     }
 
     clone() {
-        return new GSplatInstance(this.resource, this.options);
+        return new GSplatInstance(this.resource, this.material.clone());
     }
 
-    createMaterial(options) {
-        this.material = this.resource.createMaterial(options);
-        this.material.setParameter('splatOrder', this.orderTexture);
-        this.material.setParameter('alphaClip', 0.3);
-        if (this.meshInstance) {
-            this.meshInstance.material = this.material;
+    /**
+     * @param {ShaderMaterial} value - The material instance.
+     */
+    set material(value) {
+        if (this._material !== value) {
+            // set the new material
+            this._material = value;
+
+            if (this.meshInstance) {
+                this.meshInstance.material = value;
+            }
         }
     }
 
+    get material() {
+        return this._material;
+    }
+
+    /**
+     * Configure the material with gsplat instance and resource properties.
+     *
+     * @param {ShaderMaterial} material - The material to configure.
+     * @param {boolean} dither - Specify true to configure the material for dithered rendering (stochastic alpha).
+     */
+    configureMaterial(material, dither = false) {
+        // allow resource to configure the material
+        this.resource.configureMaterial(material);
+
+        // set instance properties
+        material.setParameter('splatOrder', this.orderTexture);
+        material.setParameter('alphaClip', 0.3);
+        material.setDefine(`DITHER_${dither ? 'BLUENOISE' : 'NONE'}`, '');
+        material.cull = CULLFACE_NONE;
+        material.blendType = dither ? BLEND_NONE : BLEND_PREMULTIPLIED;
+        material.depthWrite = dither;
+    }
+
     updateViewport(cameraNode) {
         const camera = cameraNode?.camera;
         const renderTarget = camera?.renderTarget;

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

@@ -109,6 +109,12 @@ class GSplatResourceBase {
         return this.gsplatData.numSplats;
     }
 
+    configureMaterial(material) {
+    }
+
+    evalTextureSize(count) {
+    }
+
     /**
      * Creates a new texture with the specified parameters.
      *