@babylonjs/core 7.32.0 → 7.32.1

package/Materials/effectRenderer.d.ts

@@ -1,11 +1,12 @@
-import type { Nullable } from "../types";
+import type { NonNullableFields, Nullable } from "../types";
 import type { AbstractEngine } from "../Engines/abstractEngine";
 import { Viewport } from "../Maths/math.viewport";
 import { Observable } from "../Misc/observable";
+import type { IShaderPath } from "./effect";
 import { Effect } from "./effect";
 import { DrawWrapper } from "./drawWrapper";
 import type { IRenderTargetTexture, RenderTargetWrapper } from "../Engines/renderTargetWrapper";
-import type { ShaderLanguage } from "./shaderLanguage";
+import { ShaderLanguage } from "./shaderLanguage";
 import "../Shaders/postprocess.vertex";
 /**
  * Effect Render Options
@@ -74,7 +75,7 @@ export declare class EffectRenderer {
     /**
      * renders one or more effects to a specified texture
      * @param effectWrapper the effect to renderer
-     * @param outputTexture texture to draw to, if null it will render to the screen.
+     * @param outputTexture texture to draw to, if null it will render to the currently bound frame buffer
      */
     render(effectWrapper: EffectWrapper, outputTexture?: Nullable<RenderTargetWrapper | IRenderTargetTexture>): void;
     /**
@@ -82,65 +83,160 @@ export declare class EffectRenderer {
      */
     dispose(): void;
 }
+/**
+ * Allows for custom processing of the shader code used by an effect wrapper
+ */
+export type EffectWrapperCustomShaderCodeProcessing = {
+    /**
+     * If provided, will be called two times with the vertex and fragment code so that this code can be updated after the #include have been processed
+     */
+    processCodeAfterIncludes?: (postProcessName: string, shaderType: string, code: string) => string;
+    /**
+     * If provided, will be called two times with the vertex and fragment code so that this code can be updated before it is compiled by the GPU
+     */
+    processFinalCode?: (postProcessName: string, shaderType: string, code: string) => string;
+    /**
+     * If provided, will be called before creating the effect to collect additional custom bindings (defines, uniforms, samplers)
+     */
+    defineCustomBindings?: (postProcessName: string, defines: Nullable<string>, uniforms: string[], samplers: string[]) => Nullable<string>;
+    /**
+     * If provided, will be called when binding inputs to the shader code to allow the user to add custom bindings
+     */
+    bindCustomBindings?: (postProcessName: string, effect: Effect) => void;
+};
 /**
  * Options to create an EffectWrapper
  */
-interface EffectWrapperCreationOptions {
+export interface EffectWrapperCreationOptions {
     /**
      * Engine to use to create the effect
      */
-    engine: AbstractEngine;
+    engine?: AbstractEngine;
     /**
      * Fragment shader for the effect
      */
-    fragmentShader: string;
+    fragmentShader?: string;
     /**
      * Use the shader store instead of direct source code
      */
     useShaderStore?: boolean;
     /**
-     * Vertex shader for the effect
+     * Vertex shader for the effect (default: "postprocess")
      */
     vertexShader?: string;
     /**
-     * Attributes to use in the shader
+     * Alias for vertexShader
+     */
+    vertexUrl?: string;
+    /**
+     * Attributes to use in the shader (default: ["position"])
      */
     attributeNames?: Array<string>;
     /**
      * Uniforms to use in the shader
      */
     uniformNames?: Array<string>;
+    /**
+     * Alias for uniformNames. Note that if it is provided, it takes precedence over uniformNames.
+     */
+    uniforms?: Nullable<string[]>;
     /**
      * Texture sampler names to use in the shader
      */
     samplerNames?: Array<string>;
+    /**
+     * Alias for samplerNames. Note that if it is provided, it takes precedence over samplerNames.
+     */
+    samplers?: Nullable<string[]>;
+    /**
+     * The list of uniform buffers used in the shader (if any)
+     */
+    uniformBuffers?: Nullable<string[]>;
     /**
      * Defines to use in the shader
      */
-    defines?: Array<string>;
+    defines?: Nullable<string | Array<string>>;
+    /**
+     * The index parameters to be used for babylons include syntax "#include<kernelBlurVaryingDeclaration>[0..varyingCount]". (default: undefined)
+     * See usage in babylon.blurPostProcess.ts and kernelBlur.vertex.fx
+     */
+    indexParameters?: any;
+    /**
+     * If the shader should not be compiled immediately. (default: false)
+     */
+    blockCompilation?: boolean;
     /**
      * Callback when effect is compiled
      */
     onCompiled?: Nullable<(effect: Effect) => void>;
     /**
-     * The friendly name of the effect displayed in Spector.
+     * The friendly name of the effect (default: "effectWrapper")
      */
     name?: string;
     /**
      * The language the shader is written in (default: GLSL)
      */
     shaderLanguage?: ShaderLanguage;
+    /**
+     * Defines additional code to call to prepare the shader code
+     */
+    extraInitializations?: (useWebGPU: boolean, list: Promise<any>[]) => void;
     /**
      * Additional async code to run before preparing the effect
      */
     extraInitializationsAsync?: () => Promise<void>;
+    /**
+     * If the effect should be used as a post process (default: false). If true, the effect will be created with a "scale" uniform and a "textureSampler" sampler
+     */
+    useAsPostProcess?: boolean;
 }
 /**
  * Wraps an effect to be used for rendering
  */
 export declare class EffectWrapper {
     /**
-     * Event that is fired right before the effect is drawn (should be used to update uniforms)
+     * Force code to compile to glsl even on WebGPU engines.
+     * False by default. This is mostly meant for backward compatibility.
+     */
+    static ForceGLSL: boolean;
+    private static _CustomShaderCodeProcessing;
+    /**
+     * Registers a shader code processing with an effect wrapper name.
+     * @param effectWrapperName name of the effect wrapper. Use null for the fallback shader code processing. This is the shader code processing that will be used in case no specific shader code processing has been associated to an effect wrapper name
+     * @param customShaderCodeProcessing shader code processing to associate to the effect wrapper name
+     */
+    static RegisterShaderCodeProcessing(effectWrapperName: Nullable<string>, customShaderCodeProcessing?: EffectWrapperCustomShaderCodeProcessing): void;
+    private static _GetShaderCodeProcessing;
+    /**
+     * Gets or sets the name of the effect wrapper
+     */
+    get name(): string;
+    set name(value: string);
+    /**
+     * Type of alpha mode to use when applying the effect (default: Engine.ALPHA_DISABLE)
+     */
+    alphaMode: number;
+    /**
+     * Executed when the effect is created
+     * @returns effect that was created for this effect wrapper
+     */
+    onEffectCreatedObservable: Observable<Effect>;
+    /**
+     * Options used to create the effect wrapper
+     */
+    readonly options: Required<NonNullableFields<EffectWrapperCreationOptions>>;
+    /**
+     * Get a value indicating if the effect is ready to be used
+     * @returns true if the post-process is ready (shader is compiled)
+     */
+    isReady(): boolean;
+    /**
+     * Get the draw wrapper associated with the effect wrapper
+     * @returns the draw wrapper associated with the effect wrapper
+     */
+    get drawWrapper(): DrawWrapper;
+    /**
+     * Event that is fired (only when the EffectWrapper is used with an EffectRenderer) right before the effect is drawn (should be used to update uniforms)
      */
     onApplyObservable: Observable<{}>;
     /**
@@ -148,18 +244,40 @@ export declare class EffectWrapper {
      */
     get effect(): Effect;
     set effect(effect: Effect);
+    protected readonly _drawWrapper: DrawWrapper;
+    protected _shadersLoaded: boolean;
+    protected readonly _shaderPath: IShaderPath;
     /** @internal */
-    _drawWrapper: DrawWrapper;
+    _webGPUReady: boolean;
     private _onContextRestoredObserver;
     /**
-     * Creates an effect to be renderer
+     * Creates an effect to be rendered
      * @param creationOptions options to create the effect
      */
     constructor(creationOptions: EffectWrapperCreationOptions);
+    protected _gatherImports(useWebGPU: boolean | undefined, list: Promise<any>[]): void;
+    private _importPromises;
+    /** @internal */
+    _postConstructor(blockCompilation: boolean, defines?: Nullable<string>, extraInitializations?: (useWebGPU: boolean, list: Promise<any>[]) => void, importPromises?: Array<Promise<any>>): void;
+    /**
+     * Updates the effect with the current effect wrapper compile time values and recompiles the shader.
+     * @param defines Define statements that should be added at the beginning of the shader. (default: null)
+     * @param uniforms Set of uniform variables that will be passed to the shader. (default: null)
+     * @param samplers Set of Texture2D variables that will be passed to the shader. (default: null)
+     * @param indexParameters The index parameters to be used for babylons include syntax "#include<kernelBlurVaryingDeclaration>[0..varyingCount]". (default: undefined) See usage in babylon.blurPostProcess.ts and kernelBlur.vertex.fx
+     * @param onCompiled Called when the shader has been compiled.
+     * @param onError Called if there is an error when compiling a shader.
+     * @param vertexUrl The url of the vertex shader to be used (default: the one given at construction time)
+     * @param fragmentUrl The url of the fragment shader to be used (default: the one given at construction time)
+     */
+    updateEffect(defines?: Nullable<string>, uniforms?: Nullable<string[]>, samplers?: Nullable<string[]>, indexParameters?: any, onCompiled?: (effect: Effect) => void, onError?: (effect: Effect, errors: string) => void, vertexUrl?: string, fragmentUrl?: string): void;
+    /**
+     * Binds the data to the effect.
+     */
+    bind(): void;
     /**
      * Disposes of the effect wrapper
      * @param _ignored kept for backward compatibility
      */
     dispose(_ignored?: boolean): void;
 }
-export {};

package/Materials/effectRenderer.js

@@ -62,7 +62,7 @@ export class EffectRenderer {
         this.engine.setState(true);
         this.engine.depthCullingState.depthTest = false;
         this.engine.stencilState.stencilTest = false;
-        this.engine.enableEffect(effectWrapper._drawWrapper);
+        this.engine.enableEffect(effectWrapper.drawWrapper);
         this.bindBuffers(effectWrapper.effect);
         effectWrapper.onApplyObservable.notifyObservers({});
     }
@@ -92,7 +92,7 @@ export class EffectRenderer {
     /**
      * renders one or more effects to a specified texture
      * @param effectWrapper the effect to renderer
-     * @param outputTexture texture to draw to, if null it will render to the screen.
+     * @param outputTexture texture to draw to, if null it will render to the currently bound frame buffer
      */
     render(effectWrapper, outputTexture = null) {
         // Ensure effect is ready
@@ -135,6 +135,44 @@ export class EffectRenderer {
  * Wraps an effect to be used for rendering
  */
 export class EffectWrapper {
+    /**
+     * Registers a shader code processing with an effect wrapper name.
+     * @param effectWrapperName name of the effect wrapper. Use null for the fallback shader code processing. This is the shader code processing that will be used in case no specific shader code processing has been associated to an effect wrapper name
+     * @param customShaderCodeProcessing shader code processing to associate to the effect wrapper name
+     */
+    static RegisterShaderCodeProcessing(effectWrapperName, customShaderCodeProcessing) {
+        if (!customShaderCodeProcessing) {
+            delete EffectWrapper._CustomShaderCodeProcessing[effectWrapperName ?? ""];
+            return;
+        }
+        EffectWrapper._CustomShaderCodeProcessing[effectWrapperName ?? ""] = customShaderCodeProcessing;
+    }
+    static _GetShaderCodeProcessing(effectWrapperName) {
+        return EffectWrapper._CustomShaderCodeProcessing[effectWrapperName] ?? EffectWrapper._CustomShaderCodeProcessing[""];
+    }
+    /**
+     * Gets or sets the name of the effect wrapper
+     */
+    get name() {
+        return this.options.name;
+    }
+    set name(value) {
+        this.options.name = value;
+    }
+    /**
+     * Get a value indicating if the effect is ready to be used
+     * @returns true if the post-process is ready (shader is compiled)
+     */
+    isReady() {
+        return this._drawWrapper.effect?.isReady() ?? false;
+    }
+    /**
+     * Get the draw wrapper associated with the effect wrapper
+     * @returns the draw wrapper associated with the effect wrapper
+     */
+    get drawWrapper() {
+        return this._drawWrapper;
+    }
     /**
      * The underlying effect
      */
@@ -145,54 +183,205 @@ export class EffectWrapper {
         this._drawWrapper.effect = effect;
     }
     /**
-     * Creates an effect to be renderer
+     * Creates an effect to be rendered
      * @param creationOptions options to create the effect
      */
     constructor(creationOptions) {
         /**
-         * Event that is fired right before the effect is drawn (should be used to update uniforms)
+         * Type of alpha mode to use when applying the effect (default: Engine.ALPHA_DISABLE)
+         */
+        this.alphaMode = 0;
+        /**
+         * Executed when the effect is created
+         * @returns effect that was created for this effect wrapper
+         */
+        this.onEffectCreatedObservable = new Observable(undefined, true);
+        /**
+         * Event that is fired (only when the EffectWrapper is used with an EffectRenderer) right before the effect is drawn (should be used to update uniforms)
          */
         this.onApplyObservable = new Observable();
-        let shaderPath;
-        const uniformNames = creationOptions.uniformNames || [];
-        if (creationOptions.vertexShader) {
-            shaderPath = {
-                fragmentSource: creationOptions.fragmentShader,
-                vertexSource: creationOptions.vertexShader,
-                spectorName: creationOptions.name || "effectWrapper",
+        this._shadersLoaded = false;
+        /** @internal */
+        this._webGPUReady = false;
+        this._importPromises = [];
+        this.options = {
+            ...creationOptions,
+            name: creationOptions.name || "effectWrapper",
+            engine: creationOptions.engine,
+            uniforms: creationOptions.uniforms || creationOptions.uniformNames || [],
+            uniformNames: undefined,
+            samplers: creationOptions.samplers || creationOptions.samplerNames || [],
+            samplerNames: undefined,
+            attributeNames: creationOptions.attributeNames || ["position"],
+            uniformBuffers: creationOptions.uniformBuffers || [],
+            defines: creationOptions.defines || "",
+            useShaderStore: creationOptions.useShaderStore || false,
+            vertexUrl: creationOptions.vertexUrl || creationOptions.vertexShader || "postprocess",
+            vertexShader: undefined,
+            fragmentShader: creationOptions.fragmentShader || "pass",
+            indexParameters: creationOptions.indexParameters,
+            blockCompilation: creationOptions.blockCompilation || false,
+            shaderLanguage: creationOptions.shaderLanguage || 0 /* ShaderLanguage.GLSL */,
+            onCompiled: creationOptions.onCompiled || undefined,
+            extraInitializations: creationOptions.extraInitializations || undefined,
+            extraInitializationsAsync: creationOptions.extraInitializationsAsync || undefined,
+            useAsPostProcess: creationOptions.useAsPostProcess ?? false,
+        };
+        this.options.uniformNames = this.options.uniforms;
+        this.options.samplerNames = this.options.samplers;
+        this.options.vertexShader = this.options.vertexUrl;
+        if (this.options.useAsPostProcess) {
+            if (this.options.samplers.indexOf("textureSampler") === -1) {
+                this.options.samplers.push("textureSampler");
+            }
+            if (this.options.uniforms.indexOf("scale") === -1) {
+                this.options.uniforms.push("scale");
+            }
+        }
+        if (creationOptions.vertexUrl || creationOptions.vertexShader) {
+            this._shaderPath = {
+                vertexSource: this.options.vertexShader,
             };
         }
         else {
-            // Default scale to use in post process vertex shader.
-            uniformNames.push("scale");
-            shaderPath = {
-                fragmentSource: creationOptions.fragmentShader,
-                vertex: "postprocess",
-                spectorName: creationOptions.name || "effectWrapper",
+            if (!this.options.useAsPostProcess) {
+                this.options.uniforms.push("scale");
+                this.onApplyObservable.add(() => {
+                    this.effect.setFloat2("scale", 1, 1);
+                });
+            }
+            this._shaderPath = {
+                vertex: this.options.vertexShader,
             };
-            // Sets the default scale to identity for the post process vertex shader.
-            this.onApplyObservable.add(() => {
-                this.effect.setFloat2("scale", 1, 1);
-            });
         }
-        const defines = creationOptions.defines ? creationOptions.defines.join("\n") : "";
-        this._drawWrapper = new DrawWrapper(creationOptions.engine);
-        if (creationOptions.useShaderStore) {
-            shaderPath.fragment = shaderPath.fragmentSource;
-            if (!shaderPath.vertex) {
-                shaderPath.vertex = shaderPath.vertexSource;
+        this._shaderPath.fragmentSource = this.options.fragmentShader;
+        this._shaderPath.spectorName = this.options.name;
+        if (this.options.useShaderStore) {
+            this._shaderPath.fragment = this._shaderPath.fragmentSource;
+            if (!this._shaderPath.vertex) {
+                this._shaderPath.vertex = this._shaderPath.vertexSource;
             }
-            delete shaderPath.fragmentSource;
-            delete shaderPath.vertexSource;
-            this.effect = creationOptions.engine.createEffect(shaderPath, creationOptions.attributeNames || ["position"], uniformNames, creationOptions.samplerNames, defines, undefined, creationOptions.onCompiled, undefined, undefined, creationOptions.shaderLanguage, creationOptions.extraInitializationsAsync);
+            delete this._shaderPath.fragmentSource;
+            delete this._shaderPath.vertexSource;
         }
-        else {
-            this.effect = new Effect(shaderPath, creationOptions.attributeNames || ["position"], uniformNames, creationOptions.samplerNames, creationOptions.engine, defines, undefined, creationOptions.onCompiled, undefined, undefined, undefined, creationOptions.shaderLanguage, creationOptions.extraInitializationsAsync);
-            this._onContextRestoredObserver = creationOptions.engine.onContextRestoredObservable.add(() => {
+        this.onApplyObservable.add(() => {
+            this.bind();
+        });
+        if (!this.options.useShaderStore) {
+            this._onContextRestoredObserver = this.options.engine.onContextRestoredObservable.add(() => {
                 this.effect._pipelineContext = null; // because _prepareEffect will try to dispose this pipeline before recreating it and that would lead to webgl errors
                 this.effect._prepareEffect();
             });
         }
+        this._drawWrapper = new DrawWrapper(this.options.engine);
+        this._webGPUReady = this.options.shaderLanguage === 1 /* ShaderLanguage.WGSL */;
+        const defines = Array.isArray(this.options.defines) ? this.options.defines.join("\n") : this.options.defines;
+        this._postConstructor(this.options.blockCompilation, defines, this.options.extraInitializations);
+    }
+    _gatherImports(useWebGPU = false, list) {
+        if (!this.options.useAsPostProcess) {
+            return;
+        }
+        // this._webGPUReady is used to detect when an effect wrapper is intended to be used with WebGPU
+        if (useWebGPU && this._webGPUReady) {
+            list.push(Promise.all([import("../ShadersWGSL/postprocess.vertex.js")]));
+        }
+        else {
+            list.push(Promise.all([import("../Shaders/postprocess.vertex.js")]));
+        }
+    }
+    /** @internal */
+    _postConstructor(blockCompilation, defines = null, extraInitializations, importPromises) {
+        this._importPromises.length = 0;
+        if (importPromises) {
+            this._importPromises.push(...importPromises);
+        }
+        const useWebGPU = this.options.engine.isWebGPU && !EffectWrapper.ForceGLSL;
+        this._gatherImports(useWebGPU, this._importPromises);
+        if (extraInitializations !== undefined) {
+            extraInitializations(useWebGPU, this._importPromises);
+        }
+        if (useWebGPU && this._webGPUReady) {
+            this.options.shaderLanguage = 1 /* ShaderLanguage.WGSL */;
+        }
+        if (!blockCompilation) {
+            this.updateEffect(defines);
+        }
+    }
+    /**
+     * Updates the effect with the current effect wrapper compile time values and recompiles the shader.
+     * @param defines Define statements that should be added at the beginning of the shader. (default: null)
+     * @param uniforms Set of uniform variables that will be passed to the shader. (default: null)
+     * @param samplers Set of Texture2D variables that will be passed to the shader. (default: null)
+     * @param indexParameters The index parameters to be used for babylons include syntax "#include<kernelBlurVaryingDeclaration>[0..varyingCount]". (default: undefined) See usage in babylon.blurPostProcess.ts and kernelBlur.vertex.fx
+     * @param onCompiled Called when the shader has been compiled.
+     * @param onError Called if there is an error when compiling a shader.
+     * @param vertexUrl The url of the vertex shader to be used (default: the one given at construction time)
+     * @param fragmentUrl The url of the fragment shader to be used (default: the one given at construction time)
+     */
+    updateEffect(defines = null, uniforms = null, samplers = null, indexParameters, onCompiled, onError, vertexUrl, fragmentUrl) {
+        const customShaderCodeProcessing = EffectWrapper._GetShaderCodeProcessing(this.name);
+        if (customShaderCodeProcessing?.defineCustomBindings) {
+            const newUniforms = uniforms?.slice() ?? [];
+            newUniforms.push(...this.options.uniforms);
+            const newSamplers = samplers?.slice() ?? [];
+            newSamplers.push(...this.options.samplers);
+            defines = customShaderCodeProcessing.defineCustomBindings(this.name, defines, newUniforms, newSamplers);
+            uniforms = newUniforms;
+            samplers = newSamplers;
+        }
+        this.options.defines = defines || "";
+        const waitImportsLoaded = this._shadersLoaded || this._importPromises.length === 0
+            ? undefined
+            : async () => {
+                await Promise.all(this._importPromises);
+                this._shadersLoaded = true;
+            };
+        let extraInitializationsAsync;
+        if (this.options.extraInitializationsAsync) {
+            extraInitializationsAsync = async () => {
+                waitImportsLoaded?.();
+                await this.options.extraInitializationsAsync;
+            };
+        }
+        else {
+            extraInitializationsAsync = waitImportsLoaded;
+        }
+        if (this.options.useShaderStore) {
+            this._drawWrapper.effect = this.options.engine.createEffect({ vertex: vertexUrl ?? this._shaderPath.vertex, fragment: fragmentUrl ?? this._shaderPath.fragment }, {
+                attributes: this.options.attributeNames,
+                uniformsNames: uniforms || this.options.uniforms,
+                uniformBuffersNames: this.options.uniformBuffers,
+                samplers: samplers || this.options.samplers,
+                defines: defines !== null ? defines : "",
+                fallbacks: null,
+                onCompiled: onCompiled ?? this.options.onCompiled,
+                onError: onError ?? null,
+                indexParameters: indexParameters || this.options.indexParameters,
+                processCodeAfterIncludes: customShaderCodeProcessing?.processCodeAfterIncludes
+                    ? (shaderType, code) => customShaderCodeProcessing.processCodeAfterIncludes(this.name, shaderType, code)
+                    : null,
+                processFinalCode: customShaderCodeProcessing?.processFinalCode
+                    ? (shaderType, code) => customShaderCodeProcessing.processFinalCode(this.name, shaderType, code)
+                    : null,
+                shaderLanguage: this.options.shaderLanguage,
+                extraInitializationsAsync,
+            }, this.options.engine);
+        }
+        else {
+            this._drawWrapper.effect = new Effect(this._shaderPath, this.options.attributeNames, uniforms || this.options.uniforms, samplers || this.options.samplerNames, this.options.engine, defines, undefined, onCompiled || this.options.onCompiled, undefined, undefined, undefined, this.options.shaderLanguage, extraInitializationsAsync);
+        }
+        this.onEffectCreatedObservable.notifyObservers(this._drawWrapper.effect);
+    }
+    /**
+     * Binds the data to the effect.
+     */
+    bind() {
+        this.options.engine.setAlphaMode(this.alphaMode);
+        if (this.options.useAsPostProcess) {
+            this.drawWrapper.effect.setFloat2("scale", 1, 1);
+        }
+        EffectWrapper._GetShaderCodeProcessing(this.name)?.bindCustomBindings?.(this.name, this._drawWrapper.effect);
     }
     /**
      * Disposes of the effect wrapper
@@ -203,7 +392,14 @@ export class EffectWrapper {
             this.effect.getEngine().onContextRestoredObservable.remove(this._onContextRestoredObserver);
             this._onContextRestoredObserver = null;
         }
+        this.onEffectCreatedObservable.clear();
         this.effect.dispose();
     }
 }
+/**
+ * Force code to compile to glsl even on WebGPU engines.
+ * False by default. This is mostly meant for backward compatibility.
+ */
+EffectWrapper.ForceGLSL = false;
+EffectWrapper._CustomShaderCodeProcessing = {};
 //# sourceMappingURL=effectRenderer.js.map