babylonjs-addons 9.26.0 → 9.26.2

package/babylonjs.addons.module.d.ts

@@ -3,6 +3,7 @@ declare module "babylonjs-addons/index" {
 export * from "babylonjs-addons/atmosphere/index";
 export * from "babylonjs-addons/htmlMesh/index";
 export * from "babylonjs-addons/msdfText/index";
+export * from "babylonjs-addons/multiTexture/index";
 export * from "babylonjs-addons/navigation/index";
 
 }
@@ -1431,6 +1432,455 @@ export function ToSoloNavMeshGeneratorConfig(config: INavMeshParametersV2): Part
  */
 export function ToCrowdAgentParams(agentParams: IAgentParametersV2): Partial<any>;
 
+}
+declare module "babylonjs-addons/multiTexture/multiTexture" {
+/**
+ * MultiTexture: composes an array of image files into a single TEXTURE_2D_ARRAY that can be
+ * assigned to a material slot like any other texture.
+ *
+ * Lives in @babylonjs/addons (not core) because it is an application-oriented, optional feature
+ * with WebGL2/WebGPU requirements, URL polling, and a non-trivial memory footprint.
+ */
+import { Nullable } from "babylonjs/types";
+import { InternalTexture } from "babylonjs/Materials/Textures/internalTexture";
+import { Scene } from "babylonjs/scene.pure";
+import { Observable } from "babylonjs/Misc/observable";
+import { BaseTexture } from "babylonjs/Materials/Textures/baseTexture.pure";
+import { ISize } from "babylonjs/Maths/math.size";
+import { ProceduralTexture } from "babylonjs/Materials/Textures/Procedurals/proceduralTexture.pure";
+import { RawTexture2DArray } from "babylonjs/Materials/Textures/rawTexture2DArray";
+/**
+ * Options for creating a MultiTexture.
+ */
+export interface IMultiTextureOptions {
+    /** Fixed layer resolution. REQUIRED. Positive integer. */
+    width: number;
+    /** Fixed layer resolution. REQUIRED. Positive integer. */
+    height: number;
+    /** Array depth to allocate. Optional positive integer; default: urls.length. Must be \>= urls.length and \<= the engine's texture2DArrayMaxLayerCount (else throw). Required when urls is empty. */
+    maxLayers?: number;
+    /** Default MultiBlendMode.ALPHA_BLEND. */
+    blendMode?: MultiBlendMode;
+    /** Default false. Passed to RawTexture2DArray: mip levels of the LAYER array. On WebGL2 they are consumed by the composite when rttScale less than 1 (trilinear minification); on WebGPU the composite fetches texels exactly, so these mips only affect direct per-layer sampling via `arrayTexture`. The composite RTT itself never has mips (consumed at 1:1 by materials). */
+    generateMipMaps?: boolean;
+    /** Default Texture.TRILINEAR_SAMPLINGMODE. Passed to RawTexture2DArray. On WebGL2 the composite shader reads the layers through this sampler, so it also drives the composite's mag/min filtering; on WebGPU the composite fetches texels exactly (see the class notes), so it only affects direct per-layer sampling via `arrayTexture`. */
+    samplingMode?: number;
+    /** Default false. Passed through to UploadImageToTexture2DArrayLayer. */
+    premultiplyAlpha?: boolean;
+    /** "resize" (default): scale to width×height. "strict": rejects mismatched dims. */
+    fit?: "resize" | "strict";
+    /** Composite RTT resolution = width*rttScale × height*rttScale. Default 1. On WebGL2 values other than 1 produce a filtered (bilinear) rescale of the composite; on WebGPU the composite fetches its texels exactly, so rttScale effectively rescales the render target without filtering. */
+    rttScale?: number;
+    /** Default false. HEAD-polling change detection. */
+    watch?: boolean;
+    /** Default 2000 ms. Only used when watch is true. */
+    pollInterval?: number;
+    /** Fired once after all initial layers have settled (success or failure). */
+    onLoad?: () => void;
+    /** Fired on any async failure (init, updateLayer, poll). Not thrown. */
+    onError?: (message?: string, exception?: any) => void;
+}
+/**
+ * Register side effects for MultiTexture.
+ * Registers the core 2D-array image-source extensions for both backends (the WebGL2
+ * `engine.texture2DArrayImageSource` and its WebGPU counterpart) lazily at first use, matching
+ * the Atmosphere addon's convention. Safe to call multiple times; only the first call has an effect.
+ */
+export function RegisterMultiTexture(): void;
+/**
+ * Composes an array of image files into a single TEXTURE_2D_ARRAY and blends the layers per pixel
+ * according to a selectable {@link MultiBlendMode}. The blended result is written to a render-target
+ * texture that can be assigned to materials like any other texture.
+ *
+ * Requires a WebGL2 or WebGPU engine (TEXTURE_2D_ARRAY + sampler2DArray). The constructor throws
+ * synchronously on WebGL1.
+ *
+ * Supported source formats are the raster formats your browser can decode with createImageBitmap
+ * (PNG, JPEG, WebP, AVIF, GIF first frame, BMP). Compressed/container formats such as KTX2 are NOT
+ * supported: the existing KTX2 transcode path goes straight to the GPU (which would bypass the
+ * CPU pixel cache this class maintains), and KTX2 containers hold the whole array in a single file
+ * (which conflicts with the one-file-per-layer-index update model).
+ *
+ * Notes:
+ * - `url` is null (the base texture loader is not used); the `urls` property is the source of truth.
+ * - By default every decoded layer is read back into a CPU `Uint8ClampedArray` (see `pixels`). This
+ *   costs one canvas readback (and a full-width×height RGBA CPU copy) per (re)load of a layer — it
+ *   runs on every initial load, `updateLayerAsync` reload, and watch-triggered reload, so frequent
+ *   reloads or large layers carry a CPU/memory cost (roughly `width × height × 4` bytes per layer).
+ * - With `premultiplyAlpha: true` the GPU layers are stored premultiplied, but the CPU `pixels`
+ *   cache still holds the raw decoded (non-premultiplied) bytes.
+ * - The default ALPHA_BLEND mode composites the layers with standard source-over blending: each
+ *   layer is drawn over the accumulated result, so later layers cover earlier ones and a fully
+ *   opaque layer hides everything below it. With straight-alpha layers (premultiplyAlpha: false)
+ *   the fold is the source-over `over` operator (`outA = layer.a + outA * (1 - layer.a)`); with
+ *   the premultiplied form (`out = layer + out * (1 - layer.a)`). The composite always outputs
+ *   straight RGBA, so materials see identical pixels regardless of `premultiplyAlpha` (which
+ *   only controls the layer storage/fold).
+ * - ALPHA_MAX picks the sample with the highest alpha; ties (equal alpha) resolve to the highest
+ *   layer index (last input draws over earlier ones).
+ * - With zero active layers, ALPHA_BLEND/ALPHA_MAX/ADD/SUBTRACT/SCREEN output transparent black
+ *   and MULTIPLY outputs white (empty-product identity).
+ * - Compositing is performed independently of the scene render loop: MultiTexture re-composites
+ *   its internal render target explicitly after every mutation (layer add/insert/remove/update,
+ *   blend-mode change, array growth), so `scene.proceduralTexturesEnabled` has no effect on it.
+ * - How the composite samples the layer array depends on the engine backend, but both are
+ *   filtered and honour `samplingMode`. On WebGL2 the GLSL composite shader reads the layers
+ *   through the array sampler (`texture(...)`), so `samplingMode` affects the output, `rttScale`
+ *   other than 1 produces a filtered bilinear rescale, and (with `generateMipMaps: true`)
+ *   trilinear minification can use the layer mips. On WebGPU the WGSL composite shader samples
+ *   the layer array through its sampler at mip 0 (`textureSampleLevel(..., 0.0)`), so `samplingMode`
+ *   affects the output but only mip-0 filtering applies (no mip-level selection) and `rttScale`
+ *   rescale is filtered at mip 0. The `_arrayTexture` sampler that materials use to read the
+ *   per-layer array is unaffected by this backend difference.
+ * - `MultiTexture` lives in `@babylonjs/addons` and lazily registers the core 2D-array
+ *   image-source extensions on first construction, matching the `Atmosphere` addon's convention.
+ *   No engine mutation occurs at addons import time. `RegisterMultiTexture()` calls both the WebGL2
+ *   (`engine.texture2DArrayImageSource`) and WebGPU pure registration functions, so a pure/tree-shaken
+ *   WebGPU build receives `updateTextureArrayLayerFromImageSource` without any extra consumer import.
+ * - The allocated array depth (options.maxLayers ?? urls.length) must be a positive integer and no
+ *   larger than the device limit getCaps().texture2DArrayMaxLayerCount. Empty urls are only accepted
+ *   together with an explicit options.maxLayers. addLayerAsync/insertLayerAsync double the depth when it is
+ *   full and throw a RangeError if the doubled depth would exceed that limit.
+ */
+export class MultiTexture extends BaseTexture {
+    /**
+     * The internal ProceduralTexture that composites the layers into the render-target texture
+     * assigned to materials. MultiTexture composes, rather than extends, ProceduralTexture: it
+     * creates this composite with `skipSceneRegistration: true` so the scene render loop does not
+     * drive it, and calls {@link _renderComposite} explicitly after each mutation. All texture
+     * surface methods (isReady/getInternalTexture) forward to it.
+     */
+    get composite(): ProceduralTexture;
+    private _compositeInternal;
+    /** Fired once after all initial layers have settled (success or failure). */
+    readonly onLoadObservable: Observable<MultiTexture>;
+    private _layers;
+    private _layerCount;
+    private _maxLayers;
+    private _deviceMaxLayerCap;
+    private _blendMode;
+    private _pollTimer;
+    /** True while a _poll() tick is in flight; overlapping interval firings early-return so a slow tick never double-fetches. */
+    private _pollInFlight;
+    private _canvas;
+    private _ctx;
+    private _disposed;
+    private _mtOptions;
+    private _arrayTexture;
+    /** Number of in-flight mip-suppressed operations (init pool + mutations). See _suppressArrayMips. */
+    private _mipSuppressCount;
+    /**
+     * Number of active layers (drives the uLayerCount uniform). Changes only via addLayerAsync/removeLayerAsync.
+     */
+    get layerCount(): number;
+    /**
+     * The underlying TEXTURE_2D_ARRAY, for users who want to sample individual layers directly.
+     */
+    get arrayTexture(): RawTexture2DArray;
+    /**
+     * Forwards to the internal composite: the render-target texture that composites the layers is
+     * owned by the composite, so the material samples it through here.
+     * @returns The composite's internal texture.
+     */
+    getInternalTexture(): Nullable<InternalTexture>;
+    /**
+     * Forwards to the internal composite: ready once the composite's render-target texture is ready.
+     * @returns True if the composite's render-target texture is ready, otherwise false.
+     */
+    isReady(): boolean;
+    /**
+     * Renders the internal composite, applying the current layer uploads and blend mode.
+     * The composite only draws once its effect is compiled (shaders load asynchronously), so the
+     * first render is deferred to the compiled callback instead of drawing a stale/empty target.
+     */
+    private _renderComposite;
+    /**
+     * Forwards to the composite: the composite render-target is what materials sample.
+     * @returns The composite render-target size.
+     */
+    getSize(): ISize;
+    /**
+     * Forwards to the composite: the composite render-target base size is what materials sample.
+     * @returns The composite render-target base size.
+     */
+    getBaseSize(): ISize;
+    /**
+     * Forwards to the composite's sampling mode.
+     * @returns the composite render-target's sampling mode.
+     */
+    get samplingMode(): number;
+    /**
+     * Forwards to the composite, which owns the render-target texture the material binds.
+     * @param samplingMode the new sampling mode
+     * @param generateMipMaps whether to generate mip maps
+     */
+    updateSamplingMode(samplingMode: number, generateMipMaps?: boolean): void;
+    /**
+     * Forwards to the composite's render-target texture.
+     * @param faceIndex defines the face of the texture to read (in case of cube texture)
+     * @param level defines the LOD level of the texture to read (in case of Mip Maps)
+     * @param buffer defines a user defined buffer to fill with data (can be null)
+     * @param flushRenderer true to flush the renderer from the pending commands before reading the pixels
+     * @param noDataConversion false to convert the data to Uint8Array (if texture type is UNSIGNED_BYTE) or to Float32Array (if texture type is anything but UNSIGNED_BYTE). If true, the type of the generated buffer (if buffer==null) will depend on the type of the texture
+     * @param x defines the region x coordinates to start reading from (default to 0)
+     * @param y defines the region y coordinates to start reading from (default to 0)
+     * @param width defines the region width to read from (default to the texture size at level)
+     * @param height defines the region width to read from (default to the texture size at level)
+     * @returns the composite render-target's pixel buffer promise.
+     */
+    readPixels(faceIndex?: number, level?: number, buffer?: Nullable<ArrayBufferView>, flushRenderer?: boolean, noDataConversion?: boolean, x?: number, y?: number, width?: number, height?: number): Nullable<Promise<ArrayBufferView>>;
+    /**
+     * Forwards to the composite's render-target texture.
+     * @param faceIndex defines the face of the texture to read (in case of cube texture)
+     * @param level defines the LOD level of the texture to read (in case of Mip Maps)
+     * @param buffer defines a user defined buffer to fill with data (can be null)
+     * @param flushRenderer true to flush the renderer from the pending commands before reading the pixels
+     * @param noDataConversion false to convert the data to Uint8Array (if texture type is UNSIGNED_BYTE) or to Float32Array (if texture type is anything but UNSIGNED_BYTE). If true, the type of the generated buffer (if buffer==null) will depend on the type of the texture
+     * @returns the composite render-target's pixel buffer.
+     */
+    _readPixelsSync(faceIndex?: number, level?: number, buffer?: Nullable<ArrayBufferView>, flushRenderer?: boolean, noDataConversion?: boolean): Nullable<ArrayBufferView>;
+    /**
+     * Forwards to the composite render-target's format.
+     * @returns the composite render-target's internal format.
+     */
+    get textureFormat(): number;
+    /**
+     * Forwards to the composite render-target's type.
+     * @returns the composite render-target's internal type.
+     */
+    get textureType(): number;
+    /**
+     * The input URLs, in layer order. Updated by addLayerAsync/insertLayerAsync/removeLayerAsync/updateLayerAsync.
+     */
+    readonly urls: string[];
+    /**
+     * CPU pixel cache. `pixels[i]` is a full `width × height × 4` RGBA (non-premultiplied) copy of
+     * decoded layer i, or `null` if that layer has not loaded (yet) or failed to load. It is
+     * repopulated on every (re)load of a layer (initial load, `updateLayerAsync`, watch reload) and
+     * cleared on dispose. Memory footprint is approximately `width × height × 4` bytes per loaded
+     * layer; skip it if you only need the GPU composite and do not read `pixels`.
+     */
+    readonly pixels: Array<Uint8ClampedArray | null>;
+    /**
+     * Creates a new MultiTexture.
+     * @param name defines the name of the texture
+     * @param urls defines the array of image URLs to load as layers
+     * @param scene defines the hosting scene
+     * @param options defines the creation options (width/height required)
+     */
+    constructor(name: string, urls: string[], scene: Scene, options: IMultiTextureOptions);
+    /**
+     * How the layers combine. Setting it swaps the composite fragment shader and triggers one
+     * re-composite.
+     */
+    get blendMode(): MultiBlendMode;
+    set blendMode(value: MultiBlendMode);
+    /**
+     * Replaces a layer by URL. Fetches, decodes and uploads layer i only.
+     * Exactly one texSubImage3D is issued for the target layer; uLayerCount is unchanged.
+     * @param index defines the layer index to replace
+     * @param url defines the new source for the layer
+     * @returns a promise resolving once the layer has been uploaded
+     */
+    updateLayerAsync(index: number, url: string): Promise<void>;
+    /**
+     * Appends a new layer at the end and returns its index. Grows the underlying array (doubling its
+     * depth and re-uploading the existing layers from their retained bitmaps) when the current depth
+     * is exhausted. Throws a RangeError if the doubled depth would exceed the device's
+     * texture2DArrayMaxLayerCount.
+     * @param url defines the URL of the image to load as the new layer
+     * @returns a promise resolving to the index of the new layer
+     */
+    addLayerAsync(url: string): Promise<number>;
+    /**
+     * Inserts a new layer at the given index and returns it. Layers at index and above shift up by
+     * one: loaded layers are re-uploaded from their retained bitmaps, and a shifted layer that is
+     * still loading lands in its new slot when its in-flight load settles (loads resolve against
+     * their layer entry, never against a stale index). uLayerCount is incremented. Inserting at
+     * `layerCount` appends (addLayerAsync-equivalent). Grows the underlying array (doubling its depth)
+     * when the current depth is exhausted, same as addLayerAsync, and throws a RangeError if the doubled
+     * depth would exceed the device's texture2DArrayMaxLayerCount.
+     * @param index defines the layer index to insert at (0..layerCount, inclusive)
+     * @param url defines the URL of the image to load as the new layer
+     * @returns a promise resolving to the index of the inserted layer
+     */
+    insertLayerAsync(index: number, url: string): Promise<number>;
+    /**
+     * Removes a layer. Higher indices shift down (re-uploaded from their retained bitmaps) and
+     * uLayerCount is decremented.
+     * @param index defines the layer index to remove
+     * @returns a promise resolving once the shift is done
+     */
+    removeLayerAsync(index: number): Promise<void>;
+    /**
+     * Disposes the texture: stops the watch poller, closes every retained bitmap, disposes the layer
+     * array and releases the composite render target through the standard procedural-texture path.
+     */
+    dispose(): void;
+    /**
+     * Clones the texture: builds a fresh MultiTexture in the same scene with the same name, the
+     * current layer urls and the resolved options (layer resolution, current array capacity,
+     * current blend mode, sampling mode, mipmap generation, RTT scale, fit and watch settings).
+     * The clone re-fetches and re-decodes its layers from scratch; it never shares the 2D array
+     * texture, the pixel cache or the load callbacks (onLoad/onError are not inherited).
+     * @returns the cloned texture
+     */
+    clone(): MultiTexture;
+    /**
+     * MultiTexture is intentionally not scene-serializable: the scene loader has no parser for it,
+     * so the payload produced by the inherited base serialization could never be reconstructed
+     * (urls, capacity, blend mode and watch options have no serialized fields). Fails explicitly
+     * instead of returning a misleading JSON object.
+     * @param _allowEmptyName accepted for signature compatibility; ignored
+     * @throws Error always
+     */
+    serialize(_allowEmptyName?: boolean): never;
+    private _buildDefines;
+    private _bitmapOptions;
+    private _reportError;
+    private _createLayerEntry;
+    private _loadEntryOrThrow;
+    private _loadEntryAndReport;
+    private _warnWatchFailure;
+    private _uploadToLayer;
+    private _reuploadSlot;
+    private _clearLayerSlot;
+    private _loadEntry;
+    private _uploadBitmap;
+    private _initialize;
+    private _pushLayerEntry;
+    private _growArray;
+    private _suppressArrayMips;
+    private _generateArrayMips;
+    private _startPolling;
+    private _poll;
+}
+/**
+ * Blend modes controlling how the layers of a MultiTexture are combined per pixel.
+ */
+export enum MultiBlendMode {
+    /**
+     * Default. Composites the layers with standard source-over alpha blending: each layer is drawn
+     * over the accumulated result, so later layers cover earlier ones and a fully opaque layer
+     * (a = 1) completely hides everything below it. With straight-alpha layers (premultiplyAlpha:
+     * false) the fold is `outA = layer.a + outA * (1 - layer.a)`; with premultiplied layers it is
+     * the premultiplied form `out = layer + out * (1 - layer.a)`. The composite always outputs
+     * straight RGBA, so materials see identical pixels regardless of `premultiplyAlpha` (which
+     * only controls the layer storage/fold). Zero active layers output transparent black.
+     */
+    ALPHA_BLEND = 0,
+    /** Keeps the sample with the highest alpha among the layers (ties: highest index wins). Zero active layers output transparent black. */
+    ALPHA_MAX = 1,
+    /** Adds all layers per channel, clamped to 1. */
+    ADD = 2,
+    /** Multiplies all layers per channel (empty product is 1). */
+    MULTIPLY = 3,
+    /** Starts from layer 0 and subtracts every following layer, clamped to 0. */
+    SUBTRACT = 4,
+    /** Screens all layers per channel. */
+    SCREEN = 5
+}
+
+}
+declare module "babylonjs-addons/multiTexture/index" {
+export * from "babylonjs-addons/multiTexture/multiTexture";
+
+}
+declare module "babylonjs-addons/multiTexture/ShadersWGSL/multiTextureCompositeSubtract.fragment" {
+/** @internal */
+export const multiTextureCompositeSubtractPixelShaderWGSL: {
+    name: string;
+    shader: string;
+};
+
+}
+declare module "babylonjs-addons/multiTexture/ShadersWGSL/multiTextureCompositeScreen.fragment" {
+/** @internal */
+export const multiTextureCompositeScreenPixelShaderWGSL: {
+    name: string;
+    shader: string;
+};
+
+}
+declare module "babylonjs-addons/multiTexture/ShadersWGSL/multiTextureCompositeMultiply.fragment" {
+/** @internal */
+export const multiTextureCompositeMultiplyPixelShaderWGSL: {
+    name: string;
+    shader: string;
+};
+
+}
+declare module "babylonjs-addons/multiTexture/ShadersWGSL/multiTextureCompositeAlphaMax.fragment" {
+/** @internal */
+export const multiTextureCompositeAlphaMaxPixelShaderWGSL: {
+    name: string;
+    shader: string;
+};
+
+}
+declare module "babylonjs-addons/multiTexture/ShadersWGSL/multiTextureCompositeAlphaBlend.fragment" {
+/** @internal */
+export const multiTextureCompositeAlphaBlendPixelShaderWGSL: {
+    name: string;
+    shader: string;
+};
+
+}
+declare module "babylonjs-addons/multiTexture/ShadersWGSL/multiTextureCompositeAdd.fragment" {
+/** @internal */
+export const multiTextureCompositeAddPixelShaderWGSL: {
+    name: string;
+    shader: string;
+};
+
+}
+declare module "babylonjs-addons/multiTexture/Shaders/multiTextureCompositeSubtract.fragment" {
+/** @internal */
+export const multiTextureCompositeSubtractPixelShader: {
+    name: string;
+    shader: string;
+};
+
+}
+declare module "babylonjs-addons/multiTexture/Shaders/multiTextureCompositeScreen.fragment" {
+/** @internal */
+export const multiTextureCompositeScreenPixelShader: {
+    name: string;
+    shader: string;
+};
+
+}
+declare module "babylonjs-addons/multiTexture/Shaders/multiTextureCompositeMultiply.fragment" {
+/** @internal */
+export const multiTextureCompositeMultiplyPixelShader: {
+    name: string;
+    shader: string;
+};
+
+}
+declare module "babylonjs-addons/multiTexture/Shaders/multiTextureCompositeAlphaMax.fragment" {
+/** @internal */
+export const multiTextureCompositeAlphaMaxPixelShader: {
+    name: string;
+    shader: string;
+};
+
+}
+declare module "babylonjs-addons/multiTexture/Shaders/multiTextureCompositeAlphaBlend.fragment" {
+/** @internal */
+export const multiTextureCompositeAlphaBlendPixelShader: {
+    name: string;
+    shader: string;
+};
+
+}
+declare module "babylonjs-addons/multiTexture/Shaders/multiTextureCompositeAdd.fragment" {
+/** @internal */
+export const multiTextureCompositeAddPixelShader: {
+    name: string;
+    shader: string;
+};
+
 }
 declare module "babylonjs-addons/msdfText/textRenderer" {
 import { AbstractEngine } from "babylonjs/Engines/abstractEngine";
@@ -4910,6 +5360,432 @@ declare namespace ADDONS {
     export function ToCrowdAgentParams(agentParams: IAgentParametersV2): Partial<any>;
 
 
+    /**
+     * MultiTexture: composes an array of image files into a single TEXTURE_2D_ARRAY that can be
+     * assigned to a material slot like any other texture.
+     *
+     * Lives in @babylonjs/addons (not core) because it is an application-oriented, optional feature
+     * with WebGL2/WebGPU requirements, URL polling, and a non-trivial memory footprint.
+     */
+    /**
+     * Options for creating a MultiTexture.
+     */
+    export interface IMultiTextureOptions {
+        /** Fixed layer resolution. REQUIRED. Positive integer. */
+        width: number;
+        /** Fixed layer resolution. REQUIRED. Positive integer. */
+        height: number;
+        /** Array depth to allocate. Optional positive integer; default: urls.length. Must be \>= urls.length and \<= the engine's texture2DArrayMaxLayerCount (else throw). Required when urls is empty. */
+        maxLayers?: number;
+        /** Default MultiBlendMode.ALPHA_BLEND. */
+        blendMode?: MultiBlendMode;
+        /** Default false. Passed to BABYLON.RawTexture2DArray: mip levels of the LAYER array. On WebGL2 they are consumed by the composite when rttScale less than 1 (trilinear minification); on WebGPU the composite fetches texels exactly, so these mips only affect direct per-layer sampling via `arrayTexture`. The composite RTT itself never has mips (consumed at 1:1 by materials). */
+        generateMipMaps?: boolean;
+        /** Default Texture.TRILINEAR_SAMPLINGMODE. Passed to BABYLON.RawTexture2DArray. On WebGL2 the composite shader reads the layers through this sampler, so it also drives the composite's mag/min filtering; on WebGPU the composite fetches texels exactly (see the class notes), so it only affects direct per-layer sampling via `arrayTexture`. */
+        samplingMode?: number;
+        /** Default false. Passed through to UploadImageToTexture2DArrayLayer. */
+        premultiplyAlpha?: boolean;
+        /** "resize" (default): scale to width×height. "strict": rejects mismatched dims. */
+        fit?: "resize" | "strict";
+        /** Composite RTT resolution = width*rttScale × height*rttScale. Default 1. On WebGL2 values other than 1 produce a filtered (bilinear) rescale of the composite; on WebGPU the composite fetches its texels exactly, so rttScale effectively rescales the render target without filtering. */
+        rttScale?: number;
+        /** Default false. HEAD-polling change detection. */
+        watch?: boolean;
+        /** Default 2000 ms. Only used when watch is true. */
+        pollInterval?: number;
+        /** Fired once after all initial layers have settled (success or failure). */
+        onLoad?: () => void;
+        /** Fired on any async failure (init, updateLayer, poll). Not thrown. */
+        onError?: (message?: string, exception?: any) => void;
+    }
+    /**
+     * Register side effects for MultiTexture.
+     * Registers the core 2D-array image-source extensions for both backends (the WebGL2
+     * `engine.texture2DArrayImageSource` and its WebGPU counterpart) lazily at first use, matching
+     * the Atmosphere addon's convention. Safe to call multiple times; only the first call has an effect.
+     */
+    export function RegisterMultiTexture(): void;
+    /**
+     * Composes an array of image files into a single TEXTURE_2D_ARRAY and blends the layers per pixel
+     * according to a selectable {@link MultiBlendMode}. The blended result is written to a render-target
+     * texture that can be assigned to materials like any other texture.
+     *
+     * Requires a WebGL2 or WebGPU engine (TEXTURE_2D_ARRAY + sampler2DArray). The constructor throws
+     * synchronously on WebGL1.
+     *
+     * Supported source formats are the raster formats your browser can decode with createImageBitmap
+     * (PNG, JPEG, WebP, AVIF, GIF first frame, BMP). Compressed/container formats such as KTX2 are NOT
+     * supported: the existing KTX2 transcode path goes straight to the GPU (which would bypass the
+     * CPU pixel cache this class maintains), and KTX2 containers hold the whole array in a single file
+     * (which conflicts with the one-file-per-layer-index update model).
+     *
+     * Notes:
+     * - `url` is null (the base texture loader is not used); the `urls` property is the source of truth.
+     * - By default every decoded layer is read back into a CPU `Uint8ClampedArray` (see `pixels`). This
+     *   costs one canvas readback (and a full-width×height RGBA CPU copy) per (re)load of a layer — it
+     *   runs on every initial load, `updateLayerAsync` reload, and watch-triggered reload, so frequent
+     *   reloads or large layers carry a CPU/memory cost (roughly `width × height × 4` bytes per layer).
+     * - With `premultiplyAlpha: true` the GPU layers are stored premultiplied, but the CPU `pixels`
+     *   cache still holds the raw decoded (non-premultiplied) bytes.
+     * - The default ALPHA_BLEND mode composites the layers with standard source-over blending: each
+     *   layer is drawn over the accumulated result, so later layers cover earlier ones and a fully
+     *   opaque layer hides everything below it. With straight-alpha layers (premultiplyAlpha: false)
+     *   the fold is the source-over `over` operator (`outA = layer.a + outA * (1 - layer.a)`); with
+     *   the premultiplied form (`out = layer + out * (1 - layer.a)`). The composite always outputs
+     *   straight RGBA, so materials see identical pixels regardless of `premultiplyAlpha` (which
+     *   only controls the layer storage/fold).
+     * - ALPHA_MAX picks the sample with the highest alpha; ties (equal alpha) resolve to the highest
+     *   layer index (last input draws over earlier ones).
+     * - With zero active layers, ALPHA_BLEND/ALPHA_MAX/ADD/SUBTRACT/SCREEN output transparent black
+     *   and MULTIPLY outputs white (empty-product identity).
+     * - Compositing is performed independently of the scene render loop: MultiTexture re-composites
+     *   its internal render target explicitly after every mutation (layer add/insert/remove/update,
+     *   blend-mode change, array growth), so `scene.proceduralTexturesEnabled` has no effect on it.
+     * - How the composite samples the layer array depends on the engine backend, but both are
+     *   filtered and honour `samplingMode`. On WebGL2 the GLSL composite shader reads the layers
+     *   through the array sampler (`texture(...)`), so `samplingMode` affects the output, `rttScale`
+     *   other than 1 produces a filtered bilinear rescale, and (with `generateMipMaps: true`)
+     *   trilinear minification can use the layer mips. On WebGPU the WGSL composite shader samples
+     *   the layer array through its sampler at mip 0 (`textureSampleLevel(..., 0.0)`), so `samplingMode`
+     *   affects the output but only mip-0 filtering applies (no mip-level selection) and `rttScale`
+     *   rescale is filtered at mip 0. The `_arrayTexture` sampler that materials use to read the
+     *   per-layer array is unaffected by this backend difference.
+     * - `MultiTexture` lives in `@babylonjs/addons` and lazily registers the core 2D-array
+     *   image-source extensions on first construction, matching the `Atmosphere` addon's convention.
+     *   No engine mutation occurs at addons import time. `RegisterMultiTexture()` calls both the WebGL2
+     *   (`engine.texture2DArrayImageSource`) and WebGPU pure registration functions, so a pure/tree-shaken
+     *   WebGPU build receives `updateTextureArrayLayerFromImageSource` without any extra consumer import.
+     * - The allocated array depth (options.maxLayers ?? urls.length) must be a positive integer and no
+     *   larger than the device limit getCaps().texture2DArrayMaxLayerCount. Empty urls are only accepted
+     *   together with an explicit options.maxLayers. addLayerAsync/insertLayerAsync double the depth when it is
+     *   full and throw a RangeError if the doubled depth would exceed that limit.
+     */
+    export class MultiTexture extends BABYLON.BaseTexture {
+        /**
+         * The internal BABYLON.ProceduralTexture that composites the layers into the render-target texture
+         * assigned to materials. MultiTexture composes, rather than extends, BABYLON.ProceduralTexture: it
+         * creates this composite with `skipSceneRegistration: true` so the scene render loop does not
+         * drive it, and calls {@link _renderComposite} explicitly after each mutation. All texture
+         * surface methods (isReady/getInternalTexture) forward to it.
+         */
+        get composite(): BABYLON.ProceduralTexture;
+        private _compositeInternal;
+        /** Fired once after all initial layers have settled (success or failure). */
+        readonly onLoadObservable: BABYLON.Observable<MultiTexture>;
+        private _layers;
+        private _layerCount;
+        private _maxLayers;
+        private _deviceMaxLayerCap;
+        private _blendMode;
+        private _pollTimer;
+        /** True while a _poll() tick is in flight; overlapping interval firings early-return so a slow tick never double-fetches. */
+        private _pollInFlight;
+        private _canvas;
+        private _ctx;
+        private _disposed;
+        private _mtOptions;
+        private _arrayTexture;
+        /** Number of in-flight mip-suppressed operations (init pool + mutations). See _suppressArrayMips. */
+        private _mipSuppressCount;
+        /**
+         * Number of active layers (drives the uLayerCount uniform). Changes only via addLayerAsync/removeLayerAsync.
+         */
+        get layerCount(): number;
+        /**
+         * The underlying TEXTURE_2D_ARRAY, for users who want to sample individual layers directly.
+         */
+        get arrayTexture(): BABYLON.RawTexture2DArray;
+        /**
+         * Forwards to the internal composite: the render-target texture that composites the layers is
+         * owned by the composite, so the material samples it through here.
+         * @returns The composite's internal texture.
+         */
+        getInternalTexture(): BABYLON.Nullable<BABYLON.InternalTexture>;
+        /**
+         * Forwards to the internal composite: ready once the composite's render-target texture is ready.
+         * @returns True if the composite's render-target texture is ready, otherwise false.
+         */
+        isReady(): boolean;
+        /**
+         * Renders the internal composite, applying the current layer uploads and blend mode.
+         * The composite only draws once its effect is compiled (shaders load asynchronously), so the
+         * first render is deferred to the compiled callback instead of drawing a stale/empty target.
+         */
+        private _renderComposite;
+        /**
+         * Forwards to the composite: the composite render-target is what materials sample.
+         * @returns The composite render-target size.
+         */
+        getSize(): BABYLON.ISize;
+        /**
+         * Forwards to the composite: the composite render-target base size is what materials sample.
+         * @returns The composite render-target base size.
+         */
+        getBaseSize(): BABYLON.ISize;
+        /**
+         * Forwards to the composite's sampling mode.
+         * @returns the composite render-target's sampling mode.
+         */
+        get samplingMode(): number;
+        /**
+         * Forwards to the composite, which owns the render-target texture the material binds.
+         * @param samplingMode the new sampling mode
+         * @param generateMipMaps whether to generate mip maps
+         */
+        updateSamplingMode(samplingMode: number, generateMipMaps?: boolean): void;
+        /**
+         * Forwards to the composite's render-target texture.
+         * @param faceIndex defines the face of the texture to read (in case of cube texture)
+         * @param level defines the LOD level of the texture to read (in case of Mip Maps)
+         * @param buffer defines a user defined buffer to fill with data (can be null)
+         * @param flushRenderer true to flush the renderer from the pending commands before reading the pixels
+         * @param noDataConversion false to convert the data to Uint8Array (if texture type is UNSIGNED_BYTE) or to Float32Array (if texture type is anything but UNSIGNED_BYTE). If true, the type of the generated buffer (if buffer==null) will depend on the type of the texture
+         * @param x defines the region x coordinates to start reading from (default to 0)
+         * @param y defines the region y coordinates to start reading from (default to 0)
+         * @param width defines the region width to read from (default to the texture size at level)
+         * @param height defines the region width to read from (default to the texture size at level)
+         * @returns the composite render-target's pixel buffer promise.
+         */
+        readPixels(faceIndex?: number, level?: number, buffer?: BABYLON.Nullable<ArrayBufferView>, flushRenderer?: boolean, noDataConversion?: boolean, x?: number, y?: number, width?: number, height?: number): BABYLON.Nullable<Promise<ArrayBufferView>>;
+        /**
+         * Forwards to the composite's render-target texture.
+         * @param faceIndex defines the face of the texture to read (in case of cube texture)
+         * @param level defines the LOD level of the texture to read (in case of Mip Maps)
+         * @param buffer defines a user defined buffer to fill with data (can be null)
+         * @param flushRenderer true to flush the renderer from the pending commands before reading the pixels
+         * @param noDataConversion false to convert the data to Uint8Array (if texture type is UNSIGNED_BYTE) or to Float32Array (if texture type is anything but UNSIGNED_BYTE). If true, the type of the generated buffer (if buffer==null) will depend on the type of the texture
+         * @returns the composite render-target's pixel buffer.
+         */
+        _readPixelsSync(faceIndex?: number, level?: number, buffer?: BABYLON.Nullable<ArrayBufferView>, flushRenderer?: boolean, noDataConversion?: boolean): BABYLON.Nullable<ArrayBufferView>;
+        /**
+         * Forwards to the composite render-target's format.
+         * @returns the composite render-target's internal format.
+         */
+        get textureFormat(): number;
+        /**
+         * Forwards to the composite render-target's type.
+         * @returns the composite render-target's internal type.
+         */
+        get textureType(): number;
+        /**
+         * The input URLs, in layer order. Updated by addLayerAsync/insertLayerAsync/removeLayerAsync/updateLayerAsync.
+         */
+        readonly urls: string[];
+        /**
+         * CPU pixel cache. `pixels[i]` is a full `width × height × 4` RGBA (non-premultiplied) copy of
+         * decoded layer i, or `null` if that layer has not loaded (yet) or failed to load. It is
+         * repopulated on every (re)load of a layer (initial load, `updateLayerAsync`, watch reload) and
+         * cleared on dispose. Memory footprint is approximately `width × height × 4` bytes per loaded
+         * layer; skip it if you only need the GPU composite and do not read `pixels`.
+         */
+        readonly pixels: Array<Uint8ClampedArray | null>;
+        /**
+         * Creates a new MultiTexture.
+         * @param name defines the name of the texture
+         * @param urls defines the array of image URLs to load as layers
+         * @param scene defines the hosting scene
+         * @param options defines the creation options (width/height required)
+         */
+        constructor(name: string, urls: string[], scene: BABYLON.Scene, options: IMultiTextureOptions);
+        /**
+         * How the layers combine. Setting it swaps the composite fragment shader and triggers one
+         * re-composite.
+         */
+        get blendMode(): MultiBlendMode;
+        set blendMode(value: MultiBlendMode);
+        /**
+         * Replaces a layer by URL. Fetches, decodes and uploads layer i only.
+         * Exactly one texSubImage3D is issued for the target layer; uLayerCount is unchanged.
+         * @param index defines the layer index to replace
+         * @param url defines the new source for the layer
+         * @returns a promise resolving once the layer has been uploaded
+         */
+        updateLayerAsync(index: number, url: string): Promise<void>;
+        /**
+         * Appends a new layer at the end and returns its index. Grows the underlying array (doubling its
+         * depth and re-uploading the existing layers from their retained bitmaps) when the current depth
+         * is exhausted. Throws a RangeError if the doubled depth would exceed the device's
+         * texture2DArrayMaxLayerCount.
+         * @param url defines the URL of the image to load as the new layer
+         * @returns a promise resolving to the index of the new layer
+         */
+        addLayerAsync(url: string): Promise<number>;
+        /**
+         * Inserts a new layer at the given index and returns it. Layers at index and above shift up by
+         * one: loaded layers are re-uploaded from their retained bitmaps, and a shifted layer that is
+         * still loading lands in its new slot when its in-flight load settles (loads resolve against
+         * their layer entry, never against a stale index). uLayerCount is incremented. Inserting at
+         * `layerCount` appends (addLayerAsync-equivalent). Grows the underlying array (doubling its depth)
+         * when the current depth is exhausted, same as addLayerAsync, and throws a RangeError if the doubled
+         * depth would exceed the device's texture2DArrayMaxLayerCount.
+         * @param index defines the layer index to insert at (0..layerCount, inclusive)
+         * @param url defines the URL of the image to load as the new layer
+         * @returns a promise resolving to the index of the inserted layer
+         */
+        insertLayerAsync(index: number, url: string): Promise<number>;
+        /**
+         * Removes a layer. Higher indices shift down (re-uploaded from their retained bitmaps) and
+         * uLayerCount is decremented.
+         * @param index defines the layer index to remove
+         * @returns a promise resolving once the shift is done
+         */
+        removeLayerAsync(index: number): Promise<void>;
+        /**
+         * Disposes the texture: stops the watch poller, closes every retained bitmap, disposes the layer
+         * array and releases the composite render target through the standard procedural-texture path.
+         */
+        dispose(): void;
+        /**
+         * Clones the texture: builds a fresh MultiTexture in the same scene with the same name, the
+         * current layer urls and the resolved options (layer resolution, current array capacity,
+         * current blend mode, sampling mode, mipmap generation, RTT scale, fit and watch settings).
+         * The clone re-fetches and re-decodes its layers from scratch; it never shares the 2D array
+         * texture, the pixel cache or the load callbacks (onLoad/onError are not inherited).
+         * @returns the cloned texture
+         */
+        clone(): MultiTexture;
+        /**
+         * MultiTexture is intentionally not scene-serializable: the scene loader has no parser for it,
+         * so the payload produced by the inherited base serialization could never be reconstructed
+         * (urls, capacity, blend mode and watch options have no serialized fields). Fails explicitly
+         * instead of returning a misleading JSON object.
+         * @param _allowEmptyName accepted for signature compatibility; ignored
+         * @throws Error always
+         */
+        serialize(_allowEmptyName?: boolean): never;
+        private _buildDefines;
+        private _bitmapOptions;
+        private _reportError;
+        private _createLayerEntry;
+        private _loadEntryOrThrow;
+        private _loadEntryAndReport;
+        private _warnWatchFailure;
+        private _uploadToLayer;
+        private _reuploadSlot;
+        private _clearLayerSlot;
+        private _loadEntry;
+        private _uploadBitmap;
+        private _initialize;
+        private _pushLayerEntry;
+        private _growArray;
+        private _suppressArrayMips;
+        private _generateArrayMips;
+        private _startPolling;
+        private _poll;
+    }
+    /**
+     * Blend modes controlling how the layers of a MultiTexture are combined per pixel.
+     */
+    export enum MultiBlendMode {
+        /**
+         * Default. Composites the layers with standard source-over alpha blending: each layer is drawn
+         * over the accumulated result, so later layers cover earlier ones and a fully opaque layer
+         * (a = 1) completely hides everything below it. With straight-alpha layers (premultiplyAlpha:
+         * false) the fold is `outA = layer.a + outA * (1 - layer.a)`; with premultiplied layers it is
+         * the premultiplied form `out = layer + out * (1 - layer.a)`. The composite always outputs
+         * straight RGBA, so materials see identical pixels regardless of `premultiplyAlpha` (which
+         * only controls the layer storage/fold). Zero active layers output transparent black.
+         */
+        ALPHA_BLEND = 0,
+        /** Keeps the sample with the highest alpha among the layers (ties: highest index wins). Zero active layers output transparent black. */
+        ALPHA_MAX = 1,
+        /** Adds all layers per channel, clamped to 1. */
+        ADD = 2,
+        /** Multiplies all layers per channel (empty product is 1). */
+        MULTIPLY = 3,
+        /** Starts from layer 0 and subtracts every following layer, clamped to 0. */
+        SUBTRACT = 4,
+        /** Screens all layers per channel. */
+        SCREEN = 5
+    }
+
+
+
+
+    /** @internal */
+    export var multiTextureCompositeSubtractPixelShaderWGSL: {
+        name: string;
+        shader: string;
+    };
+
+
+    /** @internal */
+    export var multiTextureCompositeScreenPixelShaderWGSL: {
+        name: string;
+        shader: string;
+    };
+
+
+    /** @internal */
+    export var multiTextureCompositeMultiplyPixelShaderWGSL: {
+        name: string;
+        shader: string;
+    };
+
+
+    /** @internal */
+    export var multiTextureCompositeAlphaMaxPixelShaderWGSL: {
+        name: string;
+        shader: string;
+    };
+
+
+    /** @internal */
+    export var multiTextureCompositeAlphaBlendPixelShaderWGSL: {
+        name: string;
+        shader: string;
+    };
+
+
+    /** @internal */
+    export var multiTextureCompositeAddPixelShaderWGSL: {
+        name: string;
+        shader: string;
+    };
+
+
+    /** @internal */
+    export var multiTextureCompositeSubtractPixelShader: {
+        name: string;
+        shader: string;
+    };
+
+
+    /** @internal */
+    export var multiTextureCompositeScreenPixelShader: {
+        name: string;
+        shader: string;
+    };
+
+
+    /** @internal */
+    export var multiTextureCompositeMultiplyPixelShader: {
+        name: string;
+        shader: string;
+    };
+
+
+    /** @internal */
+    export var multiTextureCompositeAlphaMaxPixelShader: {
+        name: string;
+        shader: string;
+    };
+
+
+    /** @internal */
+    export var multiTextureCompositeAlphaBlendPixelShader: {
+        name: string;
+        shader: string;
+    };
+
+
+    /** @internal */
+    export var multiTextureCompositeAddPixelShader: {
+        name: string;
+        shader: string;
+    };
+
+
     /**
      * Abstract Node class from Babylon.js
      */