@onerjs/smart-filters 8.25.0

package/src/blockFoundation/customShaderBlock.ts

@@ -0,0 +1,362 @@
+import { Logger } from "core/Misc/logger.js";
+import type { Effect } from "core/Materials/effect.js";
+import { ConnectionPointType, type ConnectionPointValue } from "../connection/connectionPointType.js";
+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 { SmartFilter } from "../smartFilter.js";
+import 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";
+
+/**
+ * The binding for a CustomShaderBlock
+ */
+class CustomShaderBlockBinding extends ShaderBinding {
+    private readonly _bindSteps: ((effect: Effect, width: number, height: number) => void)[] = [];
+
+    /**
+     * Creates a new shader binding instance for the CustomShaderBlock block.
+     * @param inputsWithRuntimeData - The input connection points of the block
+     */
+    public constructor(inputsWithRuntimeData: AnyInputWithRuntimeData[]) {
+        super();
+
+        for (const input of inputsWithRuntimeData) {
+            switch (input.type) {
+                case ConnectionPointType.Float:
+                    this._bindSteps.push((effect) => {
+                        effect.setFloat(this.getRemappedName(input.name), input.runtimeData.value);
+                    });
+                    break;
+                case ConnectionPointType.Texture:
+                    this._bindSteps.push((effect) => {
+                        effect.setTexture(this.getRemappedName(input.name), input.runtimeData.value);
+                    });
+                    break;
+                case ConnectionPointType.Color3:
+                    this._bindSteps.push((effect) => {
+                        effect.setColor3(this.getRemappedName(input.name), input.runtimeData.value);
+                    });
+                    break;
+                case ConnectionPointType.Color4:
+                    this._bindSteps.push((effect) => {
+                        effect.setDirectColor4(this.getRemappedName(input.name), input.runtimeData.value);
+                    });
+                    break;
+                case ConnectionPointType.Boolean:
+                    this._bindSteps.push((effect) => {
+                        effect.setBool(this.getRemappedName(input.name), input.runtimeData.value);
+                    });
+                    break;
+                case ConnectionPointType.Vector2:
+                    switch (input.autoBind) {
+                        case "outputResolution":
+                            this._bindSteps.push((effect, width, height) => {
+                                effect.setFloat2(this.getRemappedName(input.name), width, height);
+                            });
+                            break;
+                        case "outputAspectRatio":
+                            this._bindSteps.push((effect, width, height) => {
+                                effect.setFloat2(this.getRemappedName(input.name), width / height, height / width);
+                            });
+                            break;
+                        default:
+                            this._bindSteps.push((effect) => {
+                                effect.setVector2(this.getRemappedName(input.name), input.runtimeData.value);
+                            });
+                    }
+                    break;
+            }
+        }
+    }
+
+    /**
+     * Binds all the required data to the shader when rendering.
+     * @param effect - The effect to bind the data to
+     * @param width - defines the width of the output
+     * @param height - defines the height of the output
+     */
+    public override bind(effect: Effect, width: number, height: number): void {
+        for (let i = 0; i < this._bindSteps.length; i++) {
+            this._bindSteps[i]!(effect, width, height);
+        }
+    }
+}
+
+/**
+ * A block which loads a SerializedBlockDefinition for use in a SmartFilter.
+ */
+export class CustomShaderBlock extends ShaderBlock {
+    /**
+     * Deserializes a CustomShaderBlock from a serialized block definition.
+     * @param smartFilter - The smart filter this block belongs to
+     * @param name - Defines the name of the block
+     * @param blockDefinition - The serialized block definition
+     * @returns The deserialized CustomShaderBlock instance
+     */
+    public static Create(smartFilter: SmartFilter, name: string, blockDefinition: SerializedShaderBlockDefinition): CustomShaderBlock {
+        // When a new version of SerializedBlockDefinition is created, this function should be updated to handle the new properties.
+
+        return new CustomShaderBlock(
+            smartFilter,
+            name,
+            blockDefinition.disableOptimization,
+            blockDefinition.blockType,
+            blockDefinition.namespace,
+            blockDefinition.inputConnectionPoints,
+            blockDefinition.shaderProgram
+        );
+    }
+
+    /**
+     * The class name of the block.
+     */
+    public static override ClassName = "CustomShaderBlock";
+
+    private readonly _shaderProgram: ShaderProgram;
+    private readonly _blockType: string;
+    private readonly _namespace: Nullable<string>;
+    private _autoBoundInputs: Nullable<SerializedInputConnectionPointV1[]> = null;
+
+    /**
+     * The type of the block - used when serializing / deserializing the block, and in the editor.
+     */
+    public override get blockType(): string {
+        return this._blockType;
+    }
+
+    /**
+     * The namespace of the block, which is used to reduce name collisions between blocks and also to group blocks in the editor UI.
+     * By convention, sub namespaces are separated by a period (e.g. "Babylon.Demo.Effects").
+     */
+    public override get namespace(): Nullable<string> {
+        return this._namespace;
+    }
+
+    /**
+     * Instantiates a new custom shader block.
+     * @param smartFilter - The smart filter this block belongs to
+     * @param name - The name of the block
+     * @param disableOptimization - If true, this optimizer will not attempt to optimize this block
+     * @param blockType - The type of the block
+     * @param namespace - The namespace of the block
+     * @param inputConnectionPoints - The input connection points of the
+     * @param shaderProgram - The shader program for the block
+     */
+    private constructor(
+        smartFilter: SmartFilter,
+        name: string,
+        disableOptimization: boolean,
+        blockType: string,
+        namespace: Nullable<string>,
+        inputConnectionPoints: SerializedInputConnectionPointV1[],
+        shaderProgram: ShaderProgram
+    ) {
+        super(smartFilter, name, disableOptimization);
+        this._blockType = blockType;
+        this._namespace = namespace;
+
+        for (const input of inputConnectionPoints) {
+            this._registerSerializedInputConnectionPointV1(input);
+        }
+
+        this._shaderProgram = shaderProgram;
+    }
+
+    /**
+     * 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;
+    }
+
+    /**
+     * Checks a specific input connection point type to see if it has a default value, and registers the input
+     * connection point accordingly.
+     * @param connectionPoint - The input connection point to register
+     */
+    private _registerSerializedInputConnectionPointV1<U extends ConnectionPointType>(connectionPoint: SerializedInputConnectionPointV1<U>): void {
+        if (connectionPoint.autoBind) {
+            // Auto bound inputs are not registered as input connection points
+            if (this._autoBoundInputs === null) {
+                this._autoBoundInputs = [];
+            }
+            this._autoBoundInputs.push(connectionPoint);
+        } else {
+            // If not auto bound, register as an input connection point
+            const defaultValue = this._validateDefaultValue(connectionPoint.type, connectionPoint.name, connectionPoint.defaultValue);
+            if (defaultValue != null) {
+                this._registerOptionalInput(connectionPoint.name, connectionPoint.type, CreateStrongRef(defaultValue));
+            } else {
+                this._registerInput(connectionPoint.name, connectionPoint.type);
+            }
+        }
+    }
+
+    /**
+     * Gets the shader binding for the custom shader block.
+     * @returns The shader binding for the custom shader block
+     */
+    public override getShaderBinding(): ShaderBinding {
+        const inputs = this.inputs;
+
+        const inputsToBind: AnyInputWithRuntimeData[] = inputs.map((input) => {
+            return {
+                name: input.name,
+                type: input.type,
+                runtimeData: this._confirmRuntimeDataSupplied(input),
+                autoBind: undefined,
+            };
+        });
+
+        if (this._autoBoundInputs) {
+            for (const autoBoundInput of this._autoBoundInputs) {
+                if (
+                    (autoBoundInput.autoBind === "outputResolution" && autoBoundInput.type == ConnectionPointType.Vector2) ||
+                    (autoBoundInput.autoBind === "outputAspectRatio" && autoBoundInput.type == ConnectionPointType.Vector2)
+                ) {
+                    inputsToBind.push({
+                        name: autoBoundInput.name,
+                        type: autoBoundInput.type,
+                        autoBind: autoBoundInput.autoBind,
+                    });
+                } else {
+                    throw new Error(`Auto bound input ${autoBoundInput.name} has an unsupported type or auto bind value`);
+                }
+            }
+        }
+
+        return new CustomShaderBlockBinding(inputsToBind);
+    }
+
+    /**
+     * Validates the default value of a connection point and returns it if valid.
+     * If the default value is not provided or is invalid, this returns null.
+     * @param connectionPointType - The type of the connection point
+     * @param connectionPointName - The name of the connection point
+     * @param defaultValue - The default value of the connection point
+     * @returns The default value, or null if no default value is provided or it was invalid
+     */
+    private _validateDefaultValue<U extends ConnectionPointType>(
+        connectionPointType: U,
+        connectionPointName: string,
+        defaultValue?: ConnectionPointValue<U>
+    ): Nullable<ConnectionPointValue<U>> {
+        if (defaultValue === undefined || defaultValue === null) {
+            return null;
+        }
+
+        // Validate the default value based on the connection point type
+        let returnValue: Nullable<ConnectionPointValue<U>> = null;
+        switch (connectionPointType) {
+            case ConnectionPointType.Float:
+                returnValue = typeof defaultValue === "number" ? defaultValue : null;
+                break;
+            case ConnectionPointType.Color3:
+                returnValue = typeof defaultValue === "object" && "r" in defaultValue && "g" in defaultValue && "b" in defaultValue ? defaultValue : null;
+                break;
+            case ConnectionPointType.Color4:
+                returnValue = typeof defaultValue === "object" && "r" in defaultValue && "g" in defaultValue && "b" in defaultValue && "a" in defaultValue ? defaultValue : null;
+                break;
+            case ConnectionPointType.Boolean:
+                returnValue = typeof defaultValue === "boolean" ? defaultValue : null;
+                break;
+            case ConnectionPointType.Vector2:
+                returnValue = typeof defaultValue === "object" && "x" in defaultValue && "y" in defaultValue ? defaultValue : null;
+                break;
+            default: {
+                Logger.Warn(`Default value supplied when unsupported. Block Type: "${this.blockType}" Connection Point: "${connectionPointName}"`);
+                return null;
+            }
+        }
+
+        if (returnValue === null) {
+            Logger.Warn(`Invalid default value. Block Type: "${this.blockType}" Connection Point: "${connectionPointName}"`);
+        }
+
+        return returnValue;
+    }
+}
+
+/**
+ * Represents an input with its runtime data, enforcing type safety.
+ */
+type InputWithRuntimeData<U extends ConnectionPointType> = {
+    /**
+     * The name of the input connection point
+     */
+    name: string;
+
+    /**
+     * The type of the input connection point
+     */
+    type: U;
+
+    /**
+     * The runtime data for the input connection point
+     */
+    runtimeData: RuntimeData<U>;
+
+    /**
+     * Since this is an input connection point, it will not be auto bound
+     */
+    autoBind: undefined;
+};
+
+/**
+ * Represents an input which is auto-bound to the output resolution instead of an input connection point
+ */
+type AutoBindOutputResolution = {
+    /**
+     * The name of the input
+     */
+    name: string;
+
+    /**
+     * The type of the input
+     */
+    type: ConnectionPointType.Vector2;
+
+    /**
+     * The auto bind value for the input connection point
+     */
+    autoBind: "outputResolution";
+};
+
+/**
+ * Represents an input which is auto-bound to the output's aspect ratio instead of an input connection point.
+ * The x value is the aspect ratio (width / height) and the y value is the inverse aspect ratio (height / width).
+ */
+type AutoBindOutputAspectRatio = {
+    /**
+     * The name of the input
+     */
+    name: string;
+
+    /**
+     * The type of the input
+     */
+    type: ConnectionPointType.Vector2;
+
+    /**
+     * The auto bind value for the input connection point
+     */
+    autoBind: "outputAspectRatio";
+};
+
+/**
+ * All possible input types with runtime data.
+ */
+type AnyInputWithRuntimeData =
+    | InputWithRuntimeData<ConnectionPointType.Boolean>
+    | InputWithRuntimeData<ConnectionPointType.Color3>
+    | InputWithRuntimeData<ConnectionPointType.Color4>
+    | InputWithRuntimeData<ConnectionPointType.Float>
+    | InputWithRuntimeData<ConnectionPointType.Texture>
+    | InputWithRuntimeData<ConnectionPointType.Vector2>
+    | AutoBindOutputResolution
+    | AutoBindOutputAspectRatio;

package/src/blockFoundation/disableableShaderBlock.ts

@@ -0,0 +1,91 @@
+import type { SmartFilter } from "../smartFilter.js";
+import type { ConnectionPoint } from "../connection/connectionPoint.js";
+
+import { ConnectionPointType } from "../connection/connectionPointType.js";
+import { CreateStrongRef } from "../runtime/strongRef.js";
+import { ShaderBlock } from "./shaderBlock.js";
+import { InjectAutoSampleDisableCode } from "../utils/shaderCodeUtils.js";
+
+/**
+ * The interface that describes the disableable block.
+ */
+export interface IDisableableBlock {
+    /**
+     * The disabled connection point of the block.
+     */
+    disabled: ConnectionPoint<ConnectionPointType.Boolean>;
+}
+
+/**
+ * The strategy to use for making a block disableable.
+ */
+export enum BlockDisableStrategy {
+    /**
+     * The shader code is responsible for defining and consulting a uniform named disabled
+     * and no-oping (returning texture2D(mainInputTexture, vUV)) if the value is true.
+     */
+    Manual = 0,
+
+    /**
+     * The Smart Filter system will automatically add code to sample the mainInputTexture and return immediately if disabled,
+     * and otherwise use the value within the block's shader code. If you need to modify UVs before sampling the default input texture,
+     * you'll need to use the Manual strategy instead.
+     */
+    AutoSample = 1,
+}
+
+/**
+ * A ShaderBlock that can be disabled. The optimizer can optionally remove disabled blocks from the graph,
+ * or they can be controlled by the disabled connection point at runtime. If disabled, they pass the
+ * mainInputTexture through to the output connection point.
+ */
+export abstract class DisableableShaderBlock extends ShaderBlock implements IDisableableBlock {
+    /**
+     * The disabled connection point of the block.
+     */
+    public readonly disabled = this._registerOptionalInput("disabled", ConnectionPointType.Boolean, CreateStrongRef(false));
+
+    /**
+     * The strategy to use for making this block disableable.
+     */
+    public readonly blockDisableStrategy: BlockDisableStrategy;
+
+    // The shader code is a static per block type. When an instance of a block is created, we may need to alter
+    // that code based on the block's disable strategy. We only want to do this once per block type, or we could
+    // incorrectly modify the shader code multiple times (once per block instance). Here we use a static boolean
+    // which will be per block type to track if we've already modified the shader code for this block type.
+    // This is more memory efficient than the alternative of making a copy of the shader code for each block instance
+    // and modifying each copy.
+    private static _HasModifiedShaderCode = false;
+    private get _hasModifiedShaderCode() {
+        return (this.constructor as typeof DisableableShaderBlock)._HasModifiedShaderCode;
+    }
+    private set _hasModifiedShaderCode(value: boolean) {
+        (this.constructor as typeof DisableableShaderBlock)._HasModifiedShaderCode = value;
+    }
+
+    /**
+     * 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;
+
+        // 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;
+            }
+        }
+    }
+}

package/src/blockFoundation/index.ts

@@ -0,0 +1,9 @@
+export { BaseBlock } from "./baseBlock.js";
+export { InputBlock, type InputBlockEditorData } from "./inputBlock.js";
+export { type AnyInputBlock } from "./inputBlock.js";
+export { ShaderBlock } from "./shaderBlock.js";
+export { CustomShaderBlock } from "./customShaderBlock.js";
+export { CustomAggregateBlock } from "./customAggregateBlock.js";
+export { DisableableShaderBlock, BlockDisableStrategy } from "./disableableShaderBlock.js";
+export { AggregateBlock } from "./aggregateBlock.js";
+export { type IDisableableBlock } from "./disableableShaderBlock.js";

package/src/blockFoundation/inputBlock.deserializer.ts

@@ -0,0 +1,72 @@
+import { InputBlock } from "./inputBlock.js";
+import type { SerializedInputBlockData } from "./inputBlock.serialization.types.js";
+import { ConnectionPointType } from "../connection/connectionPointType.js";
+import type { SmartFilter } from "../smartFilter.js";
+import type { ISerializedBlockV1 } from "../serialization/v1/smartFilterSerialization.types.js";
+
+/**
+ * V1 Input Block Deserializer
+ * @param smartFilter - The SmartFilter to deserialize the block into
+ * @param serializedBlock - The serialized block data
+ * @returns A deserialized InputBlock
+ */
+export function InputBlockDeserializer(smartFilter: SmartFilter, serializedBlock: ISerializedBlockV1) {
+    const blockData = serializedBlock.data as SerializedInputBlockData;
+    let inputBlock;
+
+    switch (blockData.inputType) {
+        case ConnectionPointType.Boolean:
+            {
+                inputBlock = new InputBlock(smartFilter, serializedBlock.name, ConnectionPointType.Boolean, blockData.value);
+            }
+            break;
+        case ConnectionPointType.Float:
+            {
+                inputBlock = new InputBlock(smartFilter, serializedBlock.name, ConnectionPointType.Float, blockData.value);
+                inputBlock.editorData = {
+                    animationType: blockData.animationType,
+                    valueDeltaPerMs: blockData.valueDeltaPerMs,
+                    min: blockData.min,
+                    max: blockData.max,
+                };
+            }
+            break;
+        case ConnectionPointType.Texture:
+            {
+                // Create the input block
+                inputBlock = new InputBlock(smartFilter, serializedBlock.name, ConnectionPointType.Texture, null);
+
+                // If editor data was serialized, set it on the deserialized block
+                inputBlock.editorData = {
+                    url: blockData.url,
+                    urlTypeHint: blockData.urlTypeHint,
+                    anisotropicFilteringLevel: blockData.anisotropicFilteringLevel,
+                    flipY: blockData.flipY,
+                    forcedExtension: blockData.forcedExtension,
+                };
+            }
+            break;
+        case ConnectionPointType.Color3:
+            {
+                inputBlock = new InputBlock(smartFilter, serializedBlock.name, ConnectionPointType.Color3, blockData.value);
+            }
+            break;
+        case ConnectionPointType.Color4:
+            {
+                inputBlock = new InputBlock(smartFilter, serializedBlock.name, ConnectionPointType.Color4, blockData.value);
+            }
+            break;
+        case ConnectionPointType.Vector2:
+            {
+                inputBlock = new InputBlock(smartFilter, serializedBlock.name, ConnectionPointType.Vector2, blockData.value);
+            }
+            break;
+    }
+    if (inputBlock) {
+        inputBlock.appMetadata = blockData.appMetadata;
+
+        return inputBlock;
+    }
+
+    throw new Error("Could not deserialize input block, unknown input type");
+}

package/src/blockFoundation/inputBlock.serialization.types.ts

@@ -0,0 +1,126 @@
+import type { Nullable } from "core/types.js";
+import type { ConnectionPointType } from "../connection/connectionPointType.js";
+import type { IColor3Like, IColor4Like, IVector2Like } from "core/Maths/math.like.js";
+
+/**
+ * Data that all serialized InputBlocks share
+ */
+export type CommonInputBlockData = {
+    /**
+     * Metadata the hosting app wants to track for this input. For example, a hint for what data to
+     * assign to this input, or hints about how to draw dynamic UI to allow users to control this value.
+     */
+    appMetadata: unknown;
+};
+
+/**
+ * The data for an InputBlock for ConnectionPointType.Texture inputs
+ */
+export type TextureInputBlockData = CommonInputBlockData & {
+    /** The type of the input block */
+    inputType: ConnectionPointType.Texture;
+
+    /** The URL, if available, of the texture */
+    url: Nullable<string>;
+
+    /**
+     * If supplied, gives a hint as to which type of texture the URL points to.
+     * Default is assumed to be "image"
+     */
+    urlTypeHint: Nullable<"image" | "video">;
+
+    /**
+     * Defines the anisotropic level to use, or default if null
+     */
+    anisotropicFilteringLevel: Nullable<number>;
+
+    /**
+     * Indicates if the Y axis should be flipped, or default if null
+     */
+    flipY: Nullable<boolean>;
+
+    /**
+     * The file extension to use, or default if null.
+     */
+    forcedExtension: Nullable<string>;
+};
+
+/**
+ * The data for an InputBlock for ConnectionPointType.Boolean inputs
+ */
+export type BooleanInputBlockData = CommonInputBlockData & {
+    /** The type of the input block */
+    inputType: ConnectionPointType.Boolean;
+
+    /** The value of the input block */
+    value: boolean;
+};
+
+/**
+ * The data for an InputBlock for ConnectionPointType.Float inputs
+ */
+export type FloatInputBlockData = CommonInputBlockData & {
+    /** The type of the input block */
+    inputType: ConnectionPointType.Float;
+
+    /** The value of the input block */
+    value: number;
+
+    /**
+     * If supplied, how this should be animated by the editor.  Will not affect runtime behavior.
+     */
+    animationType: Nullable<"time">;
+
+    /**
+     * If supplied, the amount to change the value per millisecond when animating.
+     */
+    valueDeltaPerMs: Nullable<number>;
+
+    /**
+     * The minimum value of the float, used for slider control.
+     */
+    min: Nullable<number>;
+
+    /**
+     * The maximum value of the float, used for slider control.
+     */
+    max: Nullable<number>;
+};
+
+/**
+ * The data for an InputBlock for ConnectionPointType.Color3 inputs
+ */
+export type Color3InputBlockData = CommonInputBlockData & {
+    /** The type of the input block */
+    inputType: ConnectionPointType.Color3;
+
+    /** The value of the input block */
+    value: IColor3Like;
+};
+
+/**
+ * The data for an InputBlock for ConnectionPointType.Color4 inputs
+ */
+export type Color4InputBlockData = CommonInputBlockData & {
+    /** The type of the input block */
+    inputType: ConnectionPointType.Color4;
+
+    /** The value of the input block */
+    value: IColor4Like;
+};
+
+/**
+ * The data for an InputBlock for ConnectionPointType.Vector2 inputs
+ */
+export type Vector2InputBlockData = CommonInputBlockData & {
+    /** The type of the input block */
+    inputType: ConnectionPointType.Vector2;
+
+    /** The value of the input block */
+    value: IVector2Like;
+};
+
+/**
+ * Type union of all possible InputBlock data types
+ */
+export type SerializedInputBlockData = TextureInputBlockData | BooleanInputBlockData | FloatInputBlockData | Color3InputBlockData | Color4InputBlockData | Vector2InputBlockData;