Fire ‘shader:generate’ when a shader code gets generated (#5524)

* Fire ‘shader:generate’ when a shader code gets generated

* updated docs for userId

---------

Co-authored-by: Martin Valigursky <mvaligursky@snapchat.com>

src/scene/materials/basic-material.js

@@ -115,7 +115,7 @@ class BasicMaterial extends Material {
         const library = getProgramLibrary(device);
         library.register('basic', basic);
 
-        return library.getProgram('basic', options, processingOptions);
+        return library.getProgram('basic', options, processingOptions, this.userId);
     }
 }
 

src/scene/materials/lit-material.js

@@ -94,7 +94,7 @@ class LitMaterial extends Material {
         const processingOptions = new ShaderProcessorOptions(viewUniformFormat, viewBindGroupFormat, vertexFormat);
         const library = getProgramLibrary(device);
         library.register('lit', lit);
-        const shader = library.getProgram('lit', options, processingOptions);
+        const shader = library.getProgram('lit', options, processingOptions, this.userId);
         return shader;
     }
 }

src/scene/materials/material.js

@@ -68,6 +68,15 @@ class Material {
      */
     name = 'Untitled';
 
+    /**
+     * A unique id the user can assign to the material. The engine internally does not use this for
+     * anything, and the user can assign a value to this id for any purpose they like. Defaults to
+     * an empty string.
+     *
+     * @type {string}
+     */
+    userId = '';
+
     id = id++;
 
     variants = {};

src/scene/materials/standard-material.js

@@ -865,7 +865,7 @@ class StandardMaterial extends Material {
 
         const library = getProgramLibrary(device);
         library.register('standard', standard);
-        const shader = library.getProgram('standard', options, processingOptions);
+        const shader = library.getProgram('standard', options, processingOptions, this.userId);
 
         this._dirtyShader = false;
         return shader;

src/scene/shader-lib/program-library.js

@@ -110,7 +110,7 @@ class ProgramLibrary {
         this.processedCache.set(key, shader);
     }
 
-    getProgram(name, options, processingOptions) {
+    getProgram(name, options, processingOptions, userMaterialId) {
         const generator = this._generators[name];
         if (!generator) {
             Debug.warn(`ProgramLibrary#getProgram: No program library functions registered for: ${name}`);
@@ -133,11 +133,20 @@ class ProgramLibrary {
 
             // use shader pass name if known
             let passName = '';
+            let shaderPassInfo;
             if (options.pass !== undefined) {
-                const shaderPassInfo = ShaderPass.get(this._device).getByIndex(options.pass);
+                shaderPassInfo = ShaderPass.get(this._device).getByIndex(options.pass);
                 passName = `-${shaderPassInfo.name}`;
             }
 
+            // fire an event to allow the shader to be modified by the user. Note that any modifications are applied
+            // to all materials using the same generated shader, as the cache key is not modified.
+            this._device.fire('shader:generate', {
+                userMaterialId,
+                shaderPassInfo,
+                definition: generatedShaderDef
+            });
+
             // create a shader definition for the shader that will include the processingOptions
             const shaderDefinition = {
                 name: `${generatedShaderDef.name}${passName}-proc`,