@babylonjs/addons 9.26.0 → 9.26.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/index.d.ts +1 -0
  2. package/index.js +1 -0
  3. package/index.js.map +1 -1
  4. package/multiTexture/Shaders/multiTextureCompositeAdd.fragment.d.ts +5 -0
  5. package/multiTexture/Shaders/multiTextureCompositeAdd.fragment.js +13 -0
  6. package/multiTexture/Shaders/multiTextureCompositeAdd.fragment.js.map +1 -0
  7. package/multiTexture/Shaders/multiTextureCompositeAlphaBlend.fragment.d.ts +5 -0
  8. package/multiTexture/Shaders/multiTextureCompositeAlphaBlend.fragment.js +19 -0
  9. package/multiTexture/Shaders/multiTextureCompositeAlphaBlend.fragment.js.map +1 -0
  10. package/multiTexture/Shaders/multiTextureCompositeAlphaMax.fragment.d.ts +5 -0
  11. package/multiTexture/Shaders/multiTextureCompositeAlphaMax.fragment.js +13 -0
  12. package/multiTexture/Shaders/multiTextureCompositeAlphaMax.fragment.js.map +1 -0
  13. package/multiTexture/Shaders/multiTextureCompositeMultiply.fragment.d.ts +5 -0
  14. package/multiTexture/Shaders/multiTextureCompositeMultiply.fragment.js +13 -0
  15. package/multiTexture/Shaders/multiTextureCompositeMultiply.fragment.js.map +1 -0
  16. package/multiTexture/Shaders/multiTextureCompositeScreen.fragment.d.ts +5 -0
  17. package/multiTexture/Shaders/multiTextureCompositeScreen.fragment.js +13 -0
  18. package/multiTexture/Shaders/multiTextureCompositeScreen.fragment.js.map +1 -0
  19. package/multiTexture/Shaders/multiTextureCompositeSubtract.fragment.d.ts +5 -0
  20. package/multiTexture/Shaders/multiTextureCompositeSubtract.fragment.js +13 -0
  21. package/multiTexture/Shaders/multiTextureCompositeSubtract.fragment.js.map +1 -0
  22. package/multiTexture/ShadersWGSL/multiTextureCompositeAdd.fragment.d.ts +5 -0
  23. package/multiTexture/ShadersWGSL/multiTextureCompositeAdd.fragment.js +17 -0
  24. package/multiTexture/ShadersWGSL/multiTextureCompositeAdd.fragment.js.map +1 -0
  25. package/multiTexture/ShadersWGSL/multiTextureCompositeAlphaBlend.fragment.d.ts +5 -0
  26. package/multiTexture/ShadersWGSL/multiTextureCompositeAlphaBlend.fragment.js +23 -0
  27. package/multiTexture/ShadersWGSL/multiTextureCompositeAlphaBlend.fragment.js.map +1 -0
  28. package/multiTexture/ShadersWGSL/multiTextureCompositeAlphaMax.fragment.d.ts +5 -0
  29. package/multiTexture/ShadersWGSL/multiTextureCompositeAlphaMax.fragment.js +17 -0
  30. package/multiTexture/ShadersWGSL/multiTextureCompositeAlphaMax.fragment.js.map +1 -0
  31. package/multiTexture/ShadersWGSL/multiTextureCompositeMultiply.fragment.d.ts +5 -0
  32. package/multiTexture/ShadersWGSL/multiTextureCompositeMultiply.fragment.js +16 -0
  33. package/multiTexture/ShadersWGSL/multiTextureCompositeMultiply.fragment.js.map +1 -0
  34. package/multiTexture/ShadersWGSL/multiTextureCompositeScreen.fragment.d.ts +5 -0
  35. package/multiTexture/ShadersWGSL/multiTextureCompositeScreen.fragment.js +17 -0
  36. package/multiTexture/ShadersWGSL/multiTextureCompositeScreen.fragment.js.map +1 -0
  37. package/multiTexture/ShadersWGSL/multiTextureCompositeSubtract.fragment.d.ts +5 -0
  38. package/multiTexture/ShadersWGSL/multiTextureCompositeSubtract.fragment.js +17 -0
  39. package/multiTexture/ShadersWGSL/multiTextureCompositeSubtract.fragment.js.map +1 -0
  40. package/multiTexture/index.d.ts +1 -0
  41. package/multiTexture/index.js +2 -0
  42. package/multiTexture/index.js.map +1 -0
  43. package/multiTexture/multiTexture.d.ts +346 -0
  44. package/multiTexture/multiTexture.js +1051 -0
  45. package/multiTexture/multiTexture.js.map +1 -0
  46. package/package.json +2 -2
@@ -0,0 +1,346 @@
1
+ /**
2
+ * MultiTexture: composes an array of image files into a single TEXTURE_2D_ARRAY that can be
3
+ * assigned to a material slot like any other texture.
4
+ *
5
+ * Lives in @babylonjs/addons (not core) because it is an application-oriented, optional feature
6
+ * with WebGL2/WebGPU requirements, URL polling, and a non-trivial memory footprint.
7
+ */
8
+ import { type Nullable } from "@babylonjs/core/types.js";
9
+ import { type InternalTexture } from "@babylonjs/core/Materials/Textures/internalTexture.js";
10
+ import { type Scene } from "@babylonjs/core/scene.pure.js";
11
+ import { Observable } from "@babylonjs/core/Misc/observable.js";
12
+ import { BaseTexture } from "@babylonjs/core/Materials/Textures/baseTexture.pure.js";
13
+ import { type ISize } from "@babylonjs/core/Maths/math.size.js";
14
+ import { ProceduralTexture } from "@babylonjs/core/Materials/Textures/Procedurals/proceduralTexture.pure.js";
15
+ import { RawTexture2DArray } from "@babylonjs/core/Materials/Textures/rawTexture2DArray.js";
16
+ /**
17
+ * Options for creating a MultiTexture.
18
+ */
19
+ export interface IMultiTextureOptions {
20
+ /** Fixed layer resolution. REQUIRED. Positive integer. */
21
+ width: number;
22
+ /** Fixed layer resolution. REQUIRED. Positive integer. */
23
+ height: number;
24
+ /** 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. */
25
+ maxLayers?: number;
26
+ /** Default MultiBlendMode.ALPHA_BLEND. */
27
+ blendMode?: MultiBlendMode;
28
+ /** 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). */
29
+ generateMipMaps?: boolean;
30
+ /** 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`. */
31
+ samplingMode?: number;
32
+ /** Default false. Passed through to UploadImageToTexture2DArrayLayer. */
33
+ premultiplyAlpha?: boolean;
34
+ /** "resize" (default): scale to width×height. "strict": rejects mismatched dims. */
35
+ fit?: "resize" | "strict";
36
+ /** 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. */
37
+ rttScale?: number;
38
+ /** Default false. HEAD-polling change detection. */
39
+ watch?: boolean;
40
+ /** Default 2000 ms. Only used when watch is true. */
41
+ pollInterval?: number;
42
+ /** Fired once after all initial layers have settled (success or failure). */
43
+ onLoad?: () => void;
44
+ /** Fired on any async failure (init, updateLayer, poll). Not thrown. */
45
+ onError?: (message?: string, exception?: any) => void;
46
+ }
47
+ /**
48
+ * Register side effects for MultiTexture.
49
+ * Registers the core 2D-array image-source extensions for both backends (the WebGL2
50
+ * `engine.texture2DArrayImageSource` and its WebGPU counterpart) lazily at first use, matching
51
+ * the Atmosphere addon's convention. Safe to call multiple times; only the first call has an effect.
52
+ */
53
+ export declare function RegisterMultiTexture(): void;
54
+ /**
55
+ * Composes an array of image files into a single TEXTURE_2D_ARRAY and blends the layers per pixel
56
+ * according to a selectable {@link MultiBlendMode}. The blended result is written to a render-target
57
+ * texture that can be assigned to materials like any other texture.
58
+ *
59
+ * Requires a WebGL2 or WebGPU engine (TEXTURE_2D_ARRAY + sampler2DArray). The constructor throws
60
+ * synchronously on WebGL1.
61
+ *
62
+ * Supported source formats are the raster formats your browser can decode with createImageBitmap
63
+ * (PNG, JPEG, WebP, AVIF, GIF first frame, BMP). Compressed/container formats such as KTX2 are NOT
64
+ * supported: the existing KTX2 transcode path goes straight to the GPU (which would bypass the
65
+ * CPU pixel cache this class maintains), and KTX2 containers hold the whole array in a single file
66
+ * (which conflicts with the one-file-per-layer-index update model).
67
+ *
68
+ * Notes:
69
+ * - `url` is null (the base texture loader is not used); the `urls` property is the source of truth.
70
+ * - By default every decoded layer is read back into a CPU `Uint8ClampedArray` (see `pixels`). This
71
+ * costs one canvas readback (and a full-width×height RGBA CPU copy) per (re)load of a layer — it
72
+ * runs on every initial load, `updateLayerAsync` reload, and watch-triggered reload, so frequent
73
+ * reloads or large layers carry a CPU/memory cost (roughly `width × height × 4` bytes per layer).
74
+ * - With `premultiplyAlpha: true` the GPU layers are stored premultiplied, but the CPU `pixels`
75
+ * cache still holds the raw decoded (non-premultiplied) bytes.
76
+ * - The default ALPHA_BLEND mode composites the layers with standard source-over blending: each
77
+ * layer is drawn over the accumulated result, so later layers cover earlier ones and a fully
78
+ * opaque layer hides everything below it. With straight-alpha layers (premultiplyAlpha: false)
79
+ * the fold is the source-over `over` operator (`outA = layer.a + outA * (1 - layer.a)`); with
80
+ * the premultiplied form (`out = layer + out * (1 - layer.a)`). The composite always outputs
81
+ * straight RGBA, so materials see identical pixels regardless of `premultiplyAlpha` (which
82
+ * only controls the layer storage/fold).
83
+ * - ALPHA_MAX picks the sample with the highest alpha; ties (equal alpha) resolve to the highest
84
+ * layer index (last input draws over earlier ones).
85
+ * - With zero active layers, ALPHA_BLEND/ALPHA_MAX/ADD/SUBTRACT/SCREEN output transparent black
86
+ * and MULTIPLY outputs white (empty-product identity).
87
+ * - Compositing is performed independently of the scene render loop: MultiTexture re-composites
88
+ * its internal render target explicitly after every mutation (layer add/insert/remove/update,
89
+ * blend-mode change, array growth), so `scene.proceduralTexturesEnabled` has no effect on it.
90
+ * - How the composite samples the layer array depends on the engine backend, but both are
91
+ * filtered and honour `samplingMode`. On WebGL2 the GLSL composite shader reads the layers
92
+ * through the array sampler (`texture(...)`), so `samplingMode` affects the output, `rttScale`
93
+ * other than 1 produces a filtered bilinear rescale, and (with `generateMipMaps: true`)
94
+ * trilinear minification can use the layer mips. On WebGPU the WGSL composite shader samples
95
+ * the layer array through its sampler at mip 0 (`textureSampleLevel(..., 0.0)`), so `samplingMode`
96
+ * affects the output but only mip-0 filtering applies (no mip-level selection) and `rttScale`
97
+ * rescale is filtered at mip 0. The `_arrayTexture` sampler that materials use to read the
98
+ * per-layer array is unaffected by this backend difference.
99
+ * - `MultiTexture` lives in `@babylonjs/addons` and lazily registers the core 2D-array
100
+ * image-source extensions on first construction, matching the `Atmosphere` addon's convention.
101
+ * No engine mutation occurs at addons import time. `RegisterMultiTexture()` calls both the WebGL2
102
+ * (`engine.texture2DArrayImageSource`) and WebGPU pure registration functions, so a pure/tree-shaken
103
+ * WebGPU build receives `updateTextureArrayLayerFromImageSource` without any extra consumer import.
104
+ * - The allocated array depth (options.maxLayers ?? urls.length) must be a positive integer and no
105
+ * larger than the device limit getCaps().texture2DArrayMaxLayerCount. Empty urls are only accepted
106
+ * together with an explicit options.maxLayers. addLayerAsync/insertLayerAsync double the depth when it is
107
+ * full and throw a RangeError if the doubled depth would exceed that limit.
108
+ */
109
+ export declare class MultiTexture extends BaseTexture {
110
+ /**
111
+ * The internal ProceduralTexture that composites the layers into the render-target texture
112
+ * assigned to materials. MultiTexture composes, rather than extends, ProceduralTexture: it
113
+ * creates this composite with `skipSceneRegistration: true` so the scene render loop does not
114
+ * drive it, and calls {@link _renderComposite} explicitly after each mutation. All texture
115
+ * surface methods (isReady/getInternalTexture) forward to it.
116
+ */
117
+ get composite(): ProceduralTexture;
118
+ private _compositeInternal;
119
+ /** Fired once after all initial layers have settled (success or failure). */
120
+ readonly onLoadObservable: Observable<MultiTexture>;
121
+ private _layers;
122
+ private _layerCount;
123
+ private _maxLayers;
124
+ private _deviceMaxLayerCap;
125
+ private _blendMode;
126
+ private _pollTimer;
127
+ /** True while a _poll() tick is in flight; overlapping interval firings early-return so a slow tick never double-fetches. */
128
+ private _pollInFlight;
129
+ private _canvas;
130
+ private _ctx;
131
+ private _disposed;
132
+ private _mtOptions;
133
+ private _arrayTexture;
134
+ /** Number of in-flight mip-suppressed operations (init pool + mutations). See _suppressArrayMips. */
135
+ private _mipSuppressCount;
136
+ /**
137
+ * Number of active layers (drives the uLayerCount uniform). Changes only via addLayerAsync/removeLayerAsync.
138
+ */
139
+ get layerCount(): number;
140
+ /**
141
+ * The underlying TEXTURE_2D_ARRAY, for users who want to sample individual layers directly.
142
+ */
143
+ get arrayTexture(): RawTexture2DArray;
144
+ /**
145
+ * Forwards to the internal composite: the render-target texture that composites the layers is
146
+ * owned by the composite, so the material samples it through here.
147
+ * @returns The composite's internal texture.
148
+ */
149
+ getInternalTexture(): Nullable<InternalTexture>;
150
+ /**
151
+ * Forwards to the internal composite: ready once the composite's render-target texture is ready.
152
+ * @returns True if the composite's render-target texture is ready, otherwise false.
153
+ */
154
+ isReady(): boolean;
155
+ /**
156
+ * Renders the internal composite, applying the current layer uploads and blend mode.
157
+ * The composite only draws once its effect is compiled (shaders load asynchronously), so the
158
+ * first render is deferred to the compiled callback instead of drawing a stale/empty target.
159
+ */
160
+ private _renderComposite;
161
+ /**
162
+ * Forwards to the composite: the composite render-target is what materials sample.
163
+ * @returns The composite render-target size.
164
+ */
165
+ getSize(): ISize;
166
+ /**
167
+ * Forwards to the composite: the composite render-target base size is what materials sample.
168
+ * @returns The composite render-target base size.
169
+ */
170
+ getBaseSize(): ISize;
171
+ /**
172
+ * Forwards to the composite's sampling mode.
173
+ * @returns the composite render-target's sampling mode.
174
+ */
175
+ get samplingMode(): number;
176
+ /**
177
+ * Forwards to the composite, which owns the render-target texture the material binds.
178
+ * @param samplingMode the new sampling mode
179
+ * @param generateMipMaps whether to generate mip maps
180
+ */
181
+ updateSamplingMode(samplingMode: number, generateMipMaps?: boolean): void;
182
+ /**
183
+ * Forwards to the composite's render-target texture.
184
+ * @param faceIndex defines the face of the texture to read (in case of cube texture)
185
+ * @param level defines the LOD level of the texture to read (in case of Mip Maps)
186
+ * @param buffer defines a user defined buffer to fill with data (can be null)
187
+ * @param flushRenderer true to flush the renderer from the pending commands before reading the pixels
188
+ * @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
189
+ * @param x defines the region x coordinates to start reading from (default to 0)
190
+ * @param y defines the region y coordinates to start reading from (default to 0)
191
+ * @param width defines the region width to read from (default to the texture size at level)
192
+ * @param height defines the region width to read from (default to the texture size at level)
193
+ * @returns the composite render-target's pixel buffer promise.
194
+ */
195
+ readPixels(faceIndex?: number, level?: number, buffer?: Nullable<ArrayBufferView>, flushRenderer?: boolean, noDataConversion?: boolean, x?: number, y?: number, width?: number, height?: number): Nullable<Promise<ArrayBufferView>>;
196
+ /**
197
+ * Forwards to the composite's render-target texture.
198
+ * @param faceIndex defines the face of the texture to read (in case of cube texture)
199
+ * @param level defines the LOD level of the texture to read (in case of Mip Maps)
200
+ * @param buffer defines a user defined buffer to fill with data (can be null)
201
+ * @param flushRenderer true to flush the renderer from the pending commands before reading the pixels
202
+ * @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
203
+ * @returns the composite render-target's pixel buffer.
204
+ */
205
+ _readPixelsSync(faceIndex?: number, level?: number, buffer?: Nullable<ArrayBufferView>, flushRenderer?: boolean, noDataConversion?: boolean): Nullable<ArrayBufferView>;
206
+ /**
207
+ * Forwards to the composite render-target's format.
208
+ * @returns the composite render-target's internal format.
209
+ */
210
+ get textureFormat(): number;
211
+ /**
212
+ * Forwards to the composite render-target's type.
213
+ * @returns the composite render-target's internal type.
214
+ */
215
+ get textureType(): number;
216
+ /**
217
+ * The input URLs, in layer order. Updated by addLayerAsync/insertLayerAsync/removeLayerAsync/updateLayerAsync.
218
+ */
219
+ readonly urls: string[];
220
+ /**
221
+ * CPU pixel cache. `pixels[i]` is a full `width × height × 4` RGBA (non-premultiplied) copy of
222
+ * decoded layer i, or `null` if that layer has not loaded (yet) or failed to load. It is
223
+ * repopulated on every (re)load of a layer (initial load, `updateLayerAsync`, watch reload) and
224
+ * cleared on dispose. Memory footprint is approximately `width × height × 4` bytes per loaded
225
+ * layer; skip it if you only need the GPU composite and do not read `pixels`.
226
+ */
227
+ readonly pixels: Array<Uint8ClampedArray | null>;
228
+ /**
229
+ * Creates a new MultiTexture.
230
+ * @param name defines the name of the texture
231
+ * @param urls defines the array of image URLs to load as layers
232
+ * @param scene defines the hosting scene
233
+ * @param options defines the creation options (width/height required)
234
+ */
235
+ constructor(name: string, urls: string[], scene: Scene, options: IMultiTextureOptions);
236
+ /**
237
+ * How the layers combine. Setting it swaps the composite fragment shader and triggers one
238
+ * re-composite.
239
+ */
240
+ get blendMode(): MultiBlendMode;
241
+ set blendMode(value: MultiBlendMode);
242
+ /**
243
+ * Replaces a layer by URL. Fetches, decodes and uploads layer i only.
244
+ * Exactly one texSubImage3D is issued for the target layer; uLayerCount is unchanged.
245
+ * @param index defines the layer index to replace
246
+ * @param url defines the new source for the layer
247
+ * @returns a promise resolving once the layer has been uploaded
248
+ */
249
+ updateLayerAsync(index: number, url: string): Promise<void>;
250
+ /**
251
+ * Appends a new layer at the end and returns its index. Grows the underlying array (doubling its
252
+ * depth and re-uploading the existing layers from their retained bitmaps) when the current depth
253
+ * is exhausted. Throws a RangeError if the doubled depth would exceed the device's
254
+ * texture2DArrayMaxLayerCount.
255
+ * @param url defines the URL of the image to load as the new layer
256
+ * @returns a promise resolving to the index of the new layer
257
+ */
258
+ addLayerAsync(url: string): Promise<number>;
259
+ /**
260
+ * Inserts a new layer at the given index and returns it. Layers at index and above shift up by
261
+ * one: loaded layers are re-uploaded from their retained bitmaps, and a shifted layer that is
262
+ * still loading lands in its new slot when its in-flight load settles (loads resolve against
263
+ * their layer entry, never against a stale index). uLayerCount is incremented. Inserting at
264
+ * `layerCount` appends (addLayerAsync-equivalent). Grows the underlying array (doubling its depth)
265
+ * when the current depth is exhausted, same as addLayerAsync, and throws a RangeError if the doubled
266
+ * depth would exceed the device's texture2DArrayMaxLayerCount.
267
+ * @param index defines the layer index to insert at (0..layerCount, inclusive)
268
+ * @param url defines the URL of the image to load as the new layer
269
+ * @returns a promise resolving to the index of the inserted layer
270
+ */
271
+ insertLayerAsync(index: number, url: string): Promise<number>;
272
+ /**
273
+ * Removes a layer. Higher indices shift down (re-uploaded from their retained bitmaps) and
274
+ * uLayerCount is decremented.
275
+ * @param index defines the layer index to remove
276
+ * @returns a promise resolving once the shift is done
277
+ */
278
+ removeLayerAsync(index: number): Promise<void>;
279
+ /**
280
+ * Disposes the texture: stops the watch poller, closes every retained bitmap, disposes the layer
281
+ * array and releases the composite render target through the standard procedural-texture path.
282
+ */
283
+ dispose(): void;
284
+ /**
285
+ * Clones the texture: builds a fresh MultiTexture in the same scene with the same name, the
286
+ * current layer urls and the resolved options (layer resolution, current array capacity,
287
+ * current blend mode, sampling mode, mipmap generation, RTT scale, fit and watch settings).
288
+ * The clone re-fetches and re-decodes its layers from scratch; it never shares the 2D array
289
+ * texture, the pixel cache or the load callbacks (onLoad/onError are not inherited).
290
+ * @returns the cloned texture
291
+ */
292
+ clone(): MultiTexture;
293
+ /**
294
+ * MultiTexture is intentionally not scene-serializable: the scene loader has no parser for it,
295
+ * so the payload produced by the inherited base serialization could never be reconstructed
296
+ * (urls, capacity, blend mode and watch options have no serialized fields). Fails explicitly
297
+ * instead of returning a misleading JSON object.
298
+ * @param _allowEmptyName accepted for signature compatibility; ignored
299
+ * @throws Error always
300
+ */
301
+ serialize(_allowEmptyName?: boolean): never;
302
+ private _buildDefines;
303
+ private _bitmapOptions;
304
+ private _reportError;
305
+ private _createLayerEntry;
306
+ private _loadEntryOrThrow;
307
+ private _loadEntryAndReport;
308
+ private _warnWatchFailure;
309
+ private _uploadToLayer;
310
+ private _reuploadSlot;
311
+ private _clearLayerSlot;
312
+ private _loadEntry;
313
+ private _uploadBitmap;
314
+ private _initialize;
315
+ private _pushLayerEntry;
316
+ private _growArray;
317
+ private _suppressArrayMips;
318
+ private _generateArrayMips;
319
+ private _startPolling;
320
+ private _poll;
321
+ }
322
+ /**
323
+ * Blend modes controlling how the layers of a MultiTexture are combined per pixel.
324
+ */
325
+ export declare enum MultiBlendMode {
326
+ /**
327
+ * Default. Composites the layers with standard source-over alpha blending: each layer is drawn
328
+ * over the accumulated result, so later layers cover earlier ones and a fully opaque layer
329
+ * (a = 1) completely hides everything below it. With straight-alpha layers (premultiplyAlpha:
330
+ * false) the fold is `outA = layer.a + outA * (1 - layer.a)`; with premultiplied layers it is
331
+ * the premultiplied form `out = layer + out * (1 - layer.a)`. The composite always outputs
332
+ * straight RGBA, so materials see identical pixels regardless of `premultiplyAlpha` (which
333
+ * only controls the layer storage/fold). Zero active layers output transparent black.
334
+ */
335
+ ALPHA_BLEND = 0,
336
+ /** Keeps the sample with the highest alpha among the layers (ties: highest index wins). Zero active layers output transparent black. */
337
+ ALPHA_MAX = 1,
338
+ /** Adds all layers per channel, clamped to 1. */
339
+ ADD = 2,
340
+ /** Multiplies all layers per channel (empty product is 1). */
341
+ MULTIPLY = 3,
342
+ /** Starts from layer 0 and subtracts every following layer, clamped to 0. */
343
+ SUBTRACT = 4,
344
+ /** Screens all layers per channel. */
345
+ SCREEN = 5
346
+ }