@onerjs/smart-filters 8.25.0

package/src/serialization/smartFilterDeserializer.ts

@@ -0,0 +1,190 @@
+import type { BaseBlock } from "../blockFoundation/baseBlock.js";
+import type { SerializedSmartFilter } from "./serializedSmartFilter.js";
+import { SmartFilter } from "../smartFilter.js";
+import { ShaderBlock } from "../blockFoundation/shaderBlock.js";
+import { InputBlockDeserializer } from "../blockFoundation/inputBlock.deserializer.js";
+import { OutputBlock } from "../blockFoundation/outputBlock.js";
+import type { ThinEngine } from "core/Engines/thinEngine.js";
+import { InputBlock } from "../blockFoundation/inputBlock.js";
+import type { ISerializedBlockV1, ISerializedConnectionV1, OptionalBlockDeserializerV1, SerializedSmartFilterV1 } from "./v1/smartFilterSerialization.types.js";
+import { UniqueIdGenerator } from "../utils/uniqueIdGenerator.js";
+import type { Nullable } from "core/types.js";
+
+/**
+ * A function that creates a block instance of the given class block type, or return null if it cannot.
+ */
+export type BlockFactory = (
+    smartFilter: SmartFilter,
+    engine: ThinEngine,
+    serializedBlock: ISerializedBlockV1,
+    smartFilterDeserializer: SmartFilterDeserializer
+) => Promise<Nullable<BaseBlock>>;
+
+/**
+ * Deserializes serialized SmartFilters. The caller passes in a map of block deserializers it wants to use,
+ * which allows the caller to provide custom deserializers for blocks beyond the core blocks.
+ * The deserializer supports versioned serialized SmartFilters.
+ */
+export class SmartFilterDeserializer {
+    private readonly _blockFactory: BlockFactory;
+    private readonly _customInputBlockDeserializer?: OptionalBlockDeserializerV1;
+
+    /**
+     * Creates a new SmartFilterDeserializer
+     * @param blockFactory - A function that creates a block of the given class name, or returns null if it cannot
+     * @param customInputBlockDeserializer - An optional custom deserializer for InputBlocks - if supplied and it returns null, the default deserializer will be used
+     */
+    public constructor(blockFactory: BlockFactory, customInputBlockDeserializer?: OptionalBlockDeserializerV1) {
+        this._blockFactory = blockFactory;
+        this._customInputBlockDeserializer = customInputBlockDeserializer;
+    }
+
+    /**
+     * Deserializes a SmartFilter from a JSON object - can be safely called multiple times and has no side effects within the class.
+     * @param engine - The ThinEngine to pass to the new SmartFilter
+     * @param smartFilterJson - The JSON object to deserialize
+     * @returns A promise that resolves to the deserialized SmartFilter
+     */
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    public async deserialize(engine: ThinEngine, smartFilterJson: any): Promise<SmartFilter> {
+        const serializedSmartFilter: SerializedSmartFilter = smartFilterJson;
+
+        // Back-compat for the rename of version to formatVersion, didn't warrant a new version
+        if ((serializedSmartFilter as any).version && serializedSmartFilter.formatVersion === undefined) {
+            serializedSmartFilter.formatVersion = (serializedSmartFilter as any).version;
+        }
+
+        switch (serializedSmartFilter.formatVersion) {
+            case 1:
+                return await this._deserializeV1Async(engine, serializedSmartFilter);
+        }
+    }
+
+    private async _deserializeV1Async(engine: ThinEngine, serializedSmartFilter: SerializedSmartFilterV1): Promise<SmartFilter> {
+        const smartFilter = new SmartFilter(serializedSmartFilter.name, serializedSmartFilter.namespace);
+        const blockIdMap = new Map<number, BaseBlock>();
+
+        // Only needed for smart filters saved before we started using uniqueIds for the maps, didn't warrant new version
+        const blockNameMap = new Map<string, BaseBlock>();
+
+        // Deserialize the SmartFilter level data
+        smartFilter.comments = serializedSmartFilter.comments;
+        smartFilter.editorData = serializedSmartFilter.editorData;
+
+        // Deserialize the blocks
+        const blockDeserializationWork: Promise<void>[] = [];
+        const blockDefinitionsWhichCouldNotBeDeserialized: string[] = [];
+        serializedSmartFilter.blocks.forEach((serializedBlock: ISerializedBlockV1) => {
+            blockDeserializationWork.push(
+                this._deserializeBlockV1Async(smartFilter, serializedBlock, engine, blockDefinitionsWhichCouldNotBeDeserialized, blockIdMap, blockNameMap)
+            );
+        });
+        await Promise.all(blockDeserializationWork);
+
+        // If any block definitions could not be deserialized, throw an error
+        if (blockDefinitionsWhichCouldNotBeDeserialized.length > 0) {
+            throw new Error(`Could not deserialize the following block definitions: ${blockDefinitionsWhichCouldNotBeDeserialized.join(", ")}`);
+        }
+
+        // Deserialize the connections
+        serializedSmartFilter.connections.forEach((connection: ISerializedConnectionV1) => {
+            // Find the source block and its connection point's connectTo function
+            const sourceBlock = typeof connection.outputBlock === "string" ? blockNameMap.get(connection.outputBlock) : blockIdMap.get(connection.outputBlock);
+
+            if (!sourceBlock) {
+                throw new Error(`Source block ${connection.outputBlock} not found`);
+            }
+            const sourceConnectionPoint = sourceBlock.outputs.find((output) => output.name === connection.outputConnectionPoint);
+            if (!sourceConnectionPoint || typeof sourceConnectionPoint.connectTo !== "function") {
+                throw new Error(`Block ${connection.outputBlock} does not have an connection point named ${connection.outputConnectionPoint}`);
+            }
+            const sourceConnectToFunction = sourceConnectionPoint.connectTo.bind(sourceConnectionPoint);
+
+            // Find the target block and its connection point
+            const targetBlock = typeof connection.inputBlock === "string" ? blockNameMap.get(connection.inputBlock) : blockIdMap.get(connection.inputBlock);
+            if (!targetBlock) {
+                throw new Error(`Target block ${connection.inputBlock} not found`);
+            }
+
+            const targetConnectionPoint = targetBlock.inputs.find((input) => input.name === connection.inputConnectionPoint);
+            if (!targetConnectionPoint || typeof targetConnectionPoint !== "object") {
+                throw new Error(`Block ${connection.inputBlock} does not have a connection point named ${connection.inputConnectionPoint}`);
+            }
+
+            // Create the connection
+            sourceConnectToFunction.call(sourceBlock, targetConnectionPoint);
+        });
+
+        return smartFilter;
+    }
+
+    private async _deserializeBlockV1Async(
+        smartFilter: SmartFilter,
+        serializedBlock: ISerializedBlockV1,
+        engine: ThinEngine,
+        blockTypesWhichCouldNotBeDeserialized: string[],
+        blockIdMap: Map<number, BaseBlock>,
+        blockNameMap: Map<string, BaseBlock>
+    ): Promise<void> {
+        let newBlock: Nullable<BaseBlock> = null;
+
+        // Back compat for early Smart Filter V1 serialization where the blockType was stored in className
+        // Not worth creating a new version for this, as it's only used in the deserializer
+        if ((serializedBlock as any).className && !serializedBlock.blockType) {
+            serializedBlock.blockType = (serializedBlock as any).className;
+        }
+
+        // Back compat for early Smart Filter V1 serialization where the namespace was not stored
+        if (serializedBlock.namespace === undefined) {
+            serializedBlock.namespace = null;
+        }
+
+        // Get the instance of the block
+        switch (serializedBlock.blockType) {
+            case InputBlock.ClassName:
+                {
+                    if (this._customInputBlockDeserializer) {
+                        newBlock = await this._customInputBlockDeserializer(smartFilter, serializedBlock, engine);
+                    }
+                    if (newBlock === null) {
+                        newBlock = InputBlockDeserializer(smartFilter, serializedBlock);
+                    }
+                }
+                break;
+            case OutputBlock.ClassName:
+                {
+                    newBlock = smartFilter.output.ownerBlock;
+                }
+                break;
+            default: {
+                // If it's not an input or output block, use the provided block factory
+                newBlock = await this._blockFactory(smartFilter, engine, serializedBlock, this);
+                if (!newBlock) {
+                    if (blockTypesWhichCouldNotBeDeserialized.indexOf(serializedBlock.blockType) === -1) {
+                        blockTypesWhichCouldNotBeDeserialized.push(serializedBlock.blockType);
+                    }
+                    return;
+                }
+            }
+        }
+
+        // Deserializers are not responsible for setting the uniqueId or comments.
+        // This is so they don't have to be passed into the constructors when programmatically creating
+        // blocks, and so each deserializer doesn't have to remember to do it.
+        newBlock.uniqueId = serializedBlock.uniqueId;
+        newBlock.comments = serializedBlock.comments;
+
+        // Deserializers are also not responsible for deserializing the outputTextureOptions of ShaderBlocks.
+        if (serializedBlock.outputTextureOptions && newBlock instanceof ShaderBlock) {
+            newBlock.outputTextureOptions = serializedBlock.outputTextureOptions;
+        }
+
+        // We need to ensure any uniqueIds generated in the future (e.g. a new block is added to the SmartFilter)
+        // are higher than this one.
+        UniqueIdGenerator.EnsureIdsGreaterThan(newBlock.uniqueId);
+
+        // Save in the map
+        blockIdMap.set(newBlock.uniqueId, newBlock);
+        blockNameMap.set(newBlock.name, newBlock);
+    }
+}

package/src/serialization/smartFilterSerializer.ts

@@ -0,0 +1,110 @@
+import type { SmartFilter } from "../smartFilter.js";
+import type { BaseBlock } from "../blockFoundation/baseBlock.js";
+import { InputBlockSerializer } from "../blockFoundation/inputBlock.serializer.js";
+import type { ConnectionPoint } from "../connection/connectionPoint.js";
+import { DefaultBlockSerializer } from "./v1/defaultBlockSerializer.js";
+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";
+
+/**
+ * Determines if two serialized connection points are equivalent to each other
+ * @param a - The first connection point to compare
+ * @param b - The second connection point to compare
+ * @returns True if the connection points are equivalent, false otherwise
+ */
+function SerializedConnectionPointsEqual(a: ISerializedConnectionV1, b: ISerializedConnectionV1): boolean {
+    return (
+        a.inputBlock === b.inputBlock && a.inputConnectionPoint === b.inputConnectionPoint && a.outputBlock === b.outputBlock && a.outputConnectionPoint === b.outputConnectionPoint
+    );
+}
+
+/**
+ * Serializes SmartFilters using the latest SmartFilter serialization version.
+ * The caller passes in information necessary to serialize the blocks in the SmartFilter.
+ * This allows the caller to provide custom serializers for blocks beyond the core blocks.
+ */
+export class SmartFilterSerializer {
+    private readonly _blockSerializers: Map<string, SerializeBlockV1> = new Map();
+
+    /**
+     * Creates a new SmartFilterSerializer
+     * @param blocksUsingDefaultSerialization - A list of the blockType of blocks which can use default serialization (they only have ConnectionPoint properties and no constructor parameters)
+     * @param additionalBlockSerializers - An array of block serializers to use, beyond those for the core blocks
+     */
+    public constructor(blocksUsingDefaultSerialization: string[], additionalBlockSerializers: IBlockSerializerV1[]) {
+        this._blockSerializers.set(InputBlockSerializer.blockType, InputBlockSerializer.serialize);
+        this._blockSerializers.set(OutputBlock.ClassName, DefaultBlockSerializer);
+        blocksUsingDefaultSerialization.forEach((block) => {
+            this._blockSerializers.set(block, DefaultBlockSerializer);
+        });
+        additionalBlockSerializers.forEach((serializer) => this._blockSerializers.set(serializer.blockType, serializer.serialize));
+    }
+
+    /**
+     * Serializes a SmartFilter to a JSON object of the latest version
+     * @param smartFilter - The SmartFilter to serialize
+     * @returns The serialized SmartFilter
+     */
+    public serialize(smartFilter: SmartFilter): SerializedSmartFilterV1 {
+        const connections: ISerializedConnectionV1[] = [];
+
+        const blocks = smartFilter.attachedBlocks.map((block: BaseBlock) => {
+            // Serialize the block itself
+            const blockClassName = block.getClassName();
+            const serializeFn =
+                blockClassName === CustomShaderBlock.ClassName || 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}`);
+            }
+            const serializedBlock: ISerializedBlockV1 = serializeFn(block);
+
+            // Serialize the connections to the inputs
+            block.inputs.forEach((input: ConnectionPoint) => {
+                const connectedTo = input.connectedTo;
+                if (connectedTo) {
+                    const newConnection: ISerializedConnectionV1 = {
+                        inputBlock: block.uniqueId,
+                        inputConnectionPoint: input.name,
+                        outputBlock: connectedTo.ownerBlock.uniqueId,
+                        outputConnectionPoint: connectedTo.name,
+                    };
+                    if (!connections.find((other) => SerializedConnectionPointsEqual(newConnection, other))) {
+                        connections.push(newConnection);
+                    }
+                }
+            });
+
+            // Serialize the connections to the outputs
+            block.outputs.forEach((output: ConnectionPoint) => {
+                output.endpoints.forEach((input: ConnectionPoint) => {
+                    const newConnection: ISerializedConnectionV1 = {
+                        inputBlock: input.ownerBlock.uniqueId,
+                        inputConnectionPoint: input.name,
+                        outputBlock: block.uniqueId,
+                        outputConnectionPoint: output.name,
+                    };
+                    if (!connections.find((other) => SerializedConnectionPointsEqual(newConnection, other))) {
+                        connections.push(newConnection);
+                    }
+                });
+            });
+
+            return serializedBlock;
+        });
+
+        return {
+            format: "smartFilter",
+            formatVersion: 1,
+            name: smartFilter.name,
+            namespace: smartFilter.namespace,
+            comments: smartFilter.comments,
+            editorData: smartFilter.editorData,
+            blocks,
+            connections,
+        };
+    }
+}

package/src/serialization/v1/defaultBlockSerializer.ts

@@ -0,0 +1,21 @@
+import { ShaderBlock } from "../../blockFoundation/shaderBlock.js";
+import type { BaseBlock } from "../../blockFoundation/baseBlock.js";
+import type { ISerializedBlockV1, SerializeBlockV1 } from "./smartFilterSerialization.types.js";
+
+/**
+ * The default V1 block serializer which can be used for any block that relies only on ConnectionPoints
+ * and does not have any constructor parameters or class properties that need to be serialized.
+ * @param block - The block to serialize
+ * @returns The serialized block
+ */
+export const DefaultBlockSerializer: SerializeBlockV1 = (block: BaseBlock): ISerializedBlockV1 => {
+    return {
+        name: block.name,
+        uniqueId: block.uniqueId,
+        blockType: block.blockType,
+        namespace: block.namespace,
+        comments: block.comments,
+        data: undefined,
+        outputTextureOptions: block instanceof ShaderBlock ? block.outputTextureOptions : undefined,
+    };
+};

package/src/serialization/v1/index.ts

@@ -0,0 +1,4 @@
+export * from "./defaultBlockSerializer.js";
+// Back compat for when camelCase was used
+export { DefaultBlockSerializer as defaultBlockSerializer } from "./defaultBlockSerializer.js";
+export * from "./smartFilterSerialization.types.js";

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

@@ -0,0 +1,85 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Data Types Used For Block Serialization
+ * ----------------------------------------------------------------------------
+ */
+
+import type { Nullable } from "core/types.js";
+import type { AllConnectionPointTypes, ConnectionPointValue } from "../../connection/connectionPointType.js";
+import type { ShaderProgram } from "../../utils/shaderCodeUtils.js";
+
+/**
+ * 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
+ * serialized SmartFilter graph. It is referenced by blockType in a serialized SmartFilter.
+ */
+export type SerializedShaderBlockDefinitionV1 = {
+    /**
+     * Which type of serialized data this is.
+     */
+    format: "shaderBlockDefinition";
+
+    /**
+     * The version of the block definition format (format of the serialized data, not the version of the block definition itself).
+     */
+    formatVersion: 1;
+
+    /**
+     * The type used to refer to the block in serialized SmartFilters and in the editor UI.
+     * The application doing the deserialization will use this to instantiate the correct block definition.
+     * Block types are expected to be unique and their behavior should be semantically equivalent across implementations
+     * (their results must be similar enough that the differences are not perceivable).
+     */
+    blockType: string;
+
+    /**
+     * 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").
+     */
+    namespace: Nullable<string>;
+
+    /**
+     * The shader program for the block.
+     */
+    shaderProgram: ShaderProgram;
+
+    /**
+     * The input connection points of the block.
+     */
+    inputConnectionPoints: SerializedInputConnectionPointV1[];
+
+    /**
+     * If true, the optimizer will not attempt to optimize this block.
+     */
+    disableOptimization: boolean;
+};
+
+/**
+ * Possible V1 auto bind values for input connection points.
+ */
+export type InputAutoBindV1 = "outputResolution" | "outputAspectRatio";
+
+/**
+ * A V1 input connection point of a serialized block definition.
+ */
+export type SerializedInputConnectionPointV1<U extends AllConnectionPointTypes = AllConnectionPointTypes> = {
+    /**
+     * The name of the connection point.
+     */
+    name: string;
+
+    /**
+     * The type of the connection point.
+     */
+    type: U;
+
+    /**
+     * The optional default value of the connection point.
+     */
+    defaultValue?: ConnectionPointValue<U>;
+
+    /**
+     * If supplied, the input will be automatically bound to this value, instead of creating an input connection point.
+     */
+    autoBind?: InputAutoBindV1;
+};

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

@@ -0,0 +1,129 @@
+import type { Nullable } from "core/types.js";
+import type { BaseBlock } from "../../blockFoundation/baseBlock.js";
+import type { SmartFilter } from "../../smartFilter.js";
+import type { ThinEngine } from "core/Engines/thinEngine.js";
+import type { IEditorData } from "shared-ui-components/nodeGraphSystem/interfaces/nodeLocationInfo.js";
+import type { SmartFilterDeserializer } from "../smartFilterDeserializer.js";
+import type { OutputTextureOptions } from "../../blockFoundation/textureOptions.js";
+
+/**
+ * ----------------------------------------------------------------------------
+ * Serialized Data Types
+ * ----------------------------------------------------------------------------
+ */
+
+/**
+ * V1 Serialized Smart Filter
+ */
+export type SerializedSmartFilterV1 = {
+    /** Which type of serialized data this is. */
+    format: "smartFilter";
+
+    /** The format version of the serialized data (not the version of the SmartFilter itself).*/
+    formatVersion: 1;
+
+    /** The SmartFilter name */
+    name: string;
+
+    /** The namespace of the SmartFilter */
+    namespace: Nullable<string>;
+
+    /** The SmartFilter comments */
+    comments: Nullable<string>;
+
+    /** The editor data for the SmartFilter */
+    editorData: Nullable<IEditorData>;
+
+    /** The serialized blocks */
+    blocks: ISerializedBlockV1[];
+
+    /** The serialized connections */
+    connections: ISerializedConnectionV1[];
+};
+
+/**
+ * V1 format of a block in a serialized Smart Filter.
+ * Not to be confused with a SerializedBlockDefinitionV1 which serializes the definition of a CustomShaderBlock.
+ */
+export interface ISerializedBlockV1 {
+    /** The name of the block */
+    name: string;
+
+    /** The namespace of the block */
+    namespace: Nullable<string>;
+
+    /** The unique ID of the block - correlates with the ID in the editorData for block position, etc. */
+    uniqueId: number;
+
+    /** The blockType of the block - used to determine how to instantiate the block during deserialization */
+    blockType: string;
+
+    /** The comments for the block */
+    comments: Nullable<string>;
+
+    /** The OutputTextureOptions for serialized ShaderBlocks */
+    outputTextureOptions?: OutputTextureOptions;
+
+    /** Block specific serialized data */
+    data: any;
+}
+
+/**
+ * V1 Serialized Connection
+ */
+export interface ISerializedConnectionV1 {
+    /** The uniqueId of the block that the connection is to */
+    outputBlock: number;
+
+    /** The name of the connectionPoint on the outputBlock */
+    outputConnectionPoint: string;
+
+    /** The uniqueId of the block that the connection is from */
+    inputBlock: number;
+
+    /** The name of the connectionPoint on the inputBlock */
+    inputConnectionPoint: string;
+}
+
+/**
+ * ----------------------------------------------------------------------------
+ * Serializer Types
+ * ----------------------------------------------------------------------------
+ */
+
+/**
+ * A function that serializes a block to a V1 serialized block object
+ */
+export type SerializeBlockV1 = (block: BaseBlock) => ISerializedBlockV1;
+
+/**
+ * A V1 serializer for blocks in a SmartFilter
+ */
+export interface IBlockSerializerV1 {
+    /** The blockType of the block that this serializer can serialize */
+    blockType: string;
+
+    /** The function that serializes the block in the Smart Filter */
+    serialize: SerializeBlockV1;
+}
+
+/**
+ * ----------------------------------------------------------------------------
+ * Deserializer Types
+ * ----------------------------------------------------------------------------
+ */
+
+/**
+ * A function that deserializes a V1 block in a SmartFilter
+ */
+export type DeserializeBlockV1 = (
+    smartFilter: SmartFilter,
+    serializedBlock: ISerializedBlockV1,
+    engine: ThinEngine,
+    smartFilterDeserializer: SmartFilterDeserializer
+) => Promise<BaseBlock>;
+
+/**
+ * A function that optionally deserializes a block from a V1 serialized block object, returning null if it cannot
+ */
+export type OptionalBlockDeserializerV1 = (smartFilter: SmartFilter, serializedBlock: ISerializedBlockV1, engine: ThinEngine) => Promise<Nullable<BaseBlock>>;