@ignifx/core 0.12.0 → 0.14.0

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 (31) hide show
  1. package/dist/{environment-C9AjYJgV.js → environment-Cq2BmA96.js} +2 -2
  2. package/dist/{environment-C9AjYJgV.js.map → environment-Cq2BmA96.js.map} +1 -1
  3. package/dist/hdr-output-DDpIo4Q5.js +300 -0
  4. package/dist/hdr-output-DDpIo4Q5.js.map +1 -0
  5. package/dist/{ignifx-error-Dq2qJMkZ.js → ignifx-error-oYdVnT1S.js} +16 -1
  6. package/dist/ignifx-error-oYdVnT1S.js.map +1 -0
  7. package/dist/index.d.ts +343 -4
  8. package/dist/index.d.ts.map +1 -1
  9. package/dist/index.js +842 -165
  10. package/dist/index.js.map +1 -1
  11. package/dist/material-CGk5mAah.js +204 -0
  12. package/dist/material-CGk5mAah.js.map +1 -0
  13. package/dist/{material-plugin-BOCB7Stt.js → material-plugin-BUlqLsap.js} +3 -204
  14. package/dist/material-plugin-BUlqLsap.js.map +1 -0
  15. package/dist/{post-effect-compiler-Dw6zW2cG.js → post-effect-compiler-CRek8VxQ.js} +2 -2
  16. package/dist/{post-effect-compiler-Dw6zW2cG.js.map → post-effect-compiler-CRek8VxQ.js.map} +1 -1
  17. package/dist/render-path-Dx0learj.js +135 -0
  18. package/dist/render-path-Dx0learj.js.map +1 -0
  19. package/dist/render-texture-IuR0iFVa.js +174 -0
  20. package/dist/render-texture-IuR0iFVa.js.map +1 -0
  21. package/dist/{shader-material-BxQn9FT4.js → shader-material-BPb_oEZQ.js} +2 -2
  22. package/dist/{shader-material-BxQn9FT4.js.map → shader-material-BPb_oEZQ.js.map} +1 -1
  23. package/dist/{shader-material-DRZmqA_S.js → shader-material-CDQ0Y5kN.js} +3 -3
  24. package/dist/{shader-material-DRZmqA_S.js.map → shader-material-CDQ0Y5kN.js.map} +1 -1
  25. package/dist/{shader-pragma-DrFm5f5m.js → shader-pragma-BKCoZTTA.js} +2 -2
  26. package/dist/{shader-pragma-DrFm5f5m.js.map → shader-pragma-BKCoZTTA.js.map} +1 -1
  27. package/dist/{surface-shader-BgZchRBe.js → surface-shader-CwQ03yHG.js} +5 -4
  28. package/dist/{surface-shader-BgZchRBe.js.map → surface-shader-CwQ03yHG.js.map} +1 -1
  29. package/package.json +1 -1
  30. package/dist/ignifx-error-Dq2qJMkZ.js.map +0 -1
  31. package/dist/material-plugin-BOCB7Stt.js.map +0 -1
@@ -0,0 +1,135 @@
1
+ import { addTask, createCopyToTextureTask, createRenderTarget, createRenderTask } from "@babylonjs/lite";
2
+ //#region src/lite/gpu/render-path.ts
3
+ /**
4
+ * The offscreen render path (`docs/architecture/07-rendering.md` §2.7): the frame graph a scene gets
5
+ * when the project declares `rendering.features.postProcessing`.
6
+ *
7
+ * Everything here needs a device.
8
+ *
9
+ * ## Why the default render task is not good enough
10
+ *
11
+ * `createSceneContext` appends a task named `"scene"` that draws straight into the surface's
12
+ * swapchain target — `surface.scRT` for a single-sample surface, or an MSAA colour target that
13
+ * resolves into `scRT` (`lib/scene/scene-core.js` 74-79). Either way the scene's colour ends up in
14
+ * the swapchain texture, and a post-process pass cannot read it: `createSurface` configures the
15
+ * canvas context with no `usage` (`lib/engine/surface.js` 30), so the swapchain texture is
16
+ * `RENDER_ATTACHMENT` only. Binding it as a sampled texture fails WebGPU validation, the whole
17
+ * frame's command buffer is rejected, and the page presents black. That is exactly what the Phase 2
18
+ * visual suite measured, and it is why this module exists.
19
+ *
20
+ * Lite offers no way to retarget the default task after the fact — `RenderTaskConfig.rt` is read
21
+ * when the task is created, and `FrameGraph`'s public surface is only `build`/`execute`/`dispose`
22
+ * (`index.d.ts` 5367). So the scene is created with `defaultRenderTask: false` and this module
23
+ * builds the replacement.
24
+ *
25
+ * ## The graph it builds
26
+ *
27
+ * ```text
28
+ * [shadow] → scene ──→ sceneColor ──→ present ──→ swapchain
29
+ * └─ (a PostProcessStack appends its effects here, and disables present)
30
+ * ```
31
+ *
32
+ * - `scene` is a normal `createRenderTask`. With MSAA it draws into a multisampled colour target
33
+ * that owns its depth and resolves into `sceneColor` through `rst`; without MSAA it draws into
34
+ * `sceneColor` directly with a separate depth target, which is the same split Lite's own default
35
+ * uses (`RenderTaskConfig.depth`, `index.d.ts` 9782).
36
+ * - `sceneColor` is an ordinary `createRenderTarget`, so `buildRenderTarget` allocates it with
37
+ * `RENDER_ATTACHMENT | TEXTURE_BINDING | COPY_SRC | COPY_DST` (`lib/engine/render-target.js`) —
38
+ * the `TEXTURE_BINDING` the swapchain lacks.
39
+ * - `present` is a `createCopyToTextureTask` from `sceneColor` to the swapchain. Copying *into* the
40
+ * swapchain is supported and takes the blit path (`lib/frame-graph/copy-to-texture-task.js`,
41
+ * `swapAsView`); copying *out of* it is refused (Lite error 80), which is the same limit stated
42
+ * from the other side.
43
+ * - The swapchain is written every frame whatever else happens: with no chain, `present` does it;
44
+ * with a chain, the chain's last effect does it and `present` is switched off
45
+ * ({@link ScenePresenter.setPresentEnabled}).
46
+ *
47
+ * ## Resize
48
+ *
49
+ * Every target here is sized by passing the **surface** as `RenderTargetDescriptor.size`, which
50
+ * `resolveSize` re-reads from `canvas.width`/`canvas.height` on every `buildRenderTarget`
51
+ * (`lib/engine/render-target.js`). A surface resize calls the scene's `_resize`, which is
52
+ * `frameGraph.build()` (`lib/scene/scene-core.js` 67-68): every target is reallocated at the new
53
+ * size and every task re-records, which is also what refreshes the bind groups that captured the old
54
+ * texture views. Nothing here has to observe the canvas itself, and nothing is eagerly allocated —
55
+ * `createRenderTargetTexture` would be, and Lite rejects a surface as its size for exactly that
56
+ * reason.
57
+ */
58
+ /**
59
+ * The depth/stencil format Lite's own default render task uses (`lib/scene/scene-core.js` 76-77).
60
+ *
61
+ * @internal
62
+ */
63
+ const DEPTH_STENCIL_FORMAT = "depth24plus-stencil8";
64
+ /**
65
+ * Builds the scene's render task into an offscreen target and the blit that composites it, and
66
+ * appends both to the scene's frame graph.
67
+ *
68
+ * @remarks
69
+ * Call it immediately after `createSceneContext(engine, { defaultRenderTask: false })` and before
70
+ * `registerScene`: `addTask` appends, so calling it first is what puts `"scene"` ahead of everything
71
+ * a feature adds later, and `registerSceneWithShadowSupport` still unshifts its own `"shadow"` task
72
+ * in front of both.
73
+ *
74
+ * @param engine - The engine, which is also the primary surface.
75
+ * @param scene - The scene created with no default render task.
76
+ * @returns The presenter a `PostProcessStack` builds its chain against.
77
+ *
78
+ * @example
79
+ * ```ts
80
+ * const scene = createSceneContext(engine, { defaultRenderTask: false });
81
+ * const presenter = installOffscreenRenderPath(engine, scene);
82
+ * ```
83
+ *
84
+ * @internal
85
+ */
86
+ function installOffscreenRenderPath(engine, scene) {
87
+ const isMultisampled = engine.msaaSamples > 1;
88
+ const sceneColor = createRenderTarget({
89
+ lbl: "ignifx:scene-color",
90
+ format: engine.format,
91
+ samples: 1,
92
+ size: engine
93
+ });
94
+ const config = {
95
+ name: "scene",
96
+ rt: isMultisampled ? createRenderTarget({
97
+ lbl: "ignifx:scene-color-msaa",
98
+ format: engine.format,
99
+ dFormat: DEPTH_STENCIL_FORMAT,
100
+ samples: engine.msaaSamples,
101
+ size: engine
102
+ }) : sceneColor
103
+ };
104
+ if (isMultisampled) config.rst = sceneColor;
105
+ else config.depth = createRenderTarget({
106
+ lbl: "ignifx:scene-depth",
107
+ dFormat: DEPTH_STENCIL_FORMAT,
108
+ samples: 1,
109
+ size: engine
110
+ });
111
+ addTask(scene, createRenderTask(config, engine, scene));
112
+ const present = createCopyToTextureTask({
113
+ name: "ignifx:present",
114
+ sourceTexture: sceneColor,
115
+ targetTexture: engine.scRT
116
+ }, engine, scene);
117
+ addTask(scene, present);
118
+ let isPresentEnabled = true;
119
+ return {
120
+ sceneColor,
121
+ swapchain: engine.scRT,
122
+ setPresentEnabled(enabled) {
123
+ isPresentEnabled = enabled;
124
+ present.executionEnabled = enabled;
125
+ },
126
+ get isPresentEnabled() {
127
+ return isPresentEnabled;
128
+ },
129
+ hdr: null
130
+ };
131
+ }
132
+ //#endregion
133
+ export { installOffscreenRenderPath as n, DEPTH_STENCIL_FORMAT as t };
134
+
135
+ //# sourceMappingURL=render-path-Dx0learj.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"render-path-Dx0learj.js","names":[],"sources":["../src/lite/gpu/render-path.ts"],"sourcesContent":["import { addTask, createCopyToTextureTask, createRenderTarget, createRenderTask } from \"@babylonjs/lite\";\nimport type { EngineContext, RenderTarget, SceneContext, Task, Texture2D } from \"@babylonjs/lite\";\n\n/**\n * The offscreen render path (`docs/architecture/07-rendering.md` §2.7): the frame graph a scene gets\n * when the project declares `rendering.features.postProcessing`.\n *\n * Everything here needs a device.\n *\n * ## Why the default render task is not good enough\n *\n * `createSceneContext` appends a task named `\"scene\"` that draws straight into the surface's\n * swapchain target — `surface.scRT` for a single-sample surface, or an MSAA colour target that\n * resolves into `scRT` (`lib/scene/scene-core.js` 74-79). Either way the scene's colour ends up in\n * the swapchain texture, and a post-process pass cannot read it: `createSurface` configures the\n * canvas context with no `usage` (`lib/engine/surface.js` 30), so the swapchain texture is\n * `RENDER_ATTACHMENT` only. Binding it as a sampled texture fails WebGPU validation, the whole\n * frame's command buffer is rejected, and the page presents black. That is exactly what the Phase 2\n * visual suite measured, and it is why this module exists.\n *\n * Lite offers no way to retarget the default task after the fact — `RenderTaskConfig.rt` is read\n * when the task is created, and `FrameGraph`'s public surface is only `build`/`execute`/`dispose`\n * (`index.d.ts` 5367). So the scene is created with `defaultRenderTask: false` and this module\n * builds the replacement.\n *\n * ## The graph it builds\n *\n * ```text\n * [shadow] → scene ──→ sceneColor ──→ present ──→ swapchain\n * └─ (a PostProcessStack appends its effects here, and disables present)\n * ```\n *\n * - `scene` is a normal `createRenderTask`. With MSAA it draws into a multisampled colour target\n * that owns its depth and resolves into `sceneColor` through `rst`; without MSAA it draws into\n * `sceneColor` directly with a separate depth target, which is the same split Lite's own default\n * uses (`RenderTaskConfig.depth`, `index.d.ts` 9782).\n * - `sceneColor` is an ordinary `createRenderTarget`, so `buildRenderTarget` allocates it with\n * `RENDER_ATTACHMENT | TEXTURE_BINDING | COPY_SRC | COPY_DST` (`lib/engine/render-target.js`) —\n * the `TEXTURE_BINDING` the swapchain lacks.\n * - `present` is a `createCopyToTextureTask` from `sceneColor` to the swapchain. Copying *into* the\n * swapchain is supported and takes the blit path (`lib/frame-graph/copy-to-texture-task.js`,\n * `swapAsView`); copying *out of* it is refused (Lite error 80), which is the same limit stated\n * from the other side.\n * - The swapchain is written every frame whatever else happens: with no chain, `present` does it;\n * with a chain, the chain's last effect does it and `present` is switched off\n * ({@link ScenePresenter.setPresentEnabled}).\n *\n * ## Resize\n *\n * Every target here is sized by passing the **surface** as `RenderTargetDescriptor.size`, which\n * `resolveSize` re-reads from `canvas.width`/`canvas.height` on every `buildRenderTarget`\n * (`lib/engine/render-target.js`). A surface resize calls the scene's `_resize`, which is\n * `frameGraph.build()` (`lib/scene/scene-core.js` 67-68): every target is reallocated at the new\n * size and every task re-records, which is also what refreshes the bind groups that captured the old\n * texture views. Nothing here has to observe the canvas itself, and nothing is eagerly allocated —\n * `createRenderTargetTexture` would be, and Lite rejects a surface as its size for exactly that\n * reason.\n */\n\n/**\n * The depth/stencil format Lite's own default render task uses (`lib/scene/scene-core.js` 76-77).\n *\n * @internal\n */\nexport const DEPTH_STENCIL_FORMAT: GPUTextureFormat = \"depth24plus-stencil8\";\n\n/**\n * The HDR half of a presenter, when `rendering.hdr` built one (`./hdr-output.ts`).\n *\n * @internal\n */\nexport interface HdrOutputHandle {\n /** The scene's linear `rgba16float` colour, as a sampled texture. Values may exceed 1. */\n readonly sceneTexture: Texture2D;\n /**\n * The per-frame work: uploads the scene's exposure, contrast and curve when they changed, and\n * gives every new PBR material the linear-output plugin.\n *\n * @param isSceneRegistered - Whether Lite has built the scene, so a patched material needs a\n * rebuild.\n */\n update(isSceneRegistered: boolean): void;\n}\n\n/**\n * A scene's offscreen render path: the colour a `PostProcessStack` reads, and the compositing blit\n * it takes over from.\n *\n * @internal\n */\nexport interface ScenePresenter {\n /**\n * The single-sample colour target the scene ends up in — resolved when MSAA is on. It carries\n * `TEXTURE_BINDING`, so it is a legal `sourceTexture` for a post-process task.\n */\n readonly sceneColor: RenderTarget;\n /** The surface's swapchain target, where the last pass of the frame has to land. */\n readonly swapchain: RenderTarget;\n /**\n * Switches the compositing blit on or off.\n *\n * @param enabled - `false` while an effect chain writes the swapchain itself.\n */\n setPresentEnabled(enabled: boolean): void;\n /** Whether the compositing blit currently runs. */\n readonly isPresentEnabled: boolean;\n /** The HDR output pass, when `rendering.hdr` is on; `null` for the plain offscreen path. */\n readonly hdr: HdrOutputHandle | null;\n}\n\n/**\n * Builds the scene's render task into an offscreen target and the blit that composites it, and\n * appends both to the scene's frame graph.\n *\n * @remarks\n * Call it immediately after `createSceneContext(engine, { defaultRenderTask: false })` and before\n * `registerScene`: `addTask` appends, so calling it first is what puts `\"scene\"` ahead of everything\n * a feature adds later, and `registerSceneWithShadowSupport` still unshifts its own `\"shadow\"` task\n * in front of both.\n *\n * @param engine - The engine, which is also the primary surface.\n * @param scene - The scene created with no default render task.\n * @returns The presenter a `PostProcessStack` builds its chain against.\n *\n * @example\n * ```ts\n * const scene = createSceneContext(engine, { defaultRenderTask: false });\n * const presenter = installOffscreenRenderPath(engine, scene);\n * ```\n *\n * @internal\n */\nexport function installOffscreenRenderPath(engine: EngineContext, scene: SceneContext): ScenePresenter {\n const isMultisampled = engine.msaaSamples > 1;\n const sceneColor = createRenderTarget({\n lbl: \"ignifx:scene-color\",\n format: engine.format,\n samples: 1,\n size: engine,\n });\n const colorTarget = isMultisampled\n ? createRenderTarget({\n lbl: \"ignifx:scene-color-msaa\",\n format: engine.format,\n dFormat: DEPTH_STENCIL_FORMAT,\n samples: engine.msaaSamples,\n size: engine,\n })\n : sceneColor;\n const config: {\n name: string;\n rt: RenderTarget;\n rst?: RenderTarget;\n depth?: RenderTarget;\n } = { name: \"scene\", rt: colorTarget };\n if (isMultisampled) {\n config.rst = sceneColor;\n } else {\n // A colour target that carries no `dFormat` allocates no depth of its own, so the pass needs a\n // separate one — the arrangement Lite's own single-sample default task uses.\n config.depth = createRenderTarget({\n lbl: \"ignifx:scene-depth\",\n dFormat: DEPTH_STENCIL_FORMAT,\n samples: 1,\n size: engine,\n });\n }\n addTask(scene, createRenderTask(config, engine, scene));\n\n const present: Task = createCopyToTextureTask(\n { name: \"ignifx:present\", sourceTexture: sceneColor, targetTexture: engine.scRT },\n engine,\n scene,\n );\n addTask(scene, present);\n\n let isPresentEnabled = true;\n return {\n sceneColor,\n swapchain: engine.scRT,\n setPresentEnabled(enabled: boolean): void {\n isPresentEnabled = enabled;\n present.executionEnabled = enabled;\n },\n get isPresentEnabled(): boolean {\n return isPresentEnabled;\n },\n hdr: null,\n };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgEA,MAAa,uBAAyC;;;;;;;;;;;;;;;;;;;;;;;AAoEtD,SAAgB,2BAA2B,QAAuB,OAAqC;CACrG,MAAM,iBAAiB,OAAO,cAAc;CAC5C,MAAM,aAAa,mBAAmB;EACpC,KAAK;EACL,QAAQ,OAAO;EACf,SAAS;EACT,MAAM;CACR,CAAC;CAUD,MAAM,SAKF;EAAE,MAAM;EAAS,IAdD,iBAChB,mBAAmB;GACjB,KAAK;GACL,QAAQ,OAAO;GACf,SAAS;GACT,SAAS,OAAO;GAChB,MAAM;EACR,CAAC,IACD;CAMiC;CACrC,IAAI,gBACF,OAAO,MAAM;MAIb,OAAO,QAAQ,mBAAmB;EAChC,KAAK;EACL,SAAS;EACT,SAAS;EACT,MAAM;CACR,CAAC;CAEH,QAAQ,OAAO,iBAAiB,QAAQ,QAAQ,KAAK,CAAC;CAEtD,MAAM,UAAgB,wBACpB;EAAE,MAAM;EAAkB,eAAe;EAAY,eAAe,OAAO;CAAK,GAChF,QACA,KACF;CACA,QAAQ,OAAO,OAAO;CAEtB,IAAI,mBAAmB;CACvB,OAAO;EACL;EACA,WAAW,OAAO;EAClB,kBAAkB,SAAwB;GACxC,mBAAmB;GACnB,QAAQ,mBAAmB;EAC7B;EACA,IAAI,mBAA4B;GAC9B,OAAO;EACT;EACA,KAAK;CACP;AACF"}
@@ -0,0 +1,174 @@
1
+ import { addTask, buildFrameGraphTask, createRenderTarget, createRenderTask, getFrameGraph } from "@babylonjs/lite";
2
+ //#region src/lite/gpu/render-texture.ts
3
+ /**
4
+ * Render-to-texture (`docs/architecture/07-rendering.md` §2.11): a second pass of the render scene,
5
+ * through another camera, into an offscreen colour target that can be read back.
6
+ *
7
+ * Everything here needs a device, and every Lite claim was read from `@babylonjs/lite@1.34.0`.
8
+ *
9
+ * ## The pass
10
+ *
11
+ * One `createRenderTask` per texture, appended to the render scene's frame graph. Its target is an
12
+ * ordinary `createRenderTarget` of a fixed `{ width, height }`, in the surface's colour format with
13
+ * a depth/stencil attachment of its own, single-sample. The task owns it: `record()` allocates it
14
+ * (`buildRenderTarget`, `RENDER_ATTACHMENT | TEXTURE_BINDING | COPY_SRC | COPY_DST`,
15
+ * `lib/engine/render-target.js` 59) and `dispose()` frees it. The task auto-mirrors the scene's
16
+ * renderables, builds its own pipelines for its target signature, and writes a scene UBO of its own
17
+ * (`_sceneUBO`, `lib/frame-graph/render-task-base.js` 85), so its camera never disturbs the main
18
+ * pass.
19
+ *
20
+ * ## The camera
21
+ *
22
+ * `RenderTaskConfig.cam` is read on every execute (`task._config.cam ?? scene.camera`,
23
+ * `render-task-base.js` 236, 279) from the config object the task keeps by reference (line 77), so
24
+ * re-pointing the pass is one assignment. A `null` camera would fall back to the scene's main
25
+ * camera, so the pass is switched off with `Task.executionEnabled` instead.
26
+ *
27
+ * ## Gaps in Lite's public surface
28
+ *
29
+ * - **No task removal.** `FrameGraph` exposes only `build`/`execute`/`dispose`, and a disposed
30
+ * render task throws from `record()` on the next `frameGraph.build()` (a canvas resize). So the
31
+ * task is spliced out of `_tasks`, the array `addTask` appends to (`lib/frame-graph/frame-graph.js`),
32
+ * before it is disposed.
33
+ * - **No texture readback.** Lite reads back only the swapchain (`captureScreenshot`). The read here
34
+ * copies the target's `_colorTexture` into a mapped buffer through `engine._device`. Queue order
35
+ * makes it read the last frame submitted before the call.
36
+ */
37
+ /** The depth/stencil format Lite's own render tasks use. */
38
+ const DEPTH_STENCIL_FORMAT = "depth24plus-stencil8";
39
+ /** WebGPU's `bytesPerRow` alignment for a texture-to-buffer copy. */
40
+ const ROW_ALIGNMENT = 256;
41
+ /** RGBA8 bytes per pixel. */
42
+ const BYTES_PER_PIXEL = 4;
43
+ /**
44
+ * Creates a texture's render pass, switched off, at the end of the render scene's frame graph.
45
+ *
46
+ * @remarks
47
+ * Call it only once the scene is registered: the task is recorded at once, which allocates its
48
+ * target.
49
+ *
50
+ * @param engine - The WebGPU engine.
51
+ * @param scene - The registered render scene.
52
+ * @param width - The width in pixels.
53
+ * @param height - The height in pixels.
54
+ * @returns The pass.
55
+ *
56
+ * @internal
57
+ */
58
+ function createLiteRenderTexture(engine, scene, width, height) {
59
+ const target = createRenderTarget({
60
+ lbl: "ignifx:render-texture",
61
+ format: engine.format,
62
+ dFormat: DEPTH_STENCIL_FORMAT,
63
+ samples: 1,
64
+ size: {
65
+ width,
66
+ height
67
+ }
68
+ });
69
+ const config = {
70
+ name: "ignifx:render-texture",
71
+ rt: target,
72
+ cam: null
73
+ };
74
+ const task = createRenderTask(config, engine, scene);
75
+ task.executionEnabled = false;
76
+ addTask(scene, task);
77
+ buildFrameGraphTask(getFrameGraph(scene), task);
78
+ let isDisposed = false;
79
+ return {
80
+ setCamera(camera) {
81
+ if (isDisposed) return;
82
+ config.cam = camera;
83
+ task.executionEnabled = camera !== null;
84
+ },
85
+ async read() {
86
+ const texture = isDisposed ? null : colorTextureOf(target);
87
+ const device = deviceOf(engine);
88
+ if (texture === null || device === null) throw new Error("The render texture has no GPU texture to read.");
89
+ return readTexture(device, texture, width, height);
90
+ },
91
+ dispose() {
92
+ if (isDisposed) return;
93
+ isDisposed = true;
94
+ task.executionEnabled = false;
95
+ removeTask(scene, task);
96
+ task.dispose();
97
+ }
98
+ };
99
+ }
100
+ /**
101
+ * A render target's live colour texture.
102
+ *
103
+ * @param target - The target.
104
+ * @returns The texture, or `null` before the owning task has recorded.
105
+ */
106
+ function colorTextureOf(target) {
107
+ return target._colorTexture ?? null;
108
+ }
109
+ /**
110
+ * An engine's current device.
111
+ *
112
+ * @param engine - The engine.
113
+ * @returns The device, or `null` for an engine without one.
114
+ */
115
+ function deviceOf(engine) {
116
+ return engine._device ?? null;
117
+ }
118
+ /**
119
+ * Takes a task out of a scene's frame graph, so the next rebuild does not record it.
120
+ *
121
+ * @param scene - The scene.
122
+ * @param task - The task.
123
+ */
124
+ function removeTask(scene, task) {
125
+ const tasks = getFrameGraph(scene)._tasks;
126
+ if (!Array.isArray(tasks)) throw new TypeError("Lite's FrameGraph has no _tasks array; render-texture.ts needs updating for this Lite.");
127
+ const index = tasks.indexOf(task);
128
+ if (index >= 0) tasks.splice(index, 1);
129
+ }
130
+ /**
131
+ * Copies a colour texture into tightly packed RGBA8.
132
+ *
133
+ * @param device - The device that owns the texture.
134
+ * @param texture - An 8-bit RGBA or BGRA texture with `COPY_SRC`.
135
+ * @param width - The width to read.
136
+ * @param height - The height to read.
137
+ * @returns The pixels, top row first, red first.
138
+ */
139
+ async function readTexture(device, texture, width, height) {
140
+ const rowBytes = width * BYTES_PER_PIXEL;
141
+ const bytesPerRow = Math.ceil(rowBytes / ROW_ALIGNMENT) * ROW_ALIGNMENT;
142
+ const buffer = device.createBuffer({
143
+ label: "ignifx:render-texture-read",
144
+ size: bytesPerRow * height,
145
+ usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
146
+ });
147
+ try {
148
+ const encoder = device.createCommandEncoder({ label: "ignifx:render-texture-read" });
149
+ encoder.copyTextureToBuffer({ texture }, {
150
+ buffer,
151
+ bytesPerRow
152
+ }, {
153
+ width,
154
+ height
155
+ });
156
+ device.queue.submit([encoder.finish()]);
157
+ await buffer.mapAsync(GPUMapMode.READ);
158
+ const mapped = new Uint8Array(buffer.getMappedRange());
159
+ const out = new Uint8ClampedArray(rowBytes * height);
160
+ for (let row = 0; row < height; row += 1) out.set(mapped.subarray(row * bytesPerRow, row * bytesPerRow + rowBytes), row * rowBytes);
161
+ if (texture.format.startsWith("bgra")) for (let index = 0; index < out.length; index += BYTES_PER_PIXEL) {
162
+ const blue = out[index] ?? 0;
163
+ out[index] = out[index + 2] ?? 0;
164
+ out[index + 2] = blue;
165
+ }
166
+ return out;
167
+ } finally {
168
+ buffer.destroy();
169
+ }
170
+ }
171
+ //#endregion
172
+ export { createLiteRenderTexture };
173
+
174
+ //# sourceMappingURL=render-texture-IuR0iFVa.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"render-texture-IuR0iFVa.js","names":["internals"],"sources":["../src/lite/gpu/render-texture.ts"],"sourcesContent":["import { addTask, buildFrameGraphTask, createRenderTarget, createRenderTask, getFrameGraph } from \"@babylonjs/lite\";\nimport type { Camera, EngineContext, RenderTarget, RenderTaskConfig, SceneContext, Task } from \"@babylonjs/lite\";\n\n/**\n * Render-to-texture (`docs/architecture/07-rendering.md` §2.11): a second pass of the render scene,\n * through another camera, into an offscreen colour target that can be read back.\n *\n * Everything here needs a device, and every Lite claim was read from `@babylonjs/lite@1.34.0`.\n *\n * ## The pass\n *\n * One `createRenderTask` per texture, appended to the render scene's frame graph. Its target is an\n * ordinary `createRenderTarget` of a fixed `{ width, height }`, in the surface's colour format with\n * a depth/stencil attachment of its own, single-sample. The task owns it: `record()` allocates it\n * (`buildRenderTarget`, `RENDER_ATTACHMENT | TEXTURE_BINDING | COPY_SRC | COPY_DST`,\n * `lib/engine/render-target.js` 59) and `dispose()` frees it. The task auto-mirrors the scene's\n * renderables, builds its own pipelines for its target signature, and writes a scene UBO of its own\n * (`_sceneUBO`, `lib/frame-graph/render-task-base.js` 85), so its camera never disturbs the main\n * pass.\n *\n * ## The camera\n *\n * `RenderTaskConfig.cam` is read on every execute (`task._config.cam ?? scene.camera`,\n * `render-task-base.js` 236, 279) from the config object the task keeps by reference (line 77), so\n * re-pointing the pass is one assignment. A `null` camera would fall back to the scene's main\n * camera, so the pass is switched off with `Task.executionEnabled` instead.\n *\n * ## Gaps in Lite's public surface\n *\n * - **No task removal.** `FrameGraph` exposes only `build`/`execute`/`dispose`, and a disposed\n * render task throws from `record()` on the next `frameGraph.build()` (a canvas resize). So the\n * task is spliced out of `_tasks`, the array `addTask` appends to (`lib/frame-graph/frame-graph.js`),\n * before it is disposed.\n * - **No texture readback.** Lite reads back only the swapchain (`captureScreenshot`). The read here\n * copies the target's `_colorTexture` into a mapped buffer through `engine._device`. Queue order\n * makes it read the last frame submitted before the call.\n */\n\n/** The depth/stencil format Lite's own render tasks use. */\nconst DEPTH_STENCIL_FORMAT: GPUTextureFormat = \"depth24plus-stencil8\";\n\n/** WebGPU's `bytesPerRow` alignment for a texture-to-buffer copy. */\nconst ROW_ALIGNMENT = 256;\n\n/** RGBA8 bytes per pixel. */\nconst BYTES_PER_PIXEL = 4;\n\n/** The fields of a Lite 1.34 render target that hold its live GPU texture. */\ninterface TargetInternals {\n /** The colour texture, `null` until the owning task has recorded. */\n _colorTexture?: GPUTexture | null;\n}\n\n/** The field of a Lite 1.34 engine that holds its device. */\ninterface EngineInternals {\n /** The device; replaced after a device-loss recovery, so read on every use. */\n _device?: GPUDevice;\n}\n\n/** The field of a Lite 1.34 frame graph that holds its tasks. */\ninterface FrameGraphInternals {\n /** The tasks, in execute order. */\n _tasks?: Task[];\n}\n\n/**\n * One texture's render pass.\n *\n * @internal\n */\nexport interface LiteRenderTexture {\n /**\n * Points the pass at a camera, or switches it off.\n *\n * @param camera - The camera to render through from the next frame, or `null` to stop.\n */\n setCamera(camera: Camera | null): void;\n /**\n * Reads the texture as it is after the last submitted frame.\n *\n * @returns `width * height * 4` bytes of RGBA8, top row first.\n * @throws Error when the pass has not recorded yet or the engine has no device.\n */\n read(): Promise<Uint8ClampedArray>;\n /** Removes the pass from the frame graph and frees its target. Idempotent. */\n dispose(): void;\n}\n\n/**\n * Creates a texture's render pass, switched off, at the end of the render scene's frame graph.\n *\n * @remarks\n * Call it only once the scene is registered: the task is recorded at once, which allocates its\n * target.\n *\n * @param engine - The WebGPU engine.\n * @param scene - The registered render scene.\n * @param width - The width in pixels.\n * @param height - The height in pixels.\n * @returns The pass.\n *\n * @internal\n */\nexport function createLiteRenderTexture(\n engine: EngineContext,\n scene: SceneContext,\n width: number,\n height: number,\n): LiteRenderTexture {\n const target: RenderTarget = createRenderTarget({\n lbl: \"ignifx:render-texture\",\n format: engine.format,\n dFormat: DEPTH_STENCIL_FORMAT,\n samples: 1,\n size: { width, height },\n });\n const config: RenderTaskConfig = { name: \"ignifx:render-texture\", rt: target, cam: null };\n const task = createRenderTask(config, engine, scene);\n task.executionEnabled = false;\n addTask(scene, task);\n buildFrameGraphTask(getFrameGraph(scene), task);\n let isDisposed = false;\n return {\n setCamera(camera: Camera | null): void {\n if (isDisposed) {\n return;\n }\n config.cam = camera;\n task.executionEnabled = camera !== null;\n },\n async read(): Promise<Uint8ClampedArray> {\n const texture = isDisposed ? null : colorTextureOf(target);\n const device = deviceOf(engine);\n if (texture === null || device === null) {\n throw new Error(\"The render texture has no GPU texture to read.\");\n }\n return readTexture(device, texture, width, height);\n },\n dispose(): void {\n if (isDisposed) {\n return;\n }\n isDisposed = true;\n task.executionEnabled = false;\n removeTask(scene, task);\n task.dispose();\n },\n };\n}\n\n/**\n * A render target's live colour texture.\n *\n * @param target - The target.\n * @returns The texture, or `null` before the owning task has recorded.\n */\nfunction colorTextureOf(target: RenderTarget): GPUTexture | null {\n // Boundary assertion (coding standards §5.2): the field Lite 1.34 keeps, documented above.\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n const internals = target as RenderTarget & TargetInternals;\n // oxlint-disable-next-line no-underscore-dangle\n return internals._colorTexture ?? null;\n}\n\n/**\n * An engine's current device.\n *\n * @param engine - The engine.\n * @returns The device, or `null` for an engine without one.\n */\nfunction deviceOf(engine: EngineContext): GPUDevice | null {\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n const internals = engine as EngineContext & EngineInternals;\n // oxlint-disable-next-line no-underscore-dangle\n return internals._device ?? null;\n}\n\n/**\n * Takes a task out of a scene's frame graph, so the next rebuild does not record it.\n *\n * @param scene - The scene.\n * @param task - The task.\n */\nfunction removeTask(scene: SceneContext, task: Task): void {\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n const graph = getFrameGraph(scene) as ReturnType<typeof getFrameGraph> & FrameGraphInternals;\n // oxlint-disable-next-line no-underscore-dangle\n const tasks = graph._tasks;\n if (!Array.isArray(tasks)) {\n // A Lite upgrade renamed the field: fail here, not on the next rebuild (07-rendering §2.11).\n throw new TypeError(\"Lite's FrameGraph has no _tasks array; render-texture.ts needs updating for this Lite.\");\n }\n const index = tasks.indexOf(task);\n if (index >= 0) {\n tasks.splice(index, 1);\n }\n}\n\n/**\n * Copies a colour texture into tightly packed RGBA8.\n *\n * @param device - The device that owns the texture.\n * @param texture - An 8-bit RGBA or BGRA texture with `COPY_SRC`.\n * @param width - The width to read.\n * @param height - The height to read.\n * @returns The pixels, top row first, red first.\n */\nasync function readTexture(\n device: GPUDevice,\n texture: GPUTexture,\n width: number,\n height: number,\n): Promise<Uint8ClampedArray> {\n const rowBytes = width * BYTES_PER_PIXEL;\n const bytesPerRow = Math.ceil(rowBytes / ROW_ALIGNMENT) * ROW_ALIGNMENT;\n const buffer = device.createBuffer({\n label: \"ignifx:render-texture-read\",\n size: bytesPerRow * height,\n usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,\n });\n try {\n const encoder = device.createCommandEncoder({ label: \"ignifx:render-texture-read\" });\n encoder.copyTextureToBuffer({ texture }, { buffer, bytesPerRow }, { width, height });\n device.queue.submit([encoder.finish()]);\n await buffer.mapAsync(GPUMapMode.READ);\n const mapped = new Uint8Array(buffer.getMappedRange());\n const out = new Uint8ClampedArray(rowBytes * height);\n for (let row = 0; row < height; row += 1) {\n out.set(mapped.subarray(row * bytesPerRow, row * bytesPerRow + rowBytes), row * rowBytes);\n }\n if (texture.format.startsWith(\"bgra\")) {\n for (let index = 0; index < out.length; index += BYTES_PER_PIXEL) {\n const blue = out[index] ?? 0;\n out[index] = out[index + 2] ?? 0;\n out[index + 2] = blue;\n }\n }\n return out;\n } finally {\n buffer.destroy();\n }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,MAAM,uBAAyC;;AAG/C,MAAM,gBAAgB;;AAGtB,MAAM,kBAAkB;;;;;;;;;;;;;;;;AA0DxB,SAAgB,wBACd,QACA,OACA,OACA,QACmB;CACnB,MAAM,SAAuB,mBAAmB;EAC9C,KAAK;EACL,QAAQ,OAAO;EACf,SAAS;EACT,SAAS;EACT,MAAM;GAAE;GAAO;EAAO;CACxB,CAAC;CACD,MAAM,SAA2B;EAAE,MAAM;EAAyB,IAAI;EAAQ,KAAK;CAAK;CACxF,MAAM,OAAO,iBAAiB,QAAQ,QAAQ,KAAK;CACnD,KAAK,mBAAmB;CACxB,QAAQ,OAAO,IAAI;CACnB,oBAAoB,cAAc,KAAK,GAAG,IAAI;CAC9C,IAAI,aAAa;CACjB,OAAO;EACL,UAAU,QAA6B;GACrC,IAAI,YACF;GAEF,OAAO,MAAM;GACb,KAAK,mBAAmB,WAAW;EACrC;EACA,MAAM,OAAmC;GACvC,MAAM,UAAU,aAAa,OAAO,eAAe,MAAM;GACzD,MAAM,SAAS,SAAS,MAAM;GAC9B,IAAI,YAAY,QAAQ,WAAW,MACjC,MAAM,IAAI,MAAM,gDAAgD;GAElE,OAAO,YAAY,QAAQ,SAAS,OAAO,MAAM;EACnD;EACA,UAAgB;GACd,IAAI,YACF;GAEF,aAAa;GACb,KAAK,mBAAmB;GACxB,WAAW,OAAO,IAAI;GACtB,KAAK,QAAQ;EACf;CACF;AACF;;;;;;;AAQA,SAAS,eAAe,QAAyC;CAK/D,OAAOA,OAAU,iBAAiB;AACpC;;;;;;;AAQA,SAAS,SAAS,QAAyC;CAIzD,OAAOA,OAAU,WAAW;AAC9B;;;;;;;AAQA,SAAS,WAAW,OAAqB,MAAkB;CAIzD,MAAM,QAFQ,cAAc,KAEV,CAAC,CAAC;CACpB,IAAI,CAAC,MAAM,QAAQ,KAAK,GAEtB,MAAM,IAAI,UAAU,wFAAwF;CAE9G,MAAM,QAAQ,MAAM,QAAQ,IAAI;CAChC,IAAI,SAAS,GACX,MAAM,OAAO,OAAO,CAAC;AAEzB;;;;;;;;;;AAWA,eAAe,YACb,QACA,SACA,OACA,QAC4B;CAC5B,MAAM,WAAW,QAAQ;CACzB,MAAM,cAAc,KAAK,KAAK,WAAW,aAAa,IAAI;CAC1D,MAAM,SAAS,OAAO,aAAa;EACjC,OAAO;EACP,MAAM,cAAc;EACpB,OAAO,eAAe,WAAW,eAAe;CAClD,CAAC;CACD,IAAI;EACF,MAAM,UAAU,OAAO,qBAAqB,EAAE,OAAO,6BAA6B,CAAC;EACnF,QAAQ,oBAAoB,EAAE,QAAQ,GAAG;GAAE;GAAQ;EAAY,GAAG;GAAE;GAAO;EAAO,CAAC;EACnF,OAAO,MAAM,OAAO,CAAC,QAAQ,OAAO,CAAC,CAAC;EACtC,MAAM,OAAO,SAAS,WAAW,IAAI;EACrC,MAAM,SAAS,IAAI,WAAW,OAAO,eAAe,CAAC;EACrD,MAAM,MAAM,IAAI,kBAAkB,WAAW,MAAM;EACnD,KAAK,IAAI,MAAM,GAAG,MAAM,QAAQ,OAAO,GACrC,IAAI,IAAI,OAAO,SAAS,MAAM,aAAa,MAAM,cAAc,QAAQ,GAAG,MAAM,QAAQ;EAE1F,IAAI,QAAQ,OAAO,WAAW,MAAM,GAClC,KAAK,IAAI,QAAQ,GAAG,QAAQ,IAAI,QAAQ,SAAS,iBAAiB;GAChE,MAAM,OAAO,IAAI,UAAU;GAC3B,IAAI,SAAS,IAAI,QAAQ,MAAM;GAC/B,IAAI,QAAQ,KAAK;EACnB;EAEF,OAAO;CACT,UAAU;EACR,OAAO,QAAQ;CACjB;AACF"}
@@ -1,4 +1,4 @@
1
- import { i as readSceneEnvironment } from "./environment-C9AjYJgV.js";
1
+ import { i as readSceneEnvironment } from "./environment-Cq2BmA96.js";
2
2
  import { createShaderMaterial, createTexture2DArrayFromPixels, createTexture2DFromPixels, enableShaderMaterialUniformCaching, setShaderMatrix, setShaderStorageBuffer, setShaderTexture, setShaderUniform } from "@babylonjs/lite";
3
3
  //#region src/lite/gpu/shader-material.ts
4
4
  /** The RGBA bytes of each 1x1 fallback texture. */
@@ -204,4 +204,4 @@ function readSceneAmbient(scene, out) {
204
204
  //#endregion
205
205
  export { createFallbackTexture, createShaderMaterialFromOptions, enableShaderUniformCaching, readSceneAmbient, resolveFallbackTexture, writeShaderMatrix, writeShaderStorageBuffer, writeShaderTexture, writeShaderUniform };
206
206
 
207
- //# sourceMappingURL=shader-material-BxQn9FT4.js.map
207
+ //# sourceMappingURL=shader-material-BPb_oEZQ.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"shader-material-BxQn9FT4.js","names":[],"sources":["../src/lite/gpu/shader-material.ts"],"sourcesContent":["import {\n createShaderMaterial,\n createTexture2DArrayFromPixels,\n createTexture2DFromPixels,\n enableShaderMaterialUniformCaching,\n setShaderMatrix,\n setShaderStorageBuffer,\n setShaderTexture,\n setShaderUniform,\n} from \"@babylonjs/lite\";\nimport { readSceneEnvironment } from \"./environment.js\";\nimport type {\n EngineContext,\n SceneContext,\n ShaderAttributeName,\n ShaderMaterial,\n ShaderSystemUniformName,\n ShaderUniformType,\n StorageBuffer,\n Texture2D,\n} from \"@babylonjs/lite\";\n\n/**\n * The custom-WGSL half of the Babylon Lite adapter: `createShaderMaterial`, the `setShader*`\n * setters, and the 1x1 fallback textures a declared sampler falls back to\n * (`docs/plan/2026-09-terrain-particles-shaders.md` §3.1, ADR-0024). Everything here is `@internal`.\n *\n * Lite exports one barrel, so a static import of `createShaderMaterial` anywhere in the reachable\n * graph pulls `lib/material/shader/**` into every entry chunk. This module is therefore reached with\n * `await import(...)` from `../../render/shader-support.ts`, and only loading a `.wgsl` triggers the\n * fetch. `./storage-buffer.ts` is a separate file for the same reason: `StorageBufferAsset`\n * allocates synchronously, so it cannot wait for this chunk.\n *\n * Two Lite facts it is written around:\n *\n * - Nothing may be left unbound: `createShaderBindGroup` throws (errors 309 and 310) when a declared\n * sampler has no texture or a declared storage buffer has no buffer, which is what\n * {@link createFallbackTexture} exists for.\n * - There is no front-face culling; `ShaderMaterialOptions` carries only `backFaceCulling`\n * (`lib/material/shader/shader-pipeline.js`), so the pragma parser refuses `cull front`.\n */\n\n/**\n * A Babylon Lite custom WGSL material, re-exported under an ignifx name\n * (`CONSTITUTION.md` §3.4, coding standards §4).\n *\n * @remarks\n * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.\n *\n * @public\n */\nexport type LiteShaderMaterial = ShaderMaterial;\n\n/** The RGBA bytes of each 1x1 fallback texture. */\nconst FALLBACK_PIXELS: Readonly<Record<string, readonly [number, number, number, number]>> = Object.freeze({\n white: [255, 255, 255, 255],\n black: [0, 0, 0, 255],\n transparent: [0, 0, 0, 0],\n});\n\n/**\n * One declared uniform in the form Babylon Lite's factory takes: either the name of a system\n * uniform it fills in itself, or a custom declaration with its initial value.\n *\n * @internal\n */\nexport type ShaderUniformEntry =\n | ShaderSystemUniformName\n | {\n /** The WGSL identifier. */\n readonly name: string;\n /** The WGSL type. */\n readonly type: ShaderUniformType;\n /** The initial value, **linear** for a colour. */\n readonly defaultValue: number | readonly number[];\n };\n\n/**\n * One declared sampler in the form Babylon Lite's factory takes.\n *\n * @internal\n */\nexport interface ShaderSamplerEntry {\n /** The WGSL identifier; Lite generates `<name>Sampler` beside it. */\n readonly name: string;\n /** `\"2d-array\"` for a `texture_2d_array<f32>` binding. */\n readonly viewDimension: \"2d\" | \"2d-array\";\n}\n\n/**\n * One declared storage buffer in the form Babylon Lite's factory takes.\n *\n * @internal\n */\nexport interface ShaderStorageEntry {\n /** The WGSL identifier. */\n readonly name: string;\n /** The WGSL variable type, verbatim. */\n readonly type: string;\n}\n\n/**\n * Everything Babylon Lite's `createShaderMaterial` needs, in ignifx's own vocabulary so that the\n * mapping from a `ShaderDeclaration` can be built and asserted without a device or a Lite import\n * (`src/render/shader-material.ts`).\n *\n * @remarks\n * A `null` blend state or depth comparison means \"leave Babylon Lite's own default in place\", so\n * this module never restates a Lite default that could change.\n *\n * @internal\n */\nexport interface ShaderMaterialBuildOptions {\n /** The material's name, used in pipeline and shader-module labels. */\n readonly name: string;\n /** The WGSL source, handed to Lite as both the vertex and the fragment source. */\n readonly source: string;\n /** The vertex attributes the vertex stage reads; `position` is mandatory. */\n readonly attributes: readonly ShaderAttributeName[];\n /** The system and custom uniforms, in binding-declaration order. */\n readonly uniforms: readonly ShaderUniformEntry[];\n /** The samplers. */\n readonly samplers: readonly ShaderSamplerEntry[];\n /** The read-only storage buffers. */\n readonly storageBuffers: readonly ShaderStorageEntry[];\n /** The WGSL `const` declarations, resolved from the file's defaults and the material's overrides. */\n readonly defines: Readonly<Record<string, boolean | number>>;\n /** Whether the thin-instance RGBA stream is bound and injected into `VertexInput`. */\n readonly useThinInstanceColors: boolean;\n /** Whether the surface is alpha-blended. */\n readonly needAlphaBlending: boolean;\n /** Which of Lite's two blend equations to use when no explicit state is given. */\n readonly blendMode: \"alpha\" | \"additive\";\n /** An explicit colour-target blend state, which replaces the derived one; `null` to derive it. */\n readonly blend: GPUBlendState | null;\n /** Whether the surface samples the opaque scene colour behind it. */\n readonly transmissive: boolean;\n /** Whether back faces are culled. */\n readonly backFaceCulling: boolean;\n /** Whether the draw writes depth. */\n readonly depthWrite: boolean;\n /** The depth comparison, or `null` for Lite's own reverse-Z default. */\n readonly depthCompare: GPUCompareFunction | null;\n}\n\n/**\n * Builds a Babylon Lite custom WGSL material.\n *\n * @remarks\n * Validation is eager and compilation is lazy, so this runs under the null engine; the pipeline is\n * compiled the first time a mesh wearing the material is drawn.\n *\n * @param options - The sources and the declared attribute, uniform, sampler, and storage layout.\n * @returns The material.\n * @throws Error from Babylon Lite when the declaration is not one it can build.\n *\n * @internal\n */\nexport function createShaderMaterialFromOptions(options: ShaderMaterialBuildOptions): ShaderMaterial {\n return createShaderMaterial({\n name: options.name,\n vertexSource: options.source,\n fragmentSource: options.source,\n attributes: options.attributes,\n uniforms: options.uniforms,\n samplers: options.samplers,\n storageBuffers: options.storageBuffers,\n defines: options.defines,\n useThinInstanceColors: options.useThinInstanceColors,\n needAlphaBlending: options.needAlphaBlending,\n blendMode: options.blendMode,\n ...(options.blend === null ? {} : { blend: options.blend }),\n transmissive: options.transmissive,\n backFaceCulling: options.backFaceCulling,\n depthWrite: options.depthWrite,\n ...(options.depthCompare === null ? {} : { depthCompare: options.depthCompare }),\n });\n}\n\n/**\n * Writes a declared scalar, vector, or matrix uniform.\n *\n * @remarks\n * Lite compares the incoming numbers with the ones it holds and bumps the material's uniform\n * version only when one changed, so calling this every frame with an unchanged value costs a few\n * comparisons and no upload (`lib/material/shader/shader-material.js`, `setUniformValue`).\n *\n * @param material - The material to write to.\n * @param name - The declared uniform name.\n * @param value - The value; its length must match the declared type.\n * @throws Error from Babylon Lite when the name is not declared or the length is wrong.\n *\n * @internal\n */\nexport function writeShaderUniform(\n material: ShaderMaterial,\n name: string,\n value: number | readonly number[] | Float32Array,\n): void {\n setShaderUniform(material, name, value);\n}\n\n/**\n * Writes a declared `mat4x4<f32>` uniform from sixteen column-major floats.\n *\n * @param material - The material to write to.\n * @param name - The declared uniform name.\n * @param value - The matrix.\n *\n * @internal\n */\nexport function writeShaderMatrix(material: ShaderMaterial, name: string, value: Float32Array): void {\n setShaderMatrix(material, name, value);\n}\n\n/**\n * Binds or clears a declared sampler's texture.\n *\n * @param material - The material to write to.\n * @param name - The declared sampler name.\n * @param texture - The texture, or `null` to unbind. An unbound sampler makes the material\n * unbuildable, so ignifx always binds a fallback instead.\n *\n * @internal\n */\nexport function writeShaderTexture(material: ShaderMaterial, name: string, texture: Texture2D | null): void {\n setShaderTexture(material, name, texture);\n}\n\n/**\n * Binds or clears a declared storage buffer.\n *\n * @param material - The material to write to.\n * @param name - The declared storage buffer name.\n * @param buffer - The buffer, or `null` to unbind.\n *\n * @internal\n */\nexport function writeShaderStorageBuffer(material: ShaderMaterial, name: string, buffer: StorageBuffer | null): void {\n setShaderStorageBuffer(material, name, buffer);\n}\n\n/**\n * The 1x1 texture a declared-but-unbound sampler is filled with, created on first use and shared for\n * the life of the app.\n *\n * @param engine - The engine that owns the texture.\n * @param cache - The app's fallback textures, keyed by kind; a miss is created and stored.\n * @param fallback - `\"white\"`, `\"black\"`, or `\"transparent\"`; `null` means white.\n * @param array - `true` for a one-layer `texture_2d_array<f32>`.\n * @returns The texture.\n *\n * @internal\n */\nexport function resolveFallbackTexture(\n engine: EngineContext,\n cache: Map<string, Texture2D>,\n fallback: string | null,\n array: boolean,\n): Texture2D {\n const kind = fallback ?? \"white\";\n const key = array ? `${kind}:array` : kind;\n const cached = cache.get(key);\n if (cached !== undefined) {\n return cached;\n }\n const created = createFallbackTexture(engine, kind, array);\n cache.set(key, created);\n return created;\n}\n\n/**\n * Creates the 1x1 texture a declared-but-unbound sampler is filled with.\n *\n * @remarks\n * Babylon Lite refuses to build a bind group for a sampler with nothing bound (error 309), so a\n * material whose file declares `// @ignifx texture noise` and whose `.material.json` binds nothing\n * would be undrawable. One 1x1 texture per fallback kind per app is what makes it legal, which is\n * also Godot's `hint_default_white` behaviour.\n *\n * @param engine - The engine that owns the texture.\n * @param fallback - `\"white\"`, `\"black\"`, or `\"transparent\"`.\n * @param array - `true` for a one-layer `texture_2d_array<f32>`, which is what a sampler declared\n * `array` binds.\n * @returns The texture.\n *\n * @internal\n */\nexport function createFallbackTexture(engine: EngineContext, fallback: string, array: boolean): Texture2D {\n const rgba = FALLBACK_PIXELS[fallback] ?? FALLBACK_PIXELS[\"white\"];\n const pixels = Uint8Array.from(rgba ?? [255, 255, 255, 255]);\n return array\n ? createTexture2DArrayFromPixels(engine, pixels, 1, 1, 1, { mipMaps: false })\n : createTexture2DFromPixels(engine, pixels, 1, 1, {});\n}\n\n/**\n * Turns on Babylon Lite's cached uniform serialization plans for shader materials.\n *\n * @remarks\n * Process-global and idempotent: it installs two writer functions that keep a `WeakMap` of layout\n * plans per material and rewrite only the custom uniform slots whose value changed\n * (`lib/material/shader/enable-shader-material-uniform-caching.js`). That is exactly the shape of\n * ignifx's per-frame `time` upload, so the adapter enables it as it loads rather than making every\n * project remember to.\n *\n * @internal\n */\nexport function enableShaderUniformCaching(): void {\n enableShaderMaterialUniformCaching();\n}\n\n/**\n * Reads the installed environment's ambient irradiance — the `L00` band of its diffuse spherical\n * harmonics — into `out`.\n *\n * @remarks\n * `EnvironmentTextures.sphericalHarmonics` is declared: 36 floats in a stride-4 layout beginning\n * `[L00.rgb, 0, …]` (`index.d.ts`), the same block Babylon Lite writes into the scene uniform buffer\n * as `scene.vSphericalL00` and friends (`lib/scene/scene-ubo-extras.js`, `writeEnvUbo`). So the\n * value ignifx uploads as `ambientColor` is exactly what a shader could read for itself as\n * `scene.vSphericalL00.rgb`, which is the documented alternative for a shader that would rather not\n * declare the uniform. Reaching the slot goes through `./environment.ts`, which is the one place\n * ignifx touches the undeclared `scene._envTextures` field\n * (`docs/architecture/07-rendering.md` §2.5, §8).\n *\n * @param scene - The render scene.\n * @param out - Receives the three linear channels; left untouched when nothing is installed.\n * @returns `true` when an environment supplied harmonics.\n *\n * @internal\n */\nexport function readSceneAmbient(scene: SceneContext, out: Float32Array): boolean {\n const harmonics = readSceneEnvironment(scene)?.sphericalHarmonics;\n if (harmonics === undefined || harmonics.length < 3) {\n return false;\n }\n out[0] = harmonics[0] ?? 0;\n out[1] = harmonics[1] ?? 0;\n out[2] = harmonics[2] ?? 0;\n return true;\n}\n\n/**\n * The subset of this module `src/render/shader-material.ts` reaches through its dynamic `import()`,\n * named so the memo has a type that does not have to be written as `typeof import(…)` (which the\n * `consistent-type-imports` rule forbids).\n *\n * @remarks\n * Assigning the imported module namespace to this type is what checks the two against each other,\n * so a signature that drifts is a compile error rather than a runtime surprise.\n *\n * @internal\n */\nexport interface ShaderMaterialAdapter {\n /** {@link createShaderMaterialFromOptions}. */\n readonly createShaderMaterialFromOptions: (options: ShaderMaterialBuildOptions) => ShaderMaterial;\n /** {@link writeShaderUniform}. */\n readonly writeShaderUniform: (\n material: ShaderMaterial,\n name: string,\n value: number | readonly number[] | Float32Array,\n ) => void;\n /** {@link writeShaderMatrix}. */\n readonly writeShaderMatrix: (material: ShaderMaterial, name: string, value: Float32Array) => void;\n /** {@link writeShaderTexture}. */\n readonly writeShaderTexture: (material: ShaderMaterial, name: string, texture: Texture2D | null) => void;\n /** {@link writeShaderStorageBuffer}. */\n readonly writeShaderStorageBuffer: (material: ShaderMaterial, name: string, buffer: StorageBuffer | null) => void;\n /** {@link resolveFallbackTexture}. */\n readonly resolveFallbackTexture: (\n engine: EngineContext,\n cache: Map<string, Texture2D>,\n fallback: string | null,\n array: boolean,\n ) => Texture2D;\n /** {@link enableShaderUniformCaching}. */\n readonly enableShaderUniformCaching: () => void;\n /** {@link readSceneAmbient}. */\n readonly readSceneAmbient: (scene: SceneContext, out: Float32Array) => boolean;\n}\n"],"mappings":";;;;AAsDA,MAAM,kBAAuF,OAAO,OAAO;CACzG,OAAO;EAAC;EAAK;EAAK;EAAK;CAAG;CAC1B,OAAO;EAAC;EAAG;EAAG;EAAG;CAAG;CACpB,aAAa;EAAC;EAAG;EAAG;EAAG;CAAC;AAC1B,CAAC;;;;;;;;;;;;;;AAoGD,SAAgB,gCAAgC,SAAqD;CACnG,OAAO,qBAAqB;EAC1B,MAAM,QAAQ;EACd,cAAc,QAAQ;EACtB,gBAAgB,QAAQ;EACxB,YAAY,QAAQ;EACpB,UAAU,QAAQ;EAClB,UAAU,QAAQ;EAClB,gBAAgB,QAAQ;EACxB,SAAS,QAAQ;EACjB,uBAAuB,QAAQ;EAC/B,mBAAmB,QAAQ;EAC3B,WAAW,QAAQ;EACnB,GAAI,QAAQ,UAAU,OAAO,CAAC,IAAI,EAAE,OAAO,QAAQ,MAAM;EACzD,cAAc,QAAQ;EACtB,iBAAiB,QAAQ;EACzB,YAAY,QAAQ;EACpB,GAAI,QAAQ,iBAAiB,OAAO,CAAC,IAAI,EAAE,cAAc,QAAQ,aAAa;CAChF,CAAC;AACH;;;;;;;;;;;;;;;;AAiBA,SAAgB,mBACd,UACA,MACA,OACM;CACN,iBAAiB,UAAU,MAAM,KAAK;AACxC;;;;;;;;;;AAWA,SAAgB,kBAAkB,UAA0B,MAAc,OAA2B;CACnG,gBAAgB,UAAU,MAAM,KAAK;AACvC;;;;;;;;;;;AAYA,SAAgB,mBAAmB,UAA0B,MAAc,SAAiC;CAC1G,iBAAiB,UAAU,MAAM,OAAO;AAC1C;;;;;;;;;;AAWA,SAAgB,yBAAyB,UAA0B,MAAc,QAAoC;CACnH,uBAAuB,UAAU,MAAM,MAAM;AAC/C;;;;;;;;;;;;;AAcA,SAAgB,uBACd,QACA,OACA,UACA,OACW;CACX,MAAM,OAAO,YAAY;CACzB,MAAM,MAAM,QAAQ,GAAG,KAAK,UAAU;CACtC,MAAM,SAAS,MAAM,IAAI,GAAG;CAC5B,IAAI,WAAW,KAAA,GACb,OAAO;CAET,MAAM,UAAU,sBAAsB,QAAQ,MAAM,KAAK;CACzD,MAAM,IAAI,KAAK,OAAO;CACtB,OAAO;AACT;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,sBAAsB,QAAuB,UAAkB,OAA2B;CACxG,MAAM,OAAO,gBAAgB,aAAa,gBAAgB;CAC1D,MAAM,SAAS,WAAW,KAAK,QAAQ;EAAC;EAAK;EAAK;EAAK;CAAG,CAAC;CAC3D,OAAO,QACH,+BAA+B,QAAQ,QAAQ,GAAG,GAAG,GAAG,EAAE,SAAS,MAAM,CAAC,IAC1E,0BAA0B,QAAQ,QAAQ,GAAG,GAAG,CAAC,CAAC;AACxD;;;;;;;;;;;;;AAcA,SAAgB,6BAAmC;CACjD,mCAAmC;AACrC;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,iBAAiB,OAAqB,KAA4B;CAChF,MAAM,YAAY,qBAAqB,KAAK,CAAC,EAAE;CAC/C,IAAI,cAAc,KAAA,KAAa,UAAU,SAAS,GAChD,OAAO;CAET,IAAI,KAAK,UAAU,MAAM;CACzB,IAAI,KAAK,UAAU,MAAM;CACzB,IAAI,KAAK,UAAU,MAAM;CACzB,OAAO;AACT"}
1
+ {"version":3,"file":"shader-material-BPb_oEZQ.js","names":[],"sources":["../src/lite/gpu/shader-material.ts"],"sourcesContent":["import {\n createShaderMaterial,\n createTexture2DArrayFromPixels,\n createTexture2DFromPixels,\n enableShaderMaterialUniformCaching,\n setShaderMatrix,\n setShaderStorageBuffer,\n setShaderTexture,\n setShaderUniform,\n} from \"@babylonjs/lite\";\nimport { readSceneEnvironment } from \"./environment.js\";\nimport type {\n EngineContext,\n SceneContext,\n ShaderAttributeName,\n ShaderMaterial,\n ShaderSystemUniformName,\n ShaderUniformType,\n StorageBuffer,\n Texture2D,\n} from \"@babylonjs/lite\";\n\n/**\n * The custom-WGSL half of the Babylon Lite adapter: `createShaderMaterial`, the `setShader*`\n * setters, and the 1x1 fallback textures a declared sampler falls back to\n * (`docs/plan/2026-09-terrain-particles-shaders.md` §3.1, ADR-0024). Everything here is `@internal`.\n *\n * Lite exports one barrel, so a static import of `createShaderMaterial` anywhere in the reachable\n * graph pulls `lib/material/shader/**` into every entry chunk. This module is therefore reached with\n * `await import(...)` from `../../render/shader-support.ts`, and only loading a `.wgsl` triggers the\n * fetch. `./storage-buffer.ts` is a separate file for the same reason: `StorageBufferAsset`\n * allocates synchronously, so it cannot wait for this chunk.\n *\n * Two Lite facts it is written around:\n *\n * - Nothing may be left unbound: `createShaderBindGroup` throws (errors 309 and 310) when a declared\n * sampler has no texture or a declared storage buffer has no buffer, which is what\n * {@link createFallbackTexture} exists for.\n * - There is no front-face culling; `ShaderMaterialOptions` carries only `backFaceCulling`\n * (`lib/material/shader/shader-pipeline.js`), so the pragma parser refuses `cull front`.\n */\n\n/**\n * A Babylon Lite custom WGSL material, re-exported under an ignifx name\n * (`CONSTITUTION.md` §3.4, coding standards §4).\n *\n * @remarks\n * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.\n *\n * @public\n */\nexport type LiteShaderMaterial = ShaderMaterial;\n\n/** The RGBA bytes of each 1x1 fallback texture. */\nconst FALLBACK_PIXELS: Readonly<Record<string, readonly [number, number, number, number]>> = Object.freeze({\n white: [255, 255, 255, 255],\n black: [0, 0, 0, 255],\n transparent: [0, 0, 0, 0],\n});\n\n/**\n * One declared uniform in the form Babylon Lite's factory takes: either the name of a system\n * uniform it fills in itself, or a custom declaration with its initial value.\n *\n * @internal\n */\nexport type ShaderUniformEntry =\n | ShaderSystemUniformName\n | {\n /** The WGSL identifier. */\n readonly name: string;\n /** The WGSL type. */\n readonly type: ShaderUniformType;\n /** The initial value, **linear** for a colour. */\n readonly defaultValue: number | readonly number[];\n };\n\n/**\n * One declared sampler in the form Babylon Lite's factory takes.\n *\n * @internal\n */\nexport interface ShaderSamplerEntry {\n /** The WGSL identifier; Lite generates `<name>Sampler` beside it. */\n readonly name: string;\n /** `\"2d-array\"` for a `texture_2d_array<f32>` binding. */\n readonly viewDimension: \"2d\" | \"2d-array\";\n}\n\n/**\n * One declared storage buffer in the form Babylon Lite's factory takes.\n *\n * @internal\n */\nexport interface ShaderStorageEntry {\n /** The WGSL identifier. */\n readonly name: string;\n /** The WGSL variable type, verbatim. */\n readonly type: string;\n}\n\n/**\n * Everything Babylon Lite's `createShaderMaterial` needs, in ignifx's own vocabulary so that the\n * mapping from a `ShaderDeclaration` can be built and asserted without a device or a Lite import\n * (`src/render/shader-material.ts`).\n *\n * @remarks\n * A `null` blend state or depth comparison means \"leave Babylon Lite's own default in place\", so\n * this module never restates a Lite default that could change.\n *\n * @internal\n */\nexport interface ShaderMaterialBuildOptions {\n /** The material's name, used in pipeline and shader-module labels. */\n readonly name: string;\n /** The WGSL source, handed to Lite as both the vertex and the fragment source. */\n readonly source: string;\n /** The vertex attributes the vertex stage reads; `position` is mandatory. */\n readonly attributes: readonly ShaderAttributeName[];\n /** The system and custom uniforms, in binding-declaration order. */\n readonly uniforms: readonly ShaderUniformEntry[];\n /** The samplers. */\n readonly samplers: readonly ShaderSamplerEntry[];\n /** The read-only storage buffers. */\n readonly storageBuffers: readonly ShaderStorageEntry[];\n /** The WGSL `const` declarations, resolved from the file's defaults and the material's overrides. */\n readonly defines: Readonly<Record<string, boolean | number>>;\n /** Whether the thin-instance RGBA stream is bound and injected into `VertexInput`. */\n readonly useThinInstanceColors: boolean;\n /** Whether the surface is alpha-blended. */\n readonly needAlphaBlending: boolean;\n /** Which of Lite's two blend equations to use when no explicit state is given. */\n readonly blendMode: \"alpha\" | \"additive\";\n /** An explicit colour-target blend state, which replaces the derived one; `null` to derive it. */\n readonly blend: GPUBlendState | null;\n /** Whether the surface samples the opaque scene colour behind it. */\n readonly transmissive: boolean;\n /** Whether back faces are culled. */\n readonly backFaceCulling: boolean;\n /** Whether the draw writes depth. */\n readonly depthWrite: boolean;\n /** The depth comparison, or `null` for Lite's own reverse-Z default. */\n readonly depthCompare: GPUCompareFunction | null;\n}\n\n/**\n * Builds a Babylon Lite custom WGSL material.\n *\n * @remarks\n * Validation is eager and compilation is lazy, so this runs under the null engine; the pipeline is\n * compiled the first time a mesh wearing the material is drawn.\n *\n * @param options - The sources and the declared attribute, uniform, sampler, and storage layout.\n * @returns The material.\n * @throws Error from Babylon Lite when the declaration is not one it can build.\n *\n * @internal\n */\nexport function createShaderMaterialFromOptions(options: ShaderMaterialBuildOptions): ShaderMaterial {\n return createShaderMaterial({\n name: options.name,\n vertexSource: options.source,\n fragmentSource: options.source,\n attributes: options.attributes,\n uniforms: options.uniforms,\n samplers: options.samplers,\n storageBuffers: options.storageBuffers,\n defines: options.defines,\n useThinInstanceColors: options.useThinInstanceColors,\n needAlphaBlending: options.needAlphaBlending,\n blendMode: options.blendMode,\n ...(options.blend === null ? {} : { blend: options.blend }),\n transmissive: options.transmissive,\n backFaceCulling: options.backFaceCulling,\n depthWrite: options.depthWrite,\n ...(options.depthCompare === null ? {} : { depthCompare: options.depthCompare }),\n });\n}\n\n/**\n * Writes a declared scalar, vector, or matrix uniform.\n *\n * @remarks\n * Lite compares the incoming numbers with the ones it holds and bumps the material's uniform\n * version only when one changed, so calling this every frame with an unchanged value costs a few\n * comparisons and no upload (`lib/material/shader/shader-material.js`, `setUniformValue`).\n *\n * @param material - The material to write to.\n * @param name - The declared uniform name.\n * @param value - The value; its length must match the declared type.\n * @throws Error from Babylon Lite when the name is not declared or the length is wrong.\n *\n * @internal\n */\nexport function writeShaderUniform(\n material: ShaderMaterial,\n name: string,\n value: number | readonly number[] | Float32Array,\n): void {\n setShaderUniform(material, name, value);\n}\n\n/**\n * Writes a declared `mat4x4<f32>` uniform from sixteen column-major floats.\n *\n * @param material - The material to write to.\n * @param name - The declared uniform name.\n * @param value - The matrix.\n *\n * @internal\n */\nexport function writeShaderMatrix(material: ShaderMaterial, name: string, value: Float32Array): void {\n setShaderMatrix(material, name, value);\n}\n\n/**\n * Binds or clears a declared sampler's texture.\n *\n * @param material - The material to write to.\n * @param name - The declared sampler name.\n * @param texture - The texture, or `null` to unbind. An unbound sampler makes the material\n * unbuildable, so ignifx always binds a fallback instead.\n *\n * @internal\n */\nexport function writeShaderTexture(material: ShaderMaterial, name: string, texture: Texture2D | null): void {\n setShaderTexture(material, name, texture);\n}\n\n/**\n * Binds or clears a declared storage buffer.\n *\n * @param material - The material to write to.\n * @param name - The declared storage buffer name.\n * @param buffer - The buffer, or `null` to unbind.\n *\n * @internal\n */\nexport function writeShaderStorageBuffer(material: ShaderMaterial, name: string, buffer: StorageBuffer | null): void {\n setShaderStorageBuffer(material, name, buffer);\n}\n\n/**\n * The 1x1 texture a declared-but-unbound sampler is filled with, created on first use and shared for\n * the life of the app.\n *\n * @param engine - The engine that owns the texture.\n * @param cache - The app's fallback textures, keyed by kind; a miss is created and stored.\n * @param fallback - `\"white\"`, `\"black\"`, or `\"transparent\"`; `null` means white.\n * @param array - `true` for a one-layer `texture_2d_array<f32>`.\n * @returns The texture.\n *\n * @internal\n */\nexport function resolveFallbackTexture(\n engine: EngineContext,\n cache: Map<string, Texture2D>,\n fallback: string | null,\n array: boolean,\n): Texture2D {\n const kind = fallback ?? \"white\";\n const key = array ? `${kind}:array` : kind;\n const cached = cache.get(key);\n if (cached !== undefined) {\n return cached;\n }\n const created = createFallbackTexture(engine, kind, array);\n cache.set(key, created);\n return created;\n}\n\n/**\n * Creates the 1x1 texture a declared-but-unbound sampler is filled with.\n *\n * @remarks\n * Babylon Lite refuses to build a bind group for a sampler with nothing bound (error 309), so a\n * material whose file declares `// @ignifx texture noise` and whose `.material.json` binds nothing\n * would be undrawable. One 1x1 texture per fallback kind per app is what makes it legal, which is\n * also Godot's `hint_default_white` behaviour.\n *\n * @param engine - The engine that owns the texture.\n * @param fallback - `\"white\"`, `\"black\"`, or `\"transparent\"`.\n * @param array - `true` for a one-layer `texture_2d_array<f32>`, which is what a sampler declared\n * `array` binds.\n * @returns The texture.\n *\n * @internal\n */\nexport function createFallbackTexture(engine: EngineContext, fallback: string, array: boolean): Texture2D {\n const rgba = FALLBACK_PIXELS[fallback] ?? FALLBACK_PIXELS[\"white\"];\n const pixels = Uint8Array.from(rgba ?? [255, 255, 255, 255]);\n return array\n ? createTexture2DArrayFromPixels(engine, pixels, 1, 1, 1, { mipMaps: false })\n : createTexture2DFromPixels(engine, pixels, 1, 1, {});\n}\n\n/**\n * Turns on Babylon Lite's cached uniform serialization plans for shader materials.\n *\n * @remarks\n * Process-global and idempotent: it installs two writer functions that keep a `WeakMap` of layout\n * plans per material and rewrite only the custom uniform slots whose value changed\n * (`lib/material/shader/enable-shader-material-uniform-caching.js`). That is exactly the shape of\n * ignifx's per-frame `time` upload, so the adapter enables it as it loads rather than making every\n * project remember to.\n *\n * @internal\n */\nexport function enableShaderUniformCaching(): void {\n enableShaderMaterialUniformCaching();\n}\n\n/**\n * Reads the installed environment's ambient irradiance — the `L00` band of its diffuse spherical\n * harmonics — into `out`.\n *\n * @remarks\n * `EnvironmentTextures.sphericalHarmonics` is declared: 36 floats in a stride-4 layout beginning\n * `[L00.rgb, 0, …]` (`index.d.ts`), the same block Babylon Lite writes into the scene uniform buffer\n * as `scene.vSphericalL00` and friends (`lib/scene/scene-ubo-extras.js`, `writeEnvUbo`). So the\n * value ignifx uploads as `ambientColor` is exactly what a shader could read for itself as\n * `scene.vSphericalL00.rgb`, which is the documented alternative for a shader that would rather not\n * declare the uniform. Reaching the slot goes through `./environment.ts`, which is the one place\n * ignifx touches the undeclared `scene._envTextures` field\n * (`docs/architecture/07-rendering.md` §2.5, §8).\n *\n * @param scene - The render scene.\n * @param out - Receives the three linear channels; left untouched when nothing is installed.\n * @returns `true` when an environment supplied harmonics.\n *\n * @internal\n */\nexport function readSceneAmbient(scene: SceneContext, out: Float32Array): boolean {\n const harmonics = readSceneEnvironment(scene)?.sphericalHarmonics;\n if (harmonics === undefined || harmonics.length < 3) {\n return false;\n }\n out[0] = harmonics[0] ?? 0;\n out[1] = harmonics[1] ?? 0;\n out[2] = harmonics[2] ?? 0;\n return true;\n}\n\n/**\n * The subset of this module `src/render/shader-material.ts` reaches through its dynamic `import()`,\n * named so the memo has a type that does not have to be written as `typeof import(…)` (which the\n * `consistent-type-imports` rule forbids).\n *\n * @remarks\n * Assigning the imported module namespace to this type is what checks the two against each other,\n * so a signature that drifts is a compile error rather than a runtime surprise.\n *\n * @internal\n */\nexport interface ShaderMaterialAdapter {\n /** {@link createShaderMaterialFromOptions}. */\n readonly createShaderMaterialFromOptions: (options: ShaderMaterialBuildOptions) => ShaderMaterial;\n /** {@link writeShaderUniform}. */\n readonly writeShaderUniform: (\n material: ShaderMaterial,\n name: string,\n value: number | readonly number[] | Float32Array,\n ) => void;\n /** {@link writeShaderMatrix}. */\n readonly writeShaderMatrix: (material: ShaderMaterial, name: string, value: Float32Array) => void;\n /** {@link writeShaderTexture}. */\n readonly writeShaderTexture: (material: ShaderMaterial, name: string, texture: Texture2D | null) => void;\n /** {@link writeShaderStorageBuffer}. */\n readonly writeShaderStorageBuffer: (material: ShaderMaterial, name: string, buffer: StorageBuffer | null) => void;\n /** {@link resolveFallbackTexture}. */\n readonly resolveFallbackTexture: (\n engine: EngineContext,\n cache: Map<string, Texture2D>,\n fallback: string | null,\n array: boolean,\n ) => Texture2D;\n /** {@link enableShaderUniformCaching}. */\n readonly enableShaderUniformCaching: () => void;\n /** {@link readSceneAmbient}. */\n readonly readSceneAmbient: (scene: SceneContext, out: Float32Array) => boolean;\n}\n"],"mappings":";;;;AAsDA,MAAM,kBAAuF,OAAO,OAAO;CACzG,OAAO;EAAC;EAAK;EAAK;EAAK;CAAG;CAC1B,OAAO;EAAC;EAAG;EAAG;EAAG;CAAG;CACpB,aAAa;EAAC;EAAG;EAAG;EAAG;CAAC;AAC1B,CAAC;;;;;;;;;;;;;;AAoGD,SAAgB,gCAAgC,SAAqD;CACnG,OAAO,qBAAqB;EAC1B,MAAM,QAAQ;EACd,cAAc,QAAQ;EACtB,gBAAgB,QAAQ;EACxB,YAAY,QAAQ;EACpB,UAAU,QAAQ;EAClB,UAAU,QAAQ;EAClB,gBAAgB,QAAQ;EACxB,SAAS,QAAQ;EACjB,uBAAuB,QAAQ;EAC/B,mBAAmB,QAAQ;EAC3B,WAAW,QAAQ;EACnB,GAAI,QAAQ,UAAU,OAAO,CAAC,IAAI,EAAE,OAAO,QAAQ,MAAM;EACzD,cAAc,QAAQ;EACtB,iBAAiB,QAAQ;EACzB,YAAY,QAAQ;EACpB,GAAI,QAAQ,iBAAiB,OAAO,CAAC,IAAI,EAAE,cAAc,QAAQ,aAAa;CAChF,CAAC;AACH;;;;;;;;;;;;;;;;AAiBA,SAAgB,mBACd,UACA,MACA,OACM;CACN,iBAAiB,UAAU,MAAM,KAAK;AACxC;;;;;;;;;;AAWA,SAAgB,kBAAkB,UAA0B,MAAc,OAA2B;CACnG,gBAAgB,UAAU,MAAM,KAAK;AACvC;;;;;;;;;;;AAYA,SAAgB,mBAAmB,UAA0B,MAAc,SAAiC;CAC1G,iBAAiB,UAAU,MAAM,OAAO;AAC1C;;;;;;;;;;AAWA,SAAgB,yBAAyB,UAA0B,MAAc,QAAoC;CACnH,uBAAuB,UAAU,MAAM,MAAM;AAC/C;;;;;;;;;;;;;AAcA,SAAgB,uBACd,QACA,OACA,UACA,OACW;CACX,MAAM,OAAO,YAAY;CACzB,MAAM,MAAM,QAAQ,GAAG,KAAK,UAAU;CACtC,MAAM,SAAS,MAAM,IAAI,GAAG;CAC5B,IAAI,WAAW,KAAA,GACb,OAAO;CAET,MAAM,UAAU,sBAAsB,QAAQ,MAAM,KAAK;CACzD,MAAM,IAAI,KAAK,OAAO;CACtB,OAAO;AACT;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,sBAAsB,QAAuB,UAAkB,OAA2B;CACxG,MAAM,OAAO,gBAAgB,aAAa,gBAAgB;CAC1D,MAAM,SAAS,WAAW,KAAK,QAAQ;EAAC;EAAK;EAAK;EAAK;CAAG,CAAC;CAC3D,OAAO,QACH,+BAA+B,QAAQ,QAAQ,GAAG,GAAG,GAAG,EAAE,SAAS,MAAM,CAAC,IAC1E,0BAA0B,QAAQ,QAAQ,GAAG,GAAG,CAAC,CAAC;AACxD;;;;;;;;;;;;;AAcA,SAAgB,6BAAmC;CACjD,mCAAmC;AACrC;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,iBAAiB,OAAqB,KAA4B;CAChF,MAAM,YAAY,qBAAqB,KAAK,CAAC,EAAE;CAC/C,IAAI,cAAc,KAAA,KAAa,UAAU,SAAS,GAChD,OAAO;CAET,IAAI,KAAK,UAAU,MAAM;CACzB,IAAI,KAAK,UAAU,MAAM;CACzB,IAAI,KAAK,UAAU,MAAM;CACzB,OAAO;AACT"}
@@ -1,4 +1,4 @@
1
- import { o as CoreErrorCode, t as IgnifxError } from "./ignifx-error-Dq2qJMkZ.js";
1
+ import { o as CoreErrorCode, t as IgnifxError } from "./ignifx-error-oYdVnT1S.js";
2
2
  import { t as Color } from "./color-DrR6GFTd.js";
3
3
  import { t as setOwnJsonProperty } from "./json-CzZZ6K4x.js";
4
4
  import { n as IGNIFX_UNIFORM_TYPES, r as LITE_SYSTEM_UNIFORM_NAMES, t as IGNIFX_UNIFORM_NAMES } from "./shader-declaration-5q__jycG.js";
@@ -173,7 +173,7 @@ let adapter = null;
173
173
  */
174
174
  async function loadShaderMaterialAdapter() {
175
175
  if (adapter !== null) return;
176
- const loaded = await import("./shader-material-BxQn9FT4.js");
176
+ const loaded = await import("./shader-material-BPb_oEZQ.js");
177
177
  loaded.enableShaderUniformCaching();
178
178
  adapter = loaded;
179
179
  }
@@ -1010,4 +1010,4 @@ function shapeMismatch(declaration, material, expected, actual) {
1010
1010
  //#endregion
1011
1011
  export { shader_material_exports as n, shaderMaterialsOf as t };
1012
1012
 
1013
- //# sourceMappingURL=shader-material-DRZmqA_S.js.map
1013
+ //# sourceMappingURL=shader-material-CDQ0Y5kN.js.map