@onerjs/smart-filters 8.31.5 → 8.31.7

package/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,
+    };
+};

package/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,17 +177,22 @@ 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);
+        }
     }
 
     /**
@@ -171,7 +200,52 @@ export class CustomShaderBlock extends ShaderBlock {
      * @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);
     }
 
     /**

package/src/blockFoundation/disableableShaderBlock.ts

@@ -65,27 +65,36 @@ export abstract class DisableableShaderBlock extends ShaderBlock implements IDis
     }
 
     /**
-     * Instantiates a new block.
-     * @param smartFilter - Defines the smart filter the block belongs to
-     * @param name - Defines the name of the block
-     * @param disableOptimization - Defines if the block should not be optimized (default: false)
-     * @param disableStrategy - Defines the strategy to use for making this block disableable (default: BlockDisableStrategy.AutoSample)
+     * Gets the shader program to use to render the block.
+     * @returns The shader program to use to render the block
      */
-    constructor(smartFilter: SmartFilter, name: string, disableOptimization = false, disableStrategy = BlockDisableStrategy.AutoSample) {
-        super(smartFilter, name, disableOptimization);
-        this.blockDisableStrategy = disableStrategy;
+    public override getShaderProgram() {
+        const shaderProgram = super.getShaderProgram();
 
         // If we haven't already modified the shader code for this block type, do so now
         if (!this._hasModifiedShaderCode) {
             this._hasModifiedShaderCode = true;
 
             // Apply the disable strategy
-            const shaderProgram = this.getShaderProgram();
             switch (this.blockDisableStrategy) {
                 case BlockDisableStrategy.AutoSample:
                     InjectAutoSampleDisableCode(shaderProgram);
                     break;
             }
         }
+
+        return shaderProgram;
+    }
+
+    /**
+     * Instantiates a new block.
+     * @param smartFilter - Defines the smart filter the block belongs to
+     * @param name - Defines the name of the block
+     * @param disableOptimization - Defines if the block should not be optimized (default: false)
+     * @param disableStrategy - Defines the strategy to use for making this block disableable (default: BlockDisableStrategy.AutoSample)
+     */
+    constructor(smartFilter: SmartFilter, name: string, disableOptimization = false, disableStrategy = BlockDisableStrategy.AutoSample) {
+        super(smartFilter, name, disableOptimization);
+        this.blockDisableStrategy = disableStrategy;
     }
 }

package/src/editorUtils/editableInPropertyPage.ts

@@ -53,6 +53,11 @@ export interface IEditablePropertyOption {
     valuesAreStrings?: boolean;
     /** If supplied, the sub property to read/write */
     subPropertyName?: string;
+    /**
+     * If supplied, scope this to a specific block type - useful for the
+     * CustomShaderBlock where multiple block types are implemented with the same class
+     */
+    blockType?: string;
 }
 
 /**
@@ -94,13 +99,22 @@ export function EditableInPropertyPage(
             target._propStore = propStore;
         }
 
-        propStore.push({
+        const propToAdd: IPropertyDescriptionForEdition = {
             propertyName: propertyKey,
             displayName: displayName,
             type: propertyType,
             groupName: groupName,
             options: options ?? {},
             className: target.constructor.name,
-        });
+        };
+
+        // If the property already exists, overwrite it, otherwise add it
+        // Note: It may have been redefined since the application started
+        const existingIndex = propStore.findIndex((p) => p.propertyName === propertyKey && p.className === target.constructor.name && options?.blockType === p.options?.blockType);
+        if (existingIndex !== -1) {
+            propStore[existingIndex] = propToAdd;
+        } else {
+            propStore.push(propToAdd);
+        }
     };
 }

package/src/optimization/smartFilterOptimizer.ts

@@ -243,8 +243,8 @@ export class SmartFilterOptimizer {
         return newVarName;
     }
 
-    private _processDefines(block: ShaderBlock, renameWork: RenameWork) {
-        const defines = block.getShaderProgram().fragment.defines;
+    private _processDefines(block: ShaderBlock, shaderProgram: ShaderProgram, renameWork: RenameWork) {
+        const defines = shaderProgram.fragment.defines;
         if (!defines) {
             return;
         }
@@ -292,11 +292,12 @@ export class SmartFilterOptimizer {
      * folded into the final optimized block.
      * NOTE: so this function can know about the uniforms to test for them, it must be called after _processVariables.
      * @param block - The block we are processing
+     * @param shaderProgram - The shader program associated with the block
      * @param renameWork - The list of rename work to add to as needed
      * @param samplerList - The list of sampler names
      */
-    private _processHelperFunctions(block: ShaderBlock, renameWork: RenameWork, samplerList: string[]): void {
-        const functions = block.getShaderProgram().fragment.functions;
+    private _processHelperFunctions(block: ShaderBlock, shaderProgram: ShaderProgram, renameWork: RenameWork, samplerList: string[]): void {
+        const functions = shaderProgram.fragment.functions;
 
         if (functions.length === 1) {
             // There's only the main function, so we don't need to do anything
@@ -306,7 +307,7 @@ export class SmartFilterOptimizer {
         for (const func of functions) {
             let funcName = func.name;
 
-            if (funcName === block.getShaderProgram().fragment.mainFunctionName) {
+            if (funcName === shaderProgram.fragment.mainFunctionName) {
                 continue;
             }
 
@@ -381,19 +382,29 @@ export class SmartFilterOptimizer {
         }
     }
 
+    /**
+     * Processes either consts or uniforms. Handles capturing the rename work needed, updating the sampler list, and
+     * accounting for single instance situations (where a const or uniform is shared across all instances of this block).
+     * @param block - The block to work on
+     * @param renameWork - The RenameWork list to update
+     * @param varDecl - Which type of variable we're working with
+     * @param declarations - The declarations of those variables from the shader
+     * @param sharedByAllInstances - If this should be treated as a shared value across all instances of this shader block
+     * @returns The list of samplers
+     */
     private _processVariables(
         block: ShaderBlock,
         renameWork: RenameWork,
         varDecl: "const" | "uniform",
-        declarations?: string,
-        hasValue = false,
-        forceSingleInstance = false
+        declarations: string | undefined,
+        sharedByAllInstances: boolean
     ): Array<string> {
         if (!declarations) {
             return [];
         }
 
         let rex = `${varDecl}\\s+(\\S+)\\s+${DecorateChar}(\\w+)${DecorateChar}\\s*`;
+        const hasValue = varDecl !== "uniform";
         if (hasValue) {
             rex += "=\\s*(.+);";
         } else {
@@ -405,7 +416,6 @@ export class SmartFilterOptimizer {
 
         let match = rx.exec(declarations);
         while (match !== null) {
-            const singleInstance = forceSingleInstance || varDecl === "const";
             const varType = match[1]!;
             const varName = match[2]!;
             const varValue = hasValue ? match[3]! : null;
@@ -416,7 +426,7 @@ export class SmartFilterOptimizer {
                 samplerList.push(DecorateSymbol(varName));
             } else {
                 const existingRemapped = this._remappedSymbols.find((s) => s.type === varDecl && s.name === varName && s.owners[0] && s.owners[0].blockType === block.blockType);
-                if (existingRemapped && singleInstance) {
+                if (existingRemapped && sharedByAllInstances) {
                     newVarName = existingRemapped.remappedName;
                     if (varDecl === "uniform") {
                         existingRemapped.owners.push(block);
@@ -486,13 +496,13 @@ export class SmartFilterOptimizer {
         return UndecorateSymbol(newSamplerName);
     }
 
-    private _canBeOptimized(block: BaseBlock): boolean {
+    private _canBeOptimized(block: BaseBlock, shaderProgram: ShaderProgram): boolean {
         if (block.disableOptimization) {
             return false;
         }
 
         if (block instanceof ShaderBlock) {
-            if (block.getShaderProgram().vertex !== this._vertexShaderCode) {
+            if (shaderProgram.vertex !== this._vertexShaderCode) {
                 return false;
             }
 
@@ -517,6 +527,7 @@ export class SmartFilterOptimizer {
             this._currentOutputTextureOptions = block.outputTextureOptions;
         }
 
+        // Sometimes getShaderProgram() does work, so only grab it once for efficiency
         const shaderProgram = block.getShaderProgram();
         if (!shaderProgram) {
             throw new Error(`Shader program not found for block "${block.name}"!`);
@@ -546,22 +557,25 @@ export class SmartFilterOptimizer {
         }
 
         // Processes the defines to make them unique
-        this._processDefines(block, renameWork);
+        this._processDefines(block, shaderProgram, renameWork);
 
         // Processes the constants to make them unique
         this._processVariables(block, renameWork, "const", shaderProgram.fragment.const, true);
 
+        // Processes the per-instance constants
+        this._processVariables(block, renameWork, "const", shaderProgram.fragment.constPerInstance, false);
+
         // Processes the uniform inputs to make them unique. Also extract the list of samplers
         let samplerList: string[] = [];
         samplerList = this._processVariables(block, renameWork, "uniform", shaderProgram.fragment.uniform, false);
 
         let additionalSamplers = [];
-        additionalSamplers = this._processVariables(block, renameWork, "uniform", shaderProgram.fragment.uniformSingle, false, true);
+        additionalSamplers = this._processVariables(block, renameWork, "uniform", shaderProgram.fragment.uniformSingle, true);
 
         samplerList.push(...additionalSamplers);
 
         // Processes the functions other than the main function - must be done after _processVariables()
-        this._processHelperFunctions(block, renameWork, samplerList);
+        this._processHelperFunctions(block, shaderProgram, renameWork, samplerList);
 
         // Processes the texture inputs
         for (const sampler of samplerList) {
@@ -589,7 +603,7 @@ export class SmartFilterOptimizer {
             if (IsTextureInputBlock(parentBlock)) {
                 // input is connected to an InputBlock of type "Texture": we must directly sample a texture
                 this._processSampleTexture(block, renameWork, samplerName, samplers, parentBlock);
-            } else if (this._forceUnoptimized || !this._canBeOptimized(parentBlock)) {
+            } else if (this._forceUnoptimized || !this._canBeOptimized(parentBlock, shaderProgram)) {
                 // the block connected to this input cannot be optimized: we must directly sample its output texture
                 const uniqueSamplerName = this._processSampleTexture(block, renameWork, samplerName, samplers);
                 let stackItem = this._blockToStackItem.get(parentBlock);

package/src/serialization/importCustomBlockDefinition.ts

@@ -81,6 +81,7 @@ function ImportAnnotatedGlsl(fragmentShader: string): SerializedShaderBlockDefin
             fragment: fragmentShaderInfo.shaderCode,
         },
         inputConnectionPoints,
+        fragmentConstProperties: fragmentShaderInfo.fragmentConstProperties,
         disableOptimization: !!fragmentShaderInfo.disableOptimization,
     };
 }

package/src/serialization/smartFilterSerializer.ts

@@ -7,6 +7,7 @@ import { OutputBlock } from "../blockFoundation/outputBlock.js";
 import type { IBlockSerializerV1, ISerializedBlockV1, ISerializedConnectionV1, SerializeBlockV1, SerializedSmartFilterV1 } from "./v1/smartFilterSerialization.types.js";
 import { CustomShaderBlock } from "../blockFoundation/customShaderBlock.js";
 import { CustomAggregateBlock } from "../blockFoundation/customAggregateBlock.js";
+import { CustomShaderBlockSerializer } from "../blockFoundation/customShaderBlock.serializer.js";
 
 /**
  * Determines if two serialized connection points are equivalent to each other
@@ -54,9 +55,11 @@ export class SmartFilterSerializer {
             // Serialize the block itself
             const blockClassName = block.getClassName();
             const serializeFn =
-                blockClassName === CustomShaderBlock.ClassName || blockClassName === CustomAggregateBlock.ClassName
-                    ? DefaultBlockSerializer
-                    : this._blockSerializers.get(block.blockType);
+                blockClassName === CustomShaderBlock.ClassName
+                    ? CustomShaderBlockSerializer
+                    : blockClassName === CustomAggregateBlock.ClassName
+                      ? DefaultBlockSerializer
+                      : this._blockSerializers.get(block.blockType);
             if (!serializeFn) {
                 throw new Error(`No serializer was provided for a block of type ${block.blockType}`);
             }

package/src/serialization/v1/shaderBlockSerialization.types.ts

@@ -8,6 +8,43 @@ import type { Nullable } from "core/types.js";
 import type { AllConnectionPointTypes, ConnectionPointValue } from "../../connection/connectionPointType.js";
 import type { ShaderProgram } from "../../utils/shaderCodeUtils.js";
 
+/**
+ * Description of a const property exposed by a shader block.
+ */
+type ConstPropertyMetadataBase = {
+    /**
+     * The name of the const in the shader code
+     */
+    name: string;
+
+    /**
+     * A friendly name for the property to be displayed in the Smart Filters Editor UI.
+     * This is the undecorated name of the const in the shader code.
+     */
+    friendlyName: string;
+
+    /**
+     * The type of the property
+     */
+    type: string;
+};
+
+type ConstPropertyMetadataFloat = ConstPropertyMetadataBase & {
+    type: "float";
+
+    /**
+     * The default value of the property
+     */
+    defaultValue: number;
+
+    /**
+     * Optional mapping of values to strings to be displayed in the Smart Filters Editor UI for this property.
+     */
+    options?: { [key: string]: number };
+};
+
+export type ConstPropertyMetadata = ConstPropertyMetadataFloat;
+
 /**
  * The V1 definition of a serialized shader block. This block definition is loaded by a CustomShaderBlock and defines how a
  * blockType works. This should not be confused with an ISerializedBockV1, which is a serialized instance of a block in a
@@ -48,6 +85,11 @@ export type SerializedShaderBlockDefinitionV1 = {
      */
     inputConnectionPoints: SerializedInputConnectionPointV1[];
 
+    /**
+     * Properties which map to consts in the fragment shader.
+     */
+    fragmentConstProperties?: ConstPropertyMetadata[];
+
     /**
      * If true, the optimizer will not attempt to optimize this block.
      */

package/src/utils/buildTools/shaderCode.types.ts

@@ -1,59 +1,65 @@
-/**
- * Describes a shader function.
- */
-export type ShaderFunction = {
-    /**
-     * The name of the function.
-     */
-    name: string;
-
-    /**
-     * The code of the function.
-     */
-    code: string;
-
-    /**
-     * The parameters of the function.
-     */
-    params?: string;
-};
-
-/**
- * Describes a shader code.
- */
-export type ShaderCode = {
-    /**
-     * The declaration of the const variables.
-     */
-    const?: string;
-
-    /**
-     * The declaration of the uniform variables.
-     */
-    uniform?: string;
-
-    /**
-     * The declaration of the uniform variables that should be common for all ShaderBlock instances using this shader code.
-     */
-    uniformSingle?: string;
-
-    /**
-     * The name of the main function.
-     */
-    mainFunctionName: string;
-
-    /**
-     * The name of the input texture which is passed through if the block is disabled.
-     */
-    mainInputTexture?: string;
-
-    /**
-     * The list of functions used in the shader.
-     */
-    functions: ShaderFunction[];
-
-    /**
-     * The declaration of define statements.
-     */
-    defines?: string[];
-};
+/**
+ * Describes a shader function.
+ */
+export type ShaderFunction = {
+    /**
+     * The name of the function.
+     */
+    name: string;
+
+    /**
+     * The code of the function.
+     */
+    code: string;
+
+    /**
+     * The parameters of the function.
+     */
+    params?: string;
+};
+
+/**
+ * Describes a shader code.
+ */
+export type ShaderCode = {
+    /**
+     * The declaration of the const variables.
+     */
+    const?: string;
+
+    /**
+     * The declaration of const variables which can be modified by each instance of the block using
+     * this ShaderCode. The optimizer will not consolidate when there are multiple instances of the same block.
+     */
+    constPerInstance?: string;
+
+    /**
+     * The declaration of the uniform variables.
+     */
+    uniform?: string;
+
+    /**
+     * The declaration of the uniform variables that should be common for all ShaderBlock instances using this shader code.
+     */
+    uniformSingle?: string;
+
+    /**
+     * The name of the main function.
+     */
+    mainFunctionName: string;
+
+    /**
+     * The name of the input texture which is passed through if the block is disabled.
+     */
+    mainInputTexture?: string;
+
+    /**
+     * The list of functions used in the shader.
+     */
+    functions: ShaderFunction[];
+
+    /**
+     * The declaration of define statements.
+     */
+    defines?: string[];
+};