@babylonjs/smart-filters 0.2.0-alpha → 0.3.1-alpha

package/src/serialization/smartFilterDeserializer.ts

@@ -0,0 +1,127 @@
+import type { BaseBlock } from "../blocks/baseBlock";
+import type { SerializedSmartFilter } from "./serializedSmartFilter.js";
+import { SmartFilter } from "../smartFilter.js";
+import { inputBlockDeserializer } from "../blocks/inputBlock.deserializer.js";
+import { OutputBlock } from "../blocks/outputBlock.js";
+import type { ThinEngine } from "@babylonjs/core/Engines/thinEngine";
+import { InputBlock } from "../blocks/inputBlock.js";
+import type {
+    DeserializeBlockV1,
+    ISerializedBlockV1,
+    ISerializedConnectionV1,
+    SerializedSmartFilterV1,
+} from "./v1/serialization.types";
+import { UniqueIdGenerator } from "../utils/uniqueIdGenerator.js";
+
+/**
+ * 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 _blockDeserializersV1: Map<string, DeserializeBlockV1> = new Map();
+
+    /**
+     * Creates a new SmartFilterDeserializer
+     * @param blockDeserializers - The map of block serializers to use, beyond those for the core blocks
+     */
+    public constructor(blockDeserializers: Map<string, DeserializeBlockV1>) {
+        this._blockDeserializersV1 = blockDeserializers;
+
+        // Add in the core block deserializers - they are not delay loaded, so they are wrapped in Promise.resolve()
+        this._blockDeserializersV1.set(
+            InputBlock.ClassName,
+            (smartFilter: SmartFilter, serializedBlock: ISerializedBlockV1, engine: ThinEngine) =>
+                Promise.resolve(inputBlockDeserializer(smartFilter, serializedBlock, engine))
+        );
+
+        this._blockDeserializersV1.set(OutputBlock.ClassName, (smartFilter: SmartFilter) =>
+            Promise.resolve(smartFilter.output.ownerBlock)
+        );
+    }
+
+    /**
+     * 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
+     */
+    public async deserialize(engine: ThinEngine, smartFilterJson: any): Promise<SmartFilter> {
+        const serializedSmartFilter: SerializedSmartFilter = smartFilterJson;
+        switch (serializedSmartFilter.version) {
+            case 1:
+                return await this._deserializeV1(engine, serializedSmartFilter);
+        }
+    }
+
+    private async _deserializeV1(
+        engine: ThinEngine,
+        serializedSmartFilter: SerializedSmartFilterV1
+    ): Promise<SmartFilter> {
+        const smartFilter = new SmartFilter(serializedSmartFilter.name);
+        const blockMap = new Map<string, BaseBlock>();
+
+        // Deserialize the SmartFilter level data
+        smartFilter.comments = serializedSmartFilter.comments;
+        smartFilter.editorData = serializedSmartFilter.editorData;
+
+        // Deserialize the blocks
+        const blockDeserializationWork: Promise<void>[] = [];
+        serializedSmartFilter.blocks.forEach((serializedBlock: ISerializedBlockV1) => {
+            const blockDeserializer = this._blockDeserializersV1.get(serializedBlock.className);
+            if (!blockDeserializer) {
+                throw new Error(`No deserializer found for block type ${serializedBlock.className}`);
+            }
+            blockDeserializationWork.push(
+                blockDeserializer(smartFilter, serializedBlock, engine).then((newBlock) => {
+                    // 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;
+
+                    // 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
+                    blockMap.set(newBlock.name, newBlock);
+                })
+            );
+        });
+        await Promise.all(blockDeserializationWork);
+
+        // Deserialize the connections
+        serializedSmartFilter.connections.forEach((connection: ISerializedConnectionV1) => {
+            // Find the source block and its connection point's connectTo function
+            const sourceBlock = blockMap.get(connection.outputBlock);
+            if (!sourceBlock) {
+                throw new Error(`Source block ${connection.outputBlock} not found`);
+            }
+            const sourceConnectionPoint = (sourceBlock as any)[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 = blockMap.get(connection.inputBlock);
+            if (!targetBlock) {
+                throw new Error(`Target block ${connection.inputBlock} not found`);
+            }
+            const targetConnectionPoint = (targetBlock as any)[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;
+    }
+}

package/src/serialization/smartFilterSerializer.ts

@@ -0,0 +1,113 @@
+import type { SmartFilter } from "../smartFilter";
+import type { BaseBlock } from "../blocks/baseBlock";
+import { inputBlockSerializer } from "../blocks/inputBlock.serializer.js";
+import type { ConnectionPoint } from "../connection/connectionPoint";
+import { defaultBlockSerializer } from "./v1/defaultBlockSerializer.js";
+import { OutputBlock } from "../blocks/outputBlock.js";
+import type {
+    IBlockSerializerV1,
+    ISerializedBlockV1,
+    ISerializedConnectionV1,
+    SerializeBlockV1,
+    SerializedSmartFilterV1,
+} from "./v1/serialization.types";
+
+/**
+ * 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 classNames 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.className, inputBlockSerializer.serialize);
+        this._blockSerializers.set(OutputBlock.ClassName, defaultBlockSerializer);
+        blocksUsingDefaultSerialization.forEach((block) => {
+            this._blockSerializers.set(block, defaultBlockSerializer);
+        });
+        additionalBlockSerializers.forEach((serializer) =>
+            this._blockSerializers.set(serializer.className, 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 serializeFn = this._blockSerializers.get(block.getClassName());
+            if (!serializeFn) {
+                throw new Error(`No serializer was provided for a block of type ${block.getClassName()}`);
+            }
+            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.name,
+                        inputConnectionPoint: input.name,
+                        outputBlock: connectedTo.ownerBlock.name,
+                        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.name,
+                        inputConnectionPoint: input.name,
+                        outputBlock: block.name,
+                        outputConnectionPoint: output.name,
+                    };
+                    if (!connections.find((other) => serializedConnectionPointsEqual(newConnection, other))) {
+                        connections.push(newConnection);
+                    }
+                });
+            });
+
+            return serializedBlock;
+        });
+
+        return {
+            version: 1,
+            name: smartFilter.name,
+            comments: smartFilter.comments,
+            editorData: smartFilter.editorData,
+            blocks,
+            connections,
+        };
+    }
+}

package/src/serialization/v1/defaultBlockSerializer.ts

@@ -0,0 +1,18 @@
+import type { BaseBlock } from "../../blocks/baseBlock";
+import type { ISerializedBlockV1, SerializeBlockV1 } from "./serialization.types";
+
+/**
+ * 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,
+        className: block.getClassName(),
+        comments: block.comments,
+        data: undefined,
+    };
+};

package/src/serialization/v1/index.ts

@@ -0,0 +1,2 @@
+export * from "./defaultBlockSerializer.js";
+export * from "./serialization.types.js";

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

@@ -0,0 +1,108 @@
+import type { Nullable } from "@babylonjs/core/types.js";
+import type { BaseBlock } from "../../blocks/baseBlock.js";
+import type { SmartFilter } from "../../smartFilter.js";
+import type { ThinEngine } from "@babylonjs/core/Engines/thinEngine";
+import type { IEditorData } from "@babylonjs/shared-ui-components/nodeGraphSystem/interfaces/nodeLocationInfo.js";
+
+/**
+ * ----------------------------------------------------------------------------
+ * Serialized Data Types
+ * ----------------------------------------------------------------------------
+ */
+
+/**
+ * V1 Serialized Smart Filter
+ */
+export type SerializedSmartFilterV1 = {
+    /** The version of the serialized data */
+    version: 1;
+
+    /** The SmartFilter name */
+    name: 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 Serialized Block
+ */
+export interface ISerializedBlockV1 {
+    /** The name of the block */
+    name: string;
+
+    /** The unique ID of the block - correlates with the ID in the editorData for block position, etc. */
+    uniqueId: number;
+
+    /** The class name of the block */
+    className: string;
+
+    /** The comments for the block */
+    comments: Nullable<string>;
+
+    /** Block specific serialized data */
+    data: any;
+}
+
+/**
+ * V1 Serialized Connection
+ */
+export interface ISerializedConnectionV1 {
+    /** The name of the block that the connection is to */
+    outputBlock: string;
+
+    /** The name of the connectionPoint on the outputBlock */
+    outputConnectionPoint: string;
+
+    /** The name of the block that the connection is from */
+    inputBlock: string;
+
+    /** 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 block serializer
+ */
+export interface IBlockSerializerV1 {
+    /** The className of the block that this serializer can serialize */
+    className: string;
+
+    /** The function that serializes the block */
+    serialize: SerializeBlockV1;
+}
+
+/**
+ * ----------------------------------------------------------------------------
+ * Deserializer Types
+ * ----------------------------------------------------------------------------
+ */
+
+/**
+ * A function that deserializes a block from a V1 serialized block object
+ */
+export type DeserializeBlockV1 = (
+    smartFilter: SmartFilter,
+    serializedBlock: ISerializedBlockV1,
+    engine: ThinEngine
+) => Promise<BaseBlock>;

package/src/smartFilter.ts

@@ -8,6 +8,7 @@ import { OutputBlock } from "./blocks/outputBlock.js";
 import { InternalSmartFilterRuntime } from "./runtime/smartFilterRuntime.js";
 import { RenderTargetGenerator } from "./runtime/renderTargetGenerator.js";
 import { AggregateBlock } from "./blocks/aggregateBlock.js";
+import type { IEditorData } from "@babylonjs/shared-ui-components/nodeGraphSystem/interfaces/nodeLocationInfo";
 
 /**
  * How long to wait for shader compilation and texture loading to complete before erroring out.
@@ -61,9 +62,8 @@ export class SmartFilter {
 
     /**
      * Data used by the smart filter editor.
-     * TODO. strong type and hide this.
      */
-    public editorData: any = null;
+    public editorData: Nullable<IEditorData> = null;
 
     private readonly _attachedBlocks: Array<BaseBlock>;
     private readonly _outputBlock: OutputBlock;
@@ -216,12 +216,14 @@ export class SmartFilter {
             }
         });
 
-        // Do the passed in work
-        work();
-
-        // Restore all aggregate blocks
-        for (const block of mergedAggregateBlocks) {
-            block._unmergeFromSmartFilter();
+        try {
+            // Do the passed in work
+            work();
+        } finally {
+            // Restore all aggregate blocks, even if work throws
+            for (const block of mergedAggregateBlocks) {
+                block._unmergeFromSmartFilter();
+            }
         }
     }
 }

package/src/utils/buildTools/determineVersion.ts

@@ -0,0 +1,127 @@
+import type { Nullable } from "@babylonjs/core/types";
+import type { ExecException } from "child_process";
+
+/**
+ * Determines if the major and minor versions of two semver strings match
+ * @param version1 - The first semver string
+ * @param version2 - The second semver string
+ * @returns True if the major and minor versions match, false otherwise
+ */
+function majorAndMinorVersionsMatch(version1: string, version2: string): boolean {
+    const version1split = version1.split(".");
+    const version2split = version2.split(".");
+    return version1split[0] === version2split[0] && version1split[1] === version2split[1];
+}
+
+/**
+ * Takes in a semver string (e.g. "0.1.0") and increments the patch version.
+ * Note: it does not preserve any prerelease flags in the patch version.
+ * @param version - The semver string to operate on
+ * @returns The incremented version string
+ */
+function incrementPatchVersion(version: string): string {
+    const spl = version.split(".");
+    if (spl.length < 3) {
+        throw new Error("version string must have at least 3 parts");
+    }
+    spl[spl.length - 1] = (Number.parseInt(spl[spl.length - 1]!) + 1).toString();
+    return spl.join(".");
+}
+
+/**
+ * Takes in a semver string (e.g. "0.1.0" or "0.1.0-alpha") and removes any prerelease flag.
+ * @param version - The semver string to operate on
+ * @returns The version string with the prerelease flag removed
+ */
+export function removePrereleaseFlags(version: string): string {
+    const spl = version.split(".");
+    if (spl.length < 3) {
+        throw new Error("version string must have at least 3 parts");
+    }
+    spl[spl.length - 1] = Number.parseInt(spl[spl.length - 1]!).toString();
+    return spl.join(".");
+}
+
+/**
+ * Given the npmVersion, packageJSONVersion, and alpha flag, determines the version to use
+ * @param npmVersion - The version from the NPM registry
+ * @param packageJSONVersion - The version from the package.json file
+ * @param alpha - A flag to indicate if the version should have an alpha prerelease flag
+ * @returns The version to use
+ */
+export function determineVersion(npmVersion: Nullable<string>, packageJSONVersion: string, alpha: boolean): string {
+    packageJSONVersion = removePrereleaseFlags(packageJSONVersion);
+    npmVersion = npmVersion === null ? null : removePrereleaseFlags(npmVersion);
+
+    let versionToUse;
+    if (npmVersion === null || !majorAndMinorVersionsMatch(npmVersion, packageJSONVersion)) {
+        console.log("Major & minor versions do not match: using the current package.json version");
+        versionToUse = packageJSONVersion;
+    } else {
+        console.log("Major & minor versions match: using the NPM registry version with an incremented patch version.");
+        versionToUse = incrementPatchVersion(npmVersion);
+    }
+
+    if (alpha) {
+        console.log("Ensuring -alpha prerelease flag is present");
+        versionToUse += "-alpha";
+    }
+
+    return versionToUse;
+}
+
+/**
+ * The supported version types
+ */
+export type VersionType = "preview" | "latest";
+
+/**
+ * Handles error cases and returns the JSON of the package versions
+ * @param versionType - The type of version to get
+ * @param err - The error object
+ * @param stdout - The stdout string
+ * @returns The JSON of the package versions
+ */
+export function getNpmVersion(
+    versionType: VersionType,
+    err: Nullable<ExecException>,
+    stdout: string
+): Nullable<string> {
+    let npmVersion = null;
+    if (err?.message && err.message.indexOf("E404") !== -1) {
+        console.warn(`NPM registry does not have any ${versionType} version`);
+    } else if (err) {
+        console.error(err);
+        throw err;
+    } else {
+        npmVersion = stdout;
+    }
+    return npmVersion;
+}
+
+/**
+ * Compares two semver strings, returning -1 if version1 is less than version2, 1 if version1 is greater than version2, and 0 if they are equal
+ * @param version1 - The first semver string
+ * @param version2 - The second semver string
+ * @returns -1 if version1 is less than version2, 1 if version1 is greater than version2, and 0 if they are equal
+ */
+export function compareVersions(version1: string, version2: string): number {
+    const version1split = removePrereleaseFlags(version1).split(".");
+    const version2split = removePrereleaseFlags(version2).split(".");
+
+    if (version1split.length !== 3 || version2split.length !== 3) {
+        throw new Error("version strings must have 3 parts");
+    }
+
+    for (let i = 0; i < 3; i++) {
+        const v1 = Number.parseInt(version1split[i]!);
+        const v2 = Number.parseInt(version2split[i]!);
+
+        if (v1 < v2) {
+            return -1;
+        } else if (v1 > v2) {
+            return 1;
+        }
+    }
+    return 0;
+}