@babylonjs/smart-filters 0.5.0-alpha → 0.6.1-alpha

package/src/optimization/smartFilterOptimizer.ts

@@ -267,7 +267,7 @@ export class SmartFilterOptimizer {
                     s.type === "function" &&
                     s.name === funcName &&
                     s.owners[0] &&
-                    s.owners[0].getClassName() === block.getClassName()
+                    s.owners[0].blockType === block.blockType
             );
 
             const newVarName = existingRemapped?.remappedName ?? decorateSymbol(this._makeSymbolUnique(funcName));
@@ -335,7 +335,7 @@ export class SmartFilterOptimizer {
                         s.type === varDecl &&
                         s.name === varName &&
                         s.owners[0] &&
-                        s.owners[0].getClassName() === block.getClassName()
+                        s.owners[0].blockType === block.blockType
                 );
                 if (existingRemapped && singleInstance) {
                     newVarName = existingRemapped.remappedName;
@@ -591,7 +591,7 @@ export class SmartFilterOptimizer {
             return newShaderFuncName;
         }
 
-        throw `Unhandled block type! className=${block.getClassName()}`;
+        throw `Unhandled block type! blockType=${block.blockType}`;
     }
 
     private _saveBlockStackState(): void {

package/src/serialization/importCustomShaderBlockDefinition.ts

@@ -0,0 +1,85 @@
+import { ConnectionPointType } from "../connection/connectionPointType.js";
+import { hasGlslHeader, parseFragmentShader } from "../utils/buildTools/shaderConverter.js";
+import type { SerializedBlockDefinition } from "./serializedBlockDefinition.js";
+import type { SerializedInputConnectionPointV1 } from "./v1/blockSerialization.types.js";
+
+/**
+ * Imports a serialized custom shader block definition. Supports importing a JSON string
+ * of an SerializedBlockDefinition object, or a glsl shader with the required annotations
+ * so it can be converted to a SerializedBlockDefinition object.
+ * See readme.md for more information.
+ * @param serializedBlockDefinition - The serialized block definition - either a SerializedBlockDefinition object in a JSON string, or an annotated glsl shader
+ * @returns The serialized block definition
+ */
+export function importCustomShaderBlockDefinition(serializedBlockDefinition: string): SerializedBlockDefinition {
+    if (hasGlslHeader(serializedBlockDefinition)) {
+        return importAnnotatedGlsl(serializedBlockDefinition);
+    } else {
+        // Assume this is a serialized SerializedBlockDefinition object
+        return JSON.parse(serializedBlockDefinition);
+    }
+}
+
+/**
+ * Converts a fragment shader .glsl file to an SerializedBlockDefinition instance for use
+ * as a CustomShaderBlock. The .glsl file must contain certain annotations to be imported.
+ * See readme.md for more information.
+ * @param fragmentShader - The contents of the .glsl fragment shader file
+ * @returns The serialized block definition
+ */
+function importAnnotatedGlsl(fragmentShader: string): SerializedBlockDefinition {
+    const fragmentShaderInfo = parseFragmentShader(fragmentShader);
+
+    if (!fragmentShaderInfo.blockType) {
+        throw new Error("blockType must be defined");
+    }
+
+    // Calculate the input connection points
+    const inputConnectionPoints: SerializedInputConnectionPointV1[] = [];
+    for (const uniform of fragmentShaderInfo.uniforms) {
+        // Convert to ConnectionPointType
+        let type: ConnectionPointType;
+        switch (uniform.type) {
+            case "float":
+                type = ConnectionPointType.Float;
+                break;
+            case "sampler2D":
+                type = ConnectionPointType.Texture;
+                break;
+            case "vec3":
+                type = ConnectionPointType.Color3;
+                break;
+            case "vec4":
+                type = ConnectionPointType.Color4;
+                break;
+            case "bool":
+                type = ConnectionPointType.Boolean;
+                break;
+            case "vec2":
+                type = ConnectionPointType.Vector2;
+                break;
+            default:
+                throw new Error(`Unsupported uniform type: '${uniform.type}'`);
+        }
+
+        // Add to input connection point list
+        const inputConnectionPoint: SerializedInputConnectionPointV1 = {
+            name: uniform.name,
+            type,
+        };
+        if (inputConnectionPoint.type !== ConnectionPointType.Texture && uniform.properties?.default !== undefined) {
+            inputConnectionPoint.defaultValue = uniform.properties.default;
+        }
+        inputConnectionPoints.push(inputConnectionPoint);
+    }
+
+    return {
+        formatVersion: 1,
+        blockType: fragmentShaderInfo.blockType,
+        shaderProgram: {
+            fragment: fragmentShaderInfo.shaderCode,
+        },
+        inputConnectionPoints,
+        disableOptimization: !!fragmentShaderInfo.disableOptimization,
+    };
+}

package/src/serialization/index.ts

@@ -2,3 +2,4 @@ export * from "./v1/index.js";
 export * from "./serializedSmartFilter.js";
 export * from "./smartFilterDeserializer.js";
 export * from "./smartFilterSerializer.js";
+export * from "./serializedBlockDefinition.js";

package/src/serialization/serializedBlockDefinition.ts

@@ -0,0 +1,7 @@
+import type { SerializedBlockDefinitionV1 } from "./v1/blockSerialization.types";
+
+/**
+ * Type union of all versions of serialized SmartFilter block definitions
+ * A block definition is an object which is used to create a CustomShaderBlock instance.
+ */
+export type SerializedBlockDefinition = SerializedBlockDefinitionV1;

package/src/serialization/serializedSmartFilter.ts

@@ -1,4 +1,4 @@
-import type { SerializedSmartFilterV1 } from "./v1/serialization.types";
+import type { SerializedSmartFilterV1 } from "./v1/smartFilterSerialization.types";
 
 /**
  * Type union of all versions of serialized SmartFilters

package/src/serialization/smartFilterDeserializer.ts

@@ -6,13 +6,22 @@ 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,
     OptionalBlockDeserializerV1,
     SerializedSmartFilterV1,
-} from "./v1/serialization.types";
+} from "./v1/smartFilterSerialization.types";
 import { UniqueIdGenerator } from "../utils/uniqueIdGenerator.js";
+import type { Nullable } from "@babylonjs/core/types";
+
+/**
+ * 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
+) => Promise<Nullable<BaseBlock>>;
 
 /**
  * Deserializes serialized SmartFilters. The caller passes in a map of block deserializers it wants to use,
@@ -20,39 +29,17 @@ import { UniqueIdGenerator } from "../utils/uniqueIdGenerator.js";
  * The deserializer supports versioned serialized SmartFilters.
  */
 export class SmartFilterDeserializer {
-    private readonly _blockDeserializersV1: Map<string, DeserializeBlockV1> = new Map();
+    private readonly _blockFactory: BlockFactory;
+    private readonly _customInputBlockDeserializer?: OptionalBlockDeserializerV1;
 
     /**
      * Creates a new SmartFilterDeserializer
-     * @param blockDeserializers - The map of block serializers to use, beyond those for the core blocks
+     * @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(
-        blockDeserializers: Map<string, DeserializeBlockV1>,
-        customInputBlockDeserializer?: OptionalBlockDeserializerV1
-    ) {
-        this._blockDeserializersV1 = blockDeserializers;
-
-        this._blockDeserializersV1.set(
-            InputBlock.ClassName,
-            async (smartFilter: SmartFilter, serializedBlock: ISerializedBlockV1, engine: ThinEngine) => {
-                if (customInputBlockDeserializer) {
-                    const customDeserializerResult = await customInputBlockDeserializer(
-                        smartFilter,
-                        serializedBlock,
-                        engine
-                    );
-                    if (customDeserializerResult !== null) {
-                        return customDeserializerResult;
-                    }
-                }
-                return inputBlockDeserializer(smartFilter, serializedBlock);
-            }
-        );
-
-        this._blockDeserializersV1.set(OutputBlock.ClassName, (smartFilter: SmartFilter) =>
-            Promise.resolve(smartFilter.output.ownerBlock)
-        );
+    public constructor(blockFactory: BlockFactory, customInputBlockDeserializer?: OptionalBlockDeserializerV1) {
+        this._blockFactory = blockFactory;
+        this._customInputBlockDeserializer = customInputBlockDeserializer;
     }
 
     /**
@@ -63,7 +50,14 @@ export class SmartFilterDeserializer {
      */
     public async deserialize(engine: ThinEngine, smartFilterJson: any): Promise<SmartFilter> {
         const serializedSmartFilter: SerializedSmartFilter = smartFilterJson;
-        switch (serializedSmartFilter.version) {
+
+        // 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;
+            delete (serializedSmartFilter as any).version;
+        }
+
+        switch (serializedSmartFilter.formatVersion) {
             case 1:
                 return await this._deserializeV1(engine, serializedSmartFilter);
         }
@@ -85,31 +79,28 @@ export class SmartFilterDeserializer {
 
         // Deserialize the blocks
         const blockDeserializationWork: Promise<void>[] = [];
+        const blockDefinitionsWhichCouldNotBeDeserialized: string[] = [];
         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
-                    blockIdMap.set(newBlock.uniqueId, newBlock);
-                    blockNameMap.set(newBlock.name, newBlock);
-                })
+                this._deserializeBlockV1(
+                    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
@@ -121,7 +112,9 @@ export class SmartFilterDeserializer {
             if (!sourceBlock) {
                 throw new Error(`Source block ${connection.outputBlock} not found`);
             }
-            const sourceConnectionPoint = (sourceBlock as any)[connection.outputConnectionPoint];
+            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}`
@@ -137,7 +130,10 @@ export class SmartFilterDeserializer {
             if (!targetBlock) {
                 throw new Error(`Target block ${connection.inputBlock} not found`);
             }
-            const targetConnectionPoint = (targetBlock as any)[connection.inputConnectionPoint];
+
+            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}`
@@ -150,4 +146,62 @@ export class SmartFilterDeserializer {
 
         return smartFilter;
     }
+
+    private async _deserializeBlockV1(
+        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;
+        }
+
+        // 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);
+                if (!newBlock) {
+                    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;
+
+        // 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

@@ -10,7 +10,8 @@ import type {
     ISerializedConnectionV1,
     SerializeBlockV1,
     SerializedSmartFilterV1,
-} from "./v1/serialization.types";
+} from "./v1/smartFilterSerialization.types";
+import { CustomShaderBlock } from "../blocks/customShaderBlock.js";
 
 /**
  * Determines if two serialized connection points are equivalent to each other
@@ -37,17 +38,17 @@ export class SmartFilterSerializer {
 
     /**
      * 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 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.className, inputBlockSerializer.serialize);
+        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.className, serializer.serialize)
+            this._blockSerializers.set(serializer.blockType, serializer.serialize)
         );
     }
 
@@ -61,9 +62,12 @@ export class SmartFilterSerializer {
 
         const blocks = smartFilter.attachedBlocks.map((block: BaseBlock) => {
             // Serialize the block itself
-            const serializeFn = this._blockSerializers.get(block.getClassName());
+            const serializeFn =
+                block.getClassName() === CustomShaderBlock.ClassName
+                    ? defaultBlockSerializer
+                    : this._blockSerializers.get(block.blockType);
             if (!serializeFn) {
-                throw new Error(`No serializer was provided for a block of type ${block.getClassName()}`);
+                throw new Error(`No serializer was provided for a block of type ${block.blockType}`);
             }
             const serializedBlock: ISerializedBlockV1 = serializeFn(block);
 
@@ -102,7 +106,7 @@ export class SmartFilterSerializer {
         });
 
         return {
-            version: 1,
+            formatVersion: 1,
             name: smartFilter.name,
             comments: smartFilter.comments,
             editorData: smartFilter.editorData,

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

@@ -0,0 +1,63 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Data Types Used For Block Serialization
+ * ----------------------------------------------------------------------------
+ */
+
+import type { AllConnectionPointTypes, ConnectionPointValue } from "../../connection/connectionPointType";
+import type { ShaderProgram } from "../../utils/shaderCodeUtils";
+
+/**
+ * The V1 definition of a serialized block. A 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 SerializedBlockDefinitionV1 = {
+    /**
+     * 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 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;
+};
+
+/**
+ * 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>;
+};

package/src/serialization/v1/defaultBlockSerializer.ts

@@ -1,5 +1,5 @@
 import type { BaseBlock } from "../../blocks/baseBlock";
-import type { ISerializedBlockV1, SerializeBlockV1 } from "./serialization.types";
+import type { ISerializedBlockV1, SerializeBlockV1 } from "./smartFilterSerialization.types";
 
 /**
  * The default V1 block serializer which can be used for any block that relies only on ConnectionPoints
@@ -11,7 +11,7 @@ export const defaultBlockSerializer: SerializeBlockV1 = (block: BaseBlock): ISer
     return {
         name: block.name,
         uniqueId: block.uniqueId,
-        className: block.getClassName(),
+        blockType: block.blockType,
         comments: block.comments,
         data: undefined,
     };

package/src/serialization/v1/index.ts

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

package/src/serialization/v1/{serialization.types.ts → smartFilterSerialization.types.ts}

@@ -14,8 +14,8 @@ import type { IEditorData } from "@babylonjs/shared-ui-components/nodeGraphSyste
  * V1 Serialized Smart Filter
  */
 export type SerializedSmartFilterV1 = {
-    /** The version of the serialized data */
-    version: 1;
+    /** The format version of the serialized data (not the version of the SmartFilter itself).*/
+    formatVersion: 1;
 
     /** The SmartFilter name */
     name: string;
@@ -34,7 +34,8 @@ export type SerializedSmartFilterV1 = {
 };
 
 /**
- * V1 Serialized Block
+ * 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 */
@@ -43,8 +44,8 @@ export interface ISerializedBlockV1 {
     /** 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 blockType of the block - used to determine how to instantiate the block during deserialization */
+    blockType: string;
 
     /** The comments for the block */
     comments: Nullable<string>;
@@ -82,13 +83,13 @@ export interface ISerializedConnectionV1 {
 export type SerializeBlockV1 = (block: BaseBlock) => ISerializedBlockV1;
 
 /**
- * A V1 block serializer
+ * A V1 serializer for blocks in a SmartFilter
  */
 export interface IBlockSerializerV1 {
-    /** The className of the block that this serializer can serialize */
-    className: string;
+    /** The blockType of the block that this serializer can serialize */
+    blockType: string;
 
-    /** The function that serializes the block */
+    /** The function that serializes the block in the Smart Filter */
     serialize: SerializeBlockV1;
 }
 
@@ -99,7 +100,7 @@ export interface IBlockSerializerV1 {
  */
 
 /**
- * A function that deserializes a block from a V1 serialized block object
+ * A function that deserializes a V1 block in a SmartFilter
  */
 export type DeserializeBlockV1 = (
     smartFilter: SmartFilter,

package/src/utils/buildTools/buildShaders.ts

@@ -5,7 +5,7 @@
  * @example node buildShaders.js <shaderPath> <importPath>
  */
 
-import { convertShaders } from "./shaderConverter.js";
+import { convertShaders } from "./convertShaderForHardcodedBlock.js";
 
 const externalArguments = process.argv.slice(2);
 if (externalArguments.length >= 2 && externalArguments[0] && externalArguments[1]) {