@babylonjs/smart-filters 0.1.0-alpha

package/src/connection/connectionPoint.ts

@@ -0,0 +1,212 @@
+import type { Nullable } from "@babylonjs/core/types";
+import {
+    ConnectionPointCompatibilityState,
+    getCompatibilityIssueMessage,
+} from "./connectionPointCompatibilityState.js";
+import { ConnectionPointDirection } from "./connectionPointDirection.js";
+import type { BaseBlock } from "../blocks/baseBlock";
+import type { ConnectionPointType, ConnectionPointValue } from "./connectionPointType";
+import type { StrongRef } from "../runtime/strongRef";
+
+/**
+ * This represents a strong reference to the data being passed through a connection point.
+ */
+export type RuntimeData<U extends ConnectionPointType> = StrongRef<ConnectionPointValue<U>>;
+
+/**
+ * This defines a connection point.
+ *
+ * A connection point is any input/output of a block.
+ * It can be linked to another connection point following some rules:
+ *  - The type of the connection point must be compatible with the other one.
+ *  - The direction of the connection point must be different from the other one.
+ *  - The connection cannot create a cycle in the list of blocks.
+ * The relationship is always 1:N for input:output
+ */
+export class ConnectionPoint<U extends ConnectionPointType = ConnectionPointType> {
+    /**
+     * The name of the connection point.
+     * This is used to identify the connection point inside a block.
+     */
+    public readonly name: string;
+
+    /**
+     * The type of the connection point (float, texture, etc.)
+     */
+    public readonly type: U;
+
+    /**
+     * The direction of the connection point (input or output)
+     */
+    public readonly direction: ConnectionPointDirection;
+
+    /**
+     * The smart filter block the connection point belongs to.
+     */
+    public readonly ownerBlock: BaseBlock;
+
+    /**
+     * User provided name for the connection point.
+     */
+    public displayName: Nullable<string> = null;
+
+    /**
+     * The @see RunTimeData used during the init phase to reference the result of the previous block.
+     * Those are only used for input connection points.
+     * The previous block are "pushing" this in during the init stage.
+     */
+    public runtimeData: Nullable<RuntimeData<U>> = null;
+
+    /**
+     * The default runtimeData used when no connection is made to the connection point.
+     */
+    public readonly defaultRuntimeData: Nullable<RuntimeData<U>> = null;
+
+    private _connectedTo: Nullable<ConnectionPoint<U>> = null;
+    private _endpoints: Array<ConnectionPoint<U>> = [];
+
+    /**
+     * Create a new connection point.
+     * @param name - The name the connection point has in the block
+     * @param ownerBlock - The block the connection point belongs to
+     * @param type - The type of the connection point
+     * @param direction - The direction of the connection point
+     * @param defaultRuntimeData - The default runtime data to use when no connection is made to the connection point
+     */
+    constructor(
+        name: string,
+        ownerBlock: BaseBlock,
+        type: U,
+        direction: ConnectionPointDirection,
+        defaultRuntimeData: Nullable<RuntimeData<U>> = null
+    ) {
+        this.name = name;
+        this.ownerBlock = ownerBlock;
+        this.type = type;
+        this.direction = direction;
+        this.defaultRuntimeData = defaultRuntimeData;
+        this.runtimeData = defaultRuntimeData;
+    }
+
+    /**
+     * @returns the connection point this connection point is connected to.
+     * (the one on the other side of the connection)
+     * Only input connection points have a connected point which they received their value from.
+     * (Relation is always 1:N for input:output)
+     */
+    public get connectedTo(): Nullable<ConnectionPoint<U>> {
+        return this._connectedTo;
+    }
+
+    /**
+     * @returns the connection point this connection point is to.
+     * (the one on the other side of the connection)
+     * Only output connection points have a list of endpoints which they provide their value to.
+     * (Relation is always 1:N for input:output)
+     */
+    public get endpoints(): ReadonlyArray<ConnectionPoint<U>> {
+        return this._endpoints;
+    }
+
+    /**
+     * Gets a state indicating if the current point can be connected to another point
+     * @param other - defines the other connection point
+     * @returns the compatibility state
+     */
+    public checkCompatibilityState(other: ConnectionPoint<U>): ConnectionPointCompatibilityState {
+        // Only connects output to input
+        if (this.direction === ConnectionPointDirection.Input) {
+            return other.checkCompatibilityState(this);
+        }
+
+        // Check types
+        if (this.type !== other.type) {
+            return ConnectionPointCompatibilityState.TypeIncompatible;
+        }
+
+        // Check directions
+        if (this.direction === other.direction) {
+            return ConnectionPointCompatibilityState.DirectionIncompatible;
+        }
+
+        // Check hierarchy
+        if (other.ownerBlock.isAnAncestorOf(this.ownerBlock)) {
+            return ConnectionPointCompatibilityState.HierarchyIssue;
+        }
+
+        return ConnectionPointCompatibilityState.Compatible;
+    }
+
+    /**
+     * Checks if the connection point can be connected to another one.
+     * @param connectionPoint - The other connection point to check compatibility with
+     * @returns true if the connection point can be connected to the other one
+     */
+    public canConnectTo(connectionPoint: ConnectionPoint<U>) {
+        return this.checkCompatibilityState(connectionPoint) === ConnectionPointCompatibilityState.Compatible;
+    }
+
+    /**
+     * Connect this connection point to another one.
+     * @param other - The other connection point to connect to
+     * @throws if the connection point cannot be connected to the other one
+     */
+    public connectTo(other: ConnectionPoint<U>): void {
+        // Only connects output to input
+        if (this.direction === ConnectionPointDirection.Input) {
+            other.connectTo(this);
+            return;
+        }
+
+        // Check compatibility
+        const compatibility = this.checkCompatibilityState(other);
+        if (compatibility !== ConnectionPointCompatibilityState.Compatible) {
+            throw getCompatibilityIssueMessage(compatibility);
+        }
+
+        // Adds the connection point to the list of endpoints
+        this._endpoints.push(other);
+        // Fill at the same time the connectedTo property of the other connection point
+        other._connectedTo = this;
+    }
+
+    /**
+     * Disconnects this point from one of his endpoint
+     * @param endpoint - defines the other connection point
+     */
+    public disconnectFrom(endpoint: ConnectionPoint<U>): void {
+        const index = this._endpoints.indexOf(endpoint);
+        if (index === -1) {
+            return;
+        }
+
+        // Remove the connection point from the list of endpoints
+        this._endpoints.splice(index, 1);
+        // Empty at the same time the connectedTo property of the other connection point
+        endpoint._connectedTo = null;
+    }
+
+    /**
+     * Disconnects this point from all its endpoints.
+     */
+    public disconnectAllEndpoints(): void {
+        // Detach outputs
+        let endpoint: ConnectionPoint<U> | undefined;
+        while ((endpoint = this._endpoints[0])) {
+            this.disconnectFrom(endpoint);
+        }
+    }
+
+    /**
+     * Propagates the current runtime data to all endpoints.
+     */
+    public propagateRuntimeData(): void {
+        if (!this.runtimeData) {
+            this.runtimeData = {} as RuntimeData<U>;
+        }
+
+        for (const endpoint of this.endpoints) {
+            endpoint.runtimeData = this.runtimeData;
+        }
+    }
+}

package/src/connection/connectionPointCompatibilityState.ts

@@ -0,0 +1,31 @@
+/**
+ * Defines how compatible connection points are.
+ */
+export enum ConnectionPointCompatibilityState {
+    /** Points are compatibles */
+    Compatible,
+    /** Points are incompatible because of their types */
+    TypeIncompatible,
+    /** Points are incompatible because of their directions */
+    DirectionIncompatible,
+    /** Points are incompatible because they are in the same hierarchy **/
+    HierarchyIssue,
+}
+
+/**
+ * Gets a user friendly message for the given compatibility state.
+ * @param state - Defines the compatibility state
+ * @returns the message associated with a compatibility state.
+ */
+export function getCompatibilityIssueMessage(state: ConnectionPointCompatibilityState): string {
+    switch (state) {
+        case ConnectionPointCompatibilityState.TypeIncompatible:
+            return "Cannot connect two different connection types";
+        case ConnectionPointCompatibilityState.DirectionIncompatible:
+            return "Cannot connect with the same direction";
+        case ConnectionPointCompatibilityState.HierarchyIssue:
+            return "Source block cannot be connected with one of its ancestors";
+        default:
+            return "";
+    }
+}

package/src/connection/connectionPointDirection.ts

@@ -0,0 +1,9 @@
+/**
+ * Defines the direction of a connection point.
+ */
+export enum ConnectionPointDirection {
+    /** Input */
+    Input = 0,
+    /** Output */
+    Output = 1,
+}

package/src/connection/connectionPointType.ts

@@ -0,0 +1,30 @@
+import type { ThinTexture } from "@babylonjs/core/Materials/Textures/thinTexture";
+import type { IColor3Like, IColor4Like } from "@babylonjs/core/Maths/math.like";
+
+/**
+ * Defines the type of a connection point.
+ */
+export enum ConnectionPointType {
+    /** Float */
+    Float = 1,
+    /** Texture */
+    Texture = 2,
+    /** Color3 */
+    Color3 = 3,
+    /** Color4 */
+    Color4 = 4,
+    /** Boolean */
+    Boolean = 5,
+}
+
+/**
+ * Retrieves the type of the value from the Connection point type.
+ */
+// prettier-ignore
+export type ConnectionPointValue<T extends ConnectionPointType = ConnectionPointType> =
+    T extends ConnectionPointType.Float ? number :
+    T extends ConnectionPointType.Texture ? ThinTexture :
+    T extends ConnectionPointType.Color3 ? IColor3Like :
+    T extends ConnectionPointType.Color4 ? IColor4Like :
+    T extends ConnectionPointType.Boolean ? boolean :
+    never;

package/src/connection/connectionPointWithDefault.ts

@@ -0,0 +1,35 @@
+import type { BaseBlock } from "../blocks/baseBlock";
+import { ConnectionPoint, type RuntimeData } from "./connectionPoint.js";
+import type { ConnectionPointDirection } from "./connectionPointDirection";
+import type { ConnectionPointType } from "./connectionPointType";
+
+/**
+ * A ConnectionPoint whose runtimeData is never null - if not hooked up to a connection, it will use a default value.
+ */
+export class ConnectionPointWithDefault<
+    U extends ConnectionPointType = ConnectionPointType,
+> extends ConnectionPoint<U> {
+    /**
+     * The runtime data for this ConnectionPoint - it will never be null - if not hooked up to a connection, it will use the default value.
+     */
+    public override runtimeData: RuntimeData<U>;
+
+    /**
+     * Create a new ConnectionPointWithDefault
+     * @param name - The name the connection point has in the block
+     * @param ownerBlock - The block the connection point belongs to
+     * @param type - The type of the connection point
+     * @param direction - The direction of the connection point
+     * @param runtimeData - The runtimeData to use for this connection point if no connection is made
+     */
+    constructor(
+        name: string,
+        ownerBlock: BaseBlock,
+        type: U,
+        direction: ConnectionPointDirection,
+        runtimeData: RuntimeData<U>
+    ) {
+        super(name, ownerBlock, type, direction, runtimeData);
+        this.runtimeData = runtimeData;
+    }
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+export { type IDisposable } from "./IDisposable.js";
+export { type StrongRef } from "./runtime/strongRef.js";
+export { createStrongRef } from "./runtime/strongRef.js";
+
+export * from "./command/command.js";
+export * from "./command/commandBuffer.js";
+export { logCommands } from "./command/commandBufferDebugger.js";
+
+export { ConnectionPointDirection } from "./connection/connectionPointDirection.js";
+export { ConnectionPointType } from "./connection/connectionPointType.js";
+export { type ConnectionPointValue } from "./connection/connectionPointType.js";
+export {
+    ConnectionPointCompatibilityState,
+    getCompatibilityIssueMessage,
+} from "./connection/connectionPointCompatibilityState.js";
+export { ConnectionPoint } from "./connection/connectionPoint.js";
+export { type RuntimeData } from "./connection/connectionPoint.js";
+
+export { BaseBlock } from "./blocks/baseBlock.js";
+export { InputBlock } from "./blocks/inputBlock.js";
+export { type AnyInputBlock } from "./blocks/inputBlock.js";
+export { ShaderBlock } from "./blocks/shaderBlock.js";
+export { AggregateBlock } from "./blocks/aggregateBlock.js";
+export { CopyBlock } from "./blocks/copyBlock.js";
+export { ShaderBinding, ShaderRuntime } from "./runtime/shaderRuntime.js";
+export { type ShaderProgram, injectDisableUniform } from "./utils/shaderCodeUtils.js";
+export { type IDisableableBlock } from "./blocks/disableableBlock.js";
+
+export { type SmartFilterRuntime } from "./runtime/smartFilterRuntime.js";
+export { InternalSmartFilterRuntime } from "./runtime/smartFilterRuntime.js";
+export { RenderTargetGenerator } from "./runtime/renderTargetGenerator.js";
+
+export { SmartFilter } from "./smartFilter.js";
+
+export { SmartFilterOptimizer } from "./optimization/smartFilterOptimizer.js";
+export * from "./utils/textureLoaders.js";

package/src/optimization/dependencyGraph.ts

@@ -0,0 +1,94 @@
+/**
+ * Implementation of a dependency graph.
+ */
+export class DependencyGraph<T> {
+    private _list: Set<T>;
+    private _dependOn: Map<T, Set<T>>;
+    private _requiredBy: Map<T, Set<T>>;
+
+    /**
+     * Creates a new instance of a dependency graph.
+     */
+    constructor() {
+        this._list = new Set();
+        this._dependOn = new Map();
+        this._requiredBy = new Map();
+    }
+
+    /**
+     * Adds an element to the graph.
+     * @param element - The element to add to the graph.
+     */
+    public addElement(element: T) {
+        if (this._list.has(element)) {
+            throw new Error(`Element "${element}" already added to the graph!`);
+        }
+
+        this._list.add(element);
+    }
+
+    /**
+     * Adds a dependency between two elements.
+     * @param element - The element that depends on another element.
+     * @param dependency - The element that is required by the element passed as the first parameter.
+     */
+    public addDependency(element: T, dependency: T) {
+        if (!this._dependOn.has(element)) {
+            this._dependOn.set(element, new Set());
+        }
+
+        if (!this._requiredBy.has(dependency)) {
+            this._requiredBy.set(dependency, new Set());
+        }
+
+        this._dependOn.get(element)!.add(dependency);
+        this._requiredBy.get(dependency)!.add(element);
+    }
+
+    /**
+     * Walks through the graph and calls the callback for each element.
+     * The elements that depend on other elements will be traversed after the elements they depend on.
+     * Note: the graph will be modified during the walk, so don't call walk twice on the same graph!
+     * @param callback - The callback to call for each element.
+     */
+    public walk(callback: (element: T) => void) {
+        const toVisit: T[] = [];
+
+        // Collect all elements that have no dependency
+        for (const element of this._list) {
+            if (!this._dependOn.get(element)) {
+                toVisit.push(element);
+                this._list.delete(element);
+            }
+        }
+
+        // Loop over all elements that have no dependency
+        while (toVisit.length > 0) {
+            const element = toVisit.shift()!;
+
+            callback(element);
+
+            this._list.delete(element);
+
+            const requiredBy = this._requiredBy.get(element);
+            if (requiredBy) {
+                for (const dependingElement of requiredBy) {
+                    const dependencies = this._dependOn.get(dependingElement);
+
+                    if (dependencies) {
+                        dependencies.delete(element);
+
+                        if (dependencies.size === 0) {
+                            toVisit.push(dependingElement);
+                        }
+                    }
+                }
+            }
+        }
+
+        if (this._list.size > 0) {
+            console.error(this._list);
+            throw new Error("Circular dependency detected!");
+        }
+    }
+}

package/src/optimization/optimizedShaderBlock.ts

@@ -0,0 +1,133 @@
+import type { Effect } from "@babylonjs/core/Materials/effect";
+import type { Nullable } from "@babylonjs/core/types";
+import type { ThinTexture } from "@babylonjs/core/Materials/Textures/thinTexture";
+
+import type { SmartFilter } from "../smartFilter";
+import type { ShaderProgram } from "../utils/shaderCodeUtils";
+import type { StrongRef } from "../runtime/strongRef";
+import type { RuntimeData } from "../connection/connectionPoint";
+import { ShaderBlock } from "../blocks/shaderBlock.js";
+import { Binding } from "../runtime/shaderRuntime.js";
+import { ConnectionPointType } from "../connection/connectionPointType.js";
+
+/**
+ * The shader bindings for the OptimizedShader block.
+ * @internal
+ */
+export class OptimizedShaderBinding extends Binding {
+    private _shaderBindings: Binding[];
+    private _inputTextures: { [name: string]: StrongRef<ThinTexture> };
+
+    /**
+     * Creates a new shader binding instance for the OptimizedShader block.
+     * @param shaderBindings - The list of shader bindings to process
+     * @param inputTextures - The list of input textures to bind
+     */
+    constructor(shaderBindings: Binding[], inputTextures: { [name: string]: StrongRef<ThinTexture> }) {
+        super();
+
+        this._shaderBindings = shaderBindings;
+        this._inputTextures = inputTextures;
+    }
+
+    /**
+     * Binds all the required data to the shader when rendering.
+     * @param effect - defines 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 (const shaderBinding of this._shaderBindings) {
+            shaderBinding.bind(effect, width, height);
+        }
+
+        for (const name in this._inputTextures) {
+            const texture = this._inputTextures[name];
+            // texture can't be undefined, so let's add "!" to make Typescript happy
+            effect.setTexture(this.getRemappedName(name), texture!.value);
+        }
+    }
+}
+
+/**
+ * A block used by the smart filter optimizer to group shader blocks together.
+ * Should be for internal use only.
+ * @internal
+ */
+export class OptimizedShaderBlock extends ShaderBlock {
+    private _shaderBindings: Nullable<Binding[]>;
+    private _inputTextures: { [name: string]: StrongRef<ThinTexture> } = {};
+    private _shaderProgram: ShaderProgram;
+
+    /**
+     * The class name of the block.
+     */
+    public static override ClassName = "OptimizedShaderBlock";
+
+    /**
+     * Returns if the block is an input block.
+     */
+    public override get isInput(): boolean {
+        return false;
+    }
+
+    /**
+     * Creates a new OptimizedShaderBlock.
+     * @param smartFilter - The smart filter to add the block to
+     * @param name - The name of the block
+     */
+    constructor(smartFilter: SmartFilter, name: string) {
+        super(smartFilter, name, true);
+
+        this._shaderBindings = null;
+        this._shaderProgram = undefined as any;
+    }
+
+    /**
+     * Gets the shader program to use to render the block.
+     * @returns The shader program to use to render the block
+     */
+    public override getShaderProgram(): ShaderProgram {
+        return this._shaderProgram;
+    }
+
+    /**
+     * Sets the shader program to use to render the block.
+     * @param shaderProgram - The shader program to use to render the block
+     */
+    public setShaderProgram(shaderProgram: ShaderProgram): void {
+        this._shaderProgram = shaderProgram;
+    }
+
+    /**
+     * Sets the list of shader bindings to use to render the block.
+     * @param shaderBindings - The list of shader bindings to use to render the block
+     */
+    public setShaderBindings(shaderBindings: Binding[]): void {
+        this._shaderBindings = shaderBindings;
+    }
+
+    /**
+     * Get the class instance that binds all the required data to the shader (effect) when rendering.
+     * @returns The class instance that binds the data to the effect
+     */
+    public getShaderBinding(): Binding {
+        if (this._shaderBindings === null) {
+            throw new Error("Shader bindings not set!");
+        }
+
+        for (const input of this.inputs) {
+            const name = input.name;
+
+            if (input.type === ConnectionPointType.Texture) {
+                /**
+                 * These are the inputs created by the OptimizedShaderBlock
+                 * We pass them to OptimizedShaderBinding so that their value can be set appropriately at runtime (in the bind method)
+                 */
+                this._inputTextures[name] = input.runtimeData as RuntimeData<ConnectionPointType.Texture>;
+            }
+        }
+
+        return new OptimizedShaderBinding(this._shaderBindings, this._inputTextures);
+    }
+}