Smart Filters: Add const property support - consts in GLSL defined blocks that are settable at design time (#17479)

With this change, consts in fragment shaders of blocks defined using
GLSL can be annotated to be treated as properties on the resulting
block. Those properties can be set before runtime creation and then are
baked into the shader as consts. The properties are annotated for the
Smart Filter Editor to see and display in the property pane on the right
when a block instance is selected. The optimizer is updated to know that
such consts cannot be consolidated into a single const for all instances
of that block type, although regular unannotated consts will still be
consolidated.

The syntax for the annotation can either be:
```
// { "property": true }
const float mode = 1.0;
```
and this will show a text box in the Smart Filter Editor:
<img width="569" height="150" alt="image"
src="https://github.com/user-attachments/assets/c7b9f77f-2f0e-4018-9daf-c6067ba52139"
/>


Or you can supply a list of options for the value:
```
// { "property": { "options": { "Normal": 0, "Crazy": 1, "Odd": 2 } } }
const float mode = 1.0;
```
and this will show a drop down in the Smart Filter Editor:
<img width="550" height="155" alt="image"
src="https://github.com/user-attachments/assets/9f564e6d-57fe-422f-98f6-a3be16f7e619"
/>

This change also updates the serialization of CustomShaderBlocks to
include the values of these properties in the data section:
```
{
      "name": "Example",
      "uniqueId": 34,
      "blockType": "ConstPropertyExample",
      "namespace": "Test",
      "comments": null,
      "data": {
        "customProperties": [
          {
            "name": "mode",
            "value": 1
          }
        ]
      },
      "outputTextureOptions": {
        "ratio": 1,
        "format": 5,
        "type": 0
      }
    }
```

Note: this change is backwards compatible.

---------

Co-authored-by: AmoebaChant <[email protected]>

Author: AmoebaChant

packages/dev/smartFilterBlocks/src/blocks/babylon/demo/effects/compositionBlock.fragment.glsl

@@ -1,38 +1,40 @@
-uniform sampler2D background; // main
-uniform sampler2D foreground;
-
-uniform vec2 scaleUV;
-uniform vec2 translateUV;
-uniform float alphaMode;
-uniform float foregroundAlphaScale;
-
-vec4 composition(vec2 vUV) { // main
-    vec4 background = texture2D(background, vUV);
-
-    vec2 transformedUV = vUV * (1.0 / scaleUV) + translateUV;
-    if (transformedUV.x < 0.0 || transformedUV.x > 1.0 || transformedUV.y < 0.0 || transformedUV.y > 1.0) {
-        return background;
-    }
-
-    vec4 foreground = texture2D(foreground, transformedUV);
-    foreground.a *= foregroundAlphaScale;
-
-    // SRC is foreground, DEST is background
-    if (alphaMode == 0.) {
-        return foreground;
-    }
-    else if (alphaMode == 1.) {
-        return foreground.a * foreground + background;
-    }
-    else if (alphaMode == 2.) {
-        return mix(background, foreground, foreground.a);
-    }
-    else if (alphaMode == 3.) {
-        return background - foreground * background;
-    }
-    else if (alphaMode == 4.) {
-        return foreground * background;
-    }
-
-    return background;
+uniform sampler2D background; // main
+uniform sampler2D foreground;
+
+// { "property": true }
+const float alphaMode = 1;
+
+uniform vec2 scaleUV;
+uniform vec2 translateUV;
+uniform float foregroundAlphaScale;
+
+vec4 composition(vec2 vUV) { // main
+    vec4 background = texture2D(background, vUV);
+
+    vec2 transformedUV = vUV * (1.0 / scaleUV) + translateUV;
+    if (transformedUV.x < 0.0 || transformedUV.x > 1.0 || transformedUV.y < 0.0 || transformedUV.y > 1.0) {
+        return background;
+    }
+
+    vec4 foreground = texture2D(foreground, transformedUV);
+    foreground.a *= foregroundAlphaScale;
+
+    // SRC is foreground, DEST is background
+    if (alphaMode == 0.) {
+        return foreground;
+    }
+    else if (alphaMode == 1.) {
+        return foreground.a * foreground + background;
+    }
+    else if (alphaMode == 2.) {
+        return mix(background, foreground, foreground.a);
+    }
+    else if (alphaMode == 3.) {
+        return background - foreground * background;
+    }
+    else if (alphaMode == 4.) {
+        return foreground * background;
+    }
+
+    return background;
 }

packages/dev/smartFilterBlocks/src/blocks/babylon/demo/effects/compositionBlock.ts

@@ -11,6 +11,7 @@ import {
     createStrongRef,
     PropertyTypeForEdition,
     editableInPropertyPage,
+    CloneShaderProgram,
 } from "smart-filters";
 import { compositionBlockType } from "../../../blockTypes.js";
 import { babylonDemoEffectsNamespace } from "../../../blockNamespaces.js";
@@ -40,7 +41,6 @@ export class CompositionShaderBinding extends DisableableShaderBinding {
     private readonly _foregroundWidth: RuntimeData<ConnectionPointType.Float>;
     private readonly _foregroundHeight: RuntimeData<ConnectionPointType.Float>;
     private readonly _foregroundAlphaScale: RuntimeData<ConnectionPointType.Float>;
-    private readonly _alphaMode: number;
 
     /**
      * Creates a new shader binding instance for the Composition block.
@@ -52,7 +52,6 @@ export class CompositionShaderBinding extends DisableableShaderBinding {
      * @param foregroundWidth - the width of the foreground texture
      * @param foregroundHeight - the height of the foreground texture
      * @param foregroundAlphaScale - the alpha scale of the foreground texture
-     * @param alphaMode - the alpha mode to use
      */
     constructor(
         parentBlock: IDisableableBlock,
@@ -62,8 +61,7 @@ export class CompositionShaderBinding extends DisableableShaderBinding {
         foregroundLeft: RuntimeData<ConnectionPointType.Float>,
         foregroundWidth: RuntimeData<ConnectionPointType.Float>,
         foregroundHeight: RuntimeData<ConnectionPointType.Float>,
-        foregroundAlphaScale: RuntimeData<ConnectionPointType.Float>,
-        alphaMode: number
+        foregroundAlphaScale: RuntimeData<ConnectionPointType.Float>
     ) {
         super(parentBlock);
         this._backgroundTexture = backgroundTexture;
@@ -73,7 +71,6 @@ export class CompositionShaderBinding extends DisableableShaderBinding {
         this._foregroundWidth = foregroundWidth;
         this._foregroundHeight = foregroundHeight;
         this._foregroundAlphaScale = foregroundAlphaScale;
-        this._alphaMode = alphaMode;
     }
 
     /**
@@ -92,9 +89,7 @@ export class CompositionShaderBinding extends DisableableShaderBinding {
         const foregroundWidth = this._foregroundWidth.value;
         const foregroundHeight = this._foregroundHeight.value;
         const foregroundAlphaScale = this._foregroundAlphaScale.value;
-        const alphaMode = this._alphaMode;
 
-        effect.setFloat(this.getRemappedName(uniforms.alphaMode), alphaMode);
         effect.setTexture(this.getRemappedName(uniforms.background), background);
         effect.setTexture(this.getRemappedName(uniforms.foreground), foreground);
 
@@ -183,6 +178,22 @@ export class CompositionBlock extends DisableableShaderBlock {
      */
     public static override ShaderCode = shaderProgram;
 
+    /**
+     * Gets the shader program to use to render the block.
+     * This adds the per-instance const values to the shader program.
+     * @returns The shader program to use to render the block
+     */
+    public override getShaderProgram() {
+        const staticShaderProgram = super.getShaderProgram();
+
+        // Since we are making changes only for this instance of the block, and
+        // the disableableShaderProgram is static, we make a copy and modify that.
+        const shaderProgramForThisInstance = CloneShaderProgram(staticShaderProgram);
+        shaderProgramForThisInstance.fragment.constPerInstance = `const float _alphaMode_ = ${this.alphaMode.toFixed(1)};`;
+
+        return shaderProgramForThisInstance;
+    }
+
     /**
      * Instantiates a new Block.
      * @param smartFilter - The smart filter this block belongs to
@@ -204,8 +215,7 @@ export class CompositionBlock extends DisableableShaderBlock {
         const foregroundHeight = this.foregroundHeight.runtimeData;
         const foregroundTop = this.foregroundTop.runtimeData;
         const foregroundAlphaScale = this.foregroundAlphaScale.runtimeData;
-        const alphaMode = this.alphaMode;
 
-        return new CompositionShaderBinding(this, background, foreground, foregroundTop, foregroundLeft, foregroundWidth, foregroundHeight, foregroundAlphaScale, alphaMode);
+        return new CompositionShaderBinding(this, background, foreground, foregroundTop, foregroundLeft, foregroundWidth, foregroundHeight, foregroundAlphaScale);
     }
 }

packages/dev/smartFilters/src/blockFoundation/customShaderBlock.serializer.ts

@@ -0,0 +1,51 @@
+import type { ISerializedBlockV1, SerializeBlockV1 } from "../serialization/v1/smartFilterSerialization.types.js";
+import type { BaseBlock } from "./baseBlock.js";
+import { CustomShaderBlock } from "./customShaderBlock.js";
+
+/**
+ * Data for a dynamic property on a CustomShaderBlock
+ */
+export type CustomShaderBlockData = {
+    /**
+     * The custom properties of the CustomShaderBlock
+     */
+    customProperties: CustomPropertyData[];
+};
+
+type CustomPropertyData = {
+    name: string;
+    value: any;
+};
+
+/**
+ * Serializes a CustomShaderBlock to V1 serialized data.
+ * @param block - The block to serialize
+ * @returns The serialized block
+ */
+export const CustomShaderBlockSerializer: SerializeBlockV1 = (block: BaseBlock): ISerializedBlockV1 => {
+    if (block.getClassName() !== CustomShaderBlock.ClassName) {
+        throw new Error("Was asked to serialize an unrecognized block type");
+    }
+    const customShaderBlock = block as CustomShaderBlock;
+
+    let data: CustomShaderBlockData | undefined;
+    const dynamicPropertyNames = customShaderBlock.dynamicPropertyNames;
+    if (dynamicPropertyNames.length > 0) {
+        data = {
+            customProperties: dynamicPropertyNames.map((propertyName) => ({
+                name: propertyName,
+                value: (customShaderBlock as any)[propertyName],
+            })),
+        };
+    }
+
+    return {
+        name: customShaderBlock.name,
+        uniqueId: customShaderBlock.uniqueId,
+        blockType: customShaderBlock.blockType,
+        namespace: customShaderBlock.namespace,
+        comments: customShaderBlock.comments,
+        data,
+        outputTextureOptions: customShaderBlock.outputTextureOptions,
+    };
+};

packages/dev/smartFilters/src/blockFoundation/customShaderBlock.ts

@@ -4,12 +4,14 @@ import { ConnectionPointType, type ConnectionPointValue } from "../connection/co
 import { ShaderBinding } from "../runtime/shaderRuntime.js";
 import { CreateStrongRef } from "../runtime/strongRef.js";
 import type { SerializedShaderBlockDefinition } from "../serialization/serializedShaderBlockDefinition.js";
-import type { SerializedInputConnectionPointV1 } from "../serialization/v1/shaderBlockSerialization.types.js";
+import type { SerializedInputConnectionPointV1, ConstPropertyMetadata } from "../serialization/v1/shaderBlockSerialization.types.js";
 import type { SmartFilter } from "../smartFilter.js";
-import type { ShaderProgram } from "../utils/shaderCodeUtils.js";
+import { CloneShaderProgram, type ShaderProgram } from "../utils/shaderCodeUtils.js";
 import { ShaderBlock } from "./shaderBlock.js";
 import type { RuntimeData } from "../connection/connectionPoint.js";
 import type { Nullable } from "core/types.js";
+import { EditableInPropertyPage, type IEditablePropertyOption, PropertyTypeForEdition } from "../editorUtils/editableInPropertyPage.js";
+import type { CustomShaderBlockData } from "./customShaderBlock.serializer.js";
 
 /**
  * The binding for a CustomShaderBlock
@@ -95,20 +97,33 @@ export class CustomShaderBlock extends ShaderBlock {
      * @param smartFilter - The smart filter this block belongs to
      * @param name - Defines the name of the block
      * @param blockDefinition - The serialized block definition
+     * @param data - The data property from the serialized block, if applicable
      * @returns The deserialized CustomShaderBlock instance
      */
-    public static Create(smartFilter: SmartFilter, name: string, blockDefinition: SerializedShaderBlockDefinition): CustomShaderBlock {
+    public static Create(smartFilter: SmartFilter, name: string, blockDefinition: SerializedShaderBlockDefinition, data?: any): CustomShaderBlock {
         // When a new version of SerializedBlockDefinition is created, this function should be updated to handle the new properties.
 
-        return new CustomShaderBlock(
+        const newBlock = new CustomShaderBlock(
             smartFilter,
             name,
             blockDefinition.disableOptimization,
             blockDefinition.blockType,
             blockDefinition.namespace,
             blockDefinition.inputConnectionPoints,
+            blockDefinition.fragmentConstProperties || [],
             blockDefinition.shaderProgram
         );
+
+        if (data && (data as CustomShaderBlockData).customProperties) {
+            const customProperties = (data as CustomShaderBlockData).customProperties;
+            for (const customProperty of customProperties) {
+                if (newBlock.dynamicPropertyNames.indexOf(customProperty.name) !== -1) {
+                    (newBlock as any)[customProperty.name] = customProperty.value;
+                }
+            }
+        }
+
+        return newBlock;
     }
 
     /**
@@ -119,8 +134,16 @@ export class CustomShaderBlock extends ShaderBlock {
     private readonly _shaderProgram: ShaderProgram;
     private readonly _blockType: string;
     private readonly _namespace: Nullable<string>;
+    private readonly _fragmentConstProperties: ConstPropertyMetadata[];
     private _autoBoundInputs: Nullable<SerializedInputConnectionPointV1[]> = null;
 
+    /**
+     * A list of the names of the properties added to this instance of the block, for example,
+     * fragment const properties.
+     *
+     */
+    public readonly dynamicPropertyNames: string[] = [];
+
     /**
      * The type of the block - used when serializing / deserializing the block, and in the editor.
      */
@@ -144,6 +167,7 @@ export class CustomShaderBlock extends ShaderBlock {
      * @param blockType - The type of the block
      * @param namespace - The namespace of the block
      * @param inputConnectionPoints - The input connection points of the
+     * @param fragmentConstProperties - The define properties for the block
      * @param shaderProgram - The shader program for the block
      */
     private constructor(
@@ -153,25 +177,75 @@ export class CustomShaderBlock extends ShaderBlock {
         blockType: string,
         namespace: Nullable<string>,
         inputConnectionPoints: SerializedInputConnectionPointV1[],
+        fragmentConstProperties: ConstPropertyMetadata[],
         shaderProgram: ShaderProgram
     ) {
         super(smartFilter, name, disableOptimization);
         this._blockType = blockType;
         this._namespace = namespace;
+        this._shaderProgram = shaderProgram;
+        this._fragmentConstProperties = fragmentConstProperties;
 
         for (const input of inputConnectionPoints) {
             this._registerSerializedInputConnectionPointV1(input);
         }
 
-        this._shaderProgram = shaderProgram;
+        for (const constProperty of fragmentConstProperties) {
+            this._createConstProperty(constProperty);
+        }
     }
 
     /**
      * Gets the shader program to use to render the block.
      * @returns The shader program to use to render the block
      */
     public override getShaderProgram() {
-        return this._shaderProgram;
+        if (this._fragmentConstProperties.length === 0) {
+            return this._shaderProgram;
+        } else {
+            // Make a copy of the shader program and append const properties to the fragment shader consts
+            const shaderProgramForThisInstance = CloneShaderProgram(this._shaderProgram);
+            shaderProgramForThisInstance.fragment.constPerInstance =
+                this._fragmentConstProperties
+                    .map((property) => {
+                        switch (property.type) {
+                            case "float": {
+                                const value = (this as any)[property.friendlyName] as number;
+                                const valueStr = Number.isInteger(value) ? value.toString() + "." : value.toString();
+                                return `const float ${property.name} = ${valueStr};`;
+                            }
+                        }
+                    })
+                    .join("\n") + "\n";
+
+            return shaderProgramForThisInstance;
+        }
+    }
+
+    /**
+     * Creates a dynamic property for the supplied const property with EditableInPropertyPage decorator.
+     * @param constProperty - The const property metadata
+     */
+    private _createConstProperty(constProperty: ConstPropertyMetadata): void {
+        // Create the property and assign the default value
+        (this as any)[constProperty.friendlyName] = constProperty.defaultValue;
+        this.dynamicPropertyNames.push(constProperty.friendlyName);
+
+        // Use the EditableInPropertyPage decorator to make the property editable in the Smart Filters Editor
+        const editablePropertyOptions: IEditablePropertyOption = {
+            notifiers: { rebuild: true },
+            blockType: this._blockType,
+        };
+        if (constProperty.options) {
+            editablePropertyOptions.options = Object.keys(constProperty.options).map((key) => {
+                return { label: key, value: (constProperty.options as any)[key] };
+            });
+        }
+
+        const propertyType: PropertyTypeForEdition = constProperty.options ? PropertyTypeForEdition.List : PropertyTypeForEdition.Float;
+
+        const decoratorApplier = EditableInPropertyPage(constProperty.friendlyName, propertyType, "PROPERTIES", editablePropertyOptions);
+        decoratorApplier(this, constProperty.friendlyName);
     }
 
     /**