@ignifx/core 0.17.0 → 0.18.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 (46) hide show
  1. package/dist/{environment-CMpzGXTz.js → environment-DZ6WUHbm.js} +2 -2
  2. package/dist/{environment-CMpzGXTz.js.map → environment-DZ6WUHbm.js.map} +1 -1
  3. package/dist/{hdr-output-BrUvpAsE.js → hdr-output-Dbv0lhFl.js} +4 -3
  4. package/dist/{hdr-output-BrUvpAsE.js.map → hdr-output-Dbv0lhFl.js.map} +1 -1
  5. package/dist/{ignifx-error-Der0bpHK.js → ignifx-error-B8ByiSfJ.js} +10 -1
  6. package/dist/ignifx-error-B8ByiSfJ.js.map +1 -0
  7. package/dist/index.d.ts +110 -3
  8. package/dist/index.d.ts.map +1 -1
  9. package/dist/index.js +836 -35
  10. package/dist/index.js.map +1 -1
  11. package/dist/light-probe-asset-B60_X-yN.js +331 -0
  12. package/dist/light-probe-asset-B60_X-yN.js.map +1 -0
  13. package/dist/light-probes-DkYN89Qw.js +284 -0
  14. package/dist/light-probes-DkYN89Qw.js.map +1 -0
  15. package/dist/{material-plugin-B-hartHR.js → material-plugin-CiAmriQ_.js} +2 -2
  16. package/dist/{material-plugin-B-hartHR.js.map → material-plugin-CiAmriQ_.js.map} +1 -1
  17. package/dist/{post-effect-CuoYvrhb.js → post-effect-CQnlX1RH.js} +2 -2
  18. package/dist/{post-effect-CuoYvrhb.js.map → post-effect-CQnlX1RH.js.map} +1 -1
  19. package/dist/{post-effect-compiler-Bps8QbiJ.js → post-effect-compiler-C_7HTHZy.js} +3 -3
  20. package/dist/{post-effect-compiler-Bps8QbiJ.js.map → post-effect-compiler-C_7HTHZy.js.map} +1 -1
  21. package/dist/{prefab-overrides-76IhcF-e.d.ts → prefab-overrides-BLQn5yHS.d.ts} +231 -7
  22. package/dist/prefab-overrides-BLQn5yHS.d.ts.map +1 -0
  23. package/dist/{prefab-overrides-DGiGTSN-.js → prefab-overrides-DT-wHHAJ.js} +2 -2
  24. package/dist/{prefab-overrides-DGiGTSN-.js.map → prefab-overrides-DT-wHHAJ.js.map} +1 -1
  25. package/dist/prefab.d.ts +1 -1
  26. package/dist/prefab.js +1 -1
  27. package/dist/{reflection-probe-C0pzGrG_.js → reflection-probe-DlVsl3zJ.js} +3 -3
  28. package/dist/{reflection-probe-C0pzGrG_.js.map → reflection-probe-DlVsl3zJ.js.map} +1 -1
  29. package/dist/{reflection-probes-B8_vK9YR.js → reflection-probes-B8S9WnVX.js} +3 -3
  30. package/dist/{reflection-probes-B8_vK9YR.js.map → reflection-probes-B8S9WnVX.js.map} +1 -1
  31. package/dist/{render-path-Be7WgN7r.js → render-path-D11i_7X8.js} +3 -2
  32. package/dist/{render-path-Be7WgN7r.js.map → render-path-D11i_7X8.js.map} +1 -1
  33. package/dist/{scene-color-passes-DlNr-qyZ.js → scene-color-passes-B93qTOka.js} +35 -12
  34. package/dist/scene-color-passes-B93qTOka.js.map +1 -0
  35. package/dist/{shader-material-Cjfq7nFS.js → shader-material-C2_UCYdO.js} +5 -5
  36. package/dist/{shader-material-Cjfq7nFS.js.map → shader-material-C2_UCYdO.js.map} +1 -1
  37. package/dist/{shader-material-DCjYDdkh.js → shader-material-CaAkv5nT.js} +2 -2
  38. package/dist/{shader-material-DCjYDdkh.js.map → shader-material-CaAkv5nT.js.map} +1 -1
  39. package/dist/{shader-pragma-cjEC-EPK.js → shader-pragma-DmZpxGUo.js} +2 -2
  40. package/dist/{shader-pragma-cjEC-EPK.js.map → shader-pragma-DmZpxGUo.js.map} +1 -1
  41. package/dist/{surface-shader-D40hXQ8c.js → surface-shader-BeDRofOV.js} +4 -4
  42. package/dist/{surface-shader-D40hXQ8c.js.map → surface-shader-BeDRofOV.js.map} +1 -1
  43. package/package.json +1 -1
  44. package/dist/ignifx-error-Der0bpHK.js.map +0 -1
  45. package/dist/prefab-overrides-76IhcF-e.d.ts.map +0 -1
  46. package/dist/scene-color-passes-DlNr-qyZ.js.map +0 -1
@@ -0,0 +1,331 @@
1
+ import { o as CoreErrorCode, t as IgnifxError } from "./ignifx-error-B8ByiSfJ.js";
2
+ //#region src/render/light-probe-asset.ts
3
+ /**
4
+ * Light probes (`docs/plan/2026-11-gi-phase-2-execution-plan.md`, step B2): a regular grid of baked
5
+ * irradiance samples that a `LightProbeVolume` lights PBR materials with, in place of the scene
6
+ * environment's diffuse light. Everything here is plain data and runs in Node.
7
+ *
8
+ * Each probe stores four RGB coefficients of first-order spherical harmonics, already convolved and
9
+ * scaled the way Babylon Lite's environment harmonics are, so the diffuse light a white surface with
10
+ * normal `n` receives is `c0 + c1·n.y + c2·n.z + c3·n.x` (Lite's `environmentIrradiance`, L1 part).
11
+ */
12
+ /**
13
+ * The asset type light-probe grids are registered under.
14
+ *
15
+ * @public
16
+ */
17
+ const LIGHT_PROBE_ASSET_TYPE = "lightprobes";
18
+ /**
19
+ * The address extensions that select the light-probe loader.
20
+ *
21
+ * @public
22
+ */
23
+ const LIGHT_PROBE_FILE_EXTENSIONS = Object.freeze([".probes.json"]);
24
+ /**
25
+ * The `format` header every `.probes.json` carries.
26
+ *
27
+ * @public
28
+ */
29
+ const LIGHT_PROBE_FILE_FORMAT = "ignifx-probes";
30
+ /**
31
+ * The `formatVersion` this engine reads and writes.
32
+ *
33
+ * @public
34
+ */
35
+ const LIGHT_PROBE_FORMAT_VERSION = 1;
36
+ /** Floats per probe: four RGB coefficients. */
37
+ const FLOATS_PER_PROBE = 12;
38
+ /** The largest grid side along X (the texture is four times as wide) and the largest Y·Z product. */
39
+ const MAX_X = 1024;
40
+ const MAX_YZ = 4096;
41
+ /** The bounds that keep the generated shader constants valid 32-bit floats. */
42
+ const MAX_COORDINATE = 0x56bc75e2d63100000;
43
+ const MIN_CELL = 1e-30;
44
+ /**
45
+ * A loaded light-probe grid.
46
+ *
47
+ * @example
48
+ * ```ts
49
+ * const probes = await app.assets.loadAsync<LightProbeAsset>("lighting/hall.probes.json");
50
+ * world.createEntity("Probes").addComponent(LightProbeVolume, { probes });
51
+ * ```
52
+ *
53
+ * @beta
54
+ */
55
+ var LightProbeAsset = class {
56
+ /** The type name the asset service registers light-probe grids under. */
57
+ static assetType = LIGHT_PROBE_ASSET_TYPE;
58
+ /** The grid. */
59
+ data;
60
+ /**
61
+ * Wraps a checked grid. Use the loader or {@link createLightProbeAsset}.
62
+ *
63
+ * @param data - The grid, already checked by `readLightProbeData`.
64
+ *
65
+ * @internal
66
+ */
67
+ constructor(data) {
68
+ this.data = data;
69
+ }
70
+ };
71
+ /**
72
+ * Publishes a grid built in code, such as the result of a bake, as an asset.
73
+ *
74
+ * @param app - The app.
75
+ * @param data - The grid.
76
+ * @returns A handle a `LightProbeVolume` can take.
77
+ * @throws IgnifxError with code `IGX-0709` when the grid is malformed.
78
+ *
79
+ * @beta
80
+ */
81
+ function createLightProbeAsset(app, data) {
82
+ return app.assets.register(new LightProbeAsset(readLightProbeData(data, "light probe data")), { type: LIGHT_PROBE_ASSET_TYPE });
83
+ }
84
+ /**
85
+ * Turns a grid into the JSON a `.probes.json` file holds.
86
+ *
87
+ * @param data - The grid.
88
+ * @returns The file contents, with the format header.
89
+ *
90
+ * @beta
91
+ */
92
+ function writeLightProbeFile(data) {
93
+ return {
94
+ format: LIGHT_PROBE_FILE_FORMAT,
95
+ formatVersion: 1,
96
+ origin: {
97
+ x: data.origin.x,
98
+ y: data.origin.y,
99
+ z: data.origin.z
100
+ },
101
+ cellSize: {
102
+ x: data.cellSize.x,
103
+ y: data.cellSize.y,
104
+ z: data.cellSize.z
105
+ },
106
+ counts: {
107
+ x: data.counts.x,
108
+ y: data.counts.y,
109
+ z: data.counts.z
110
+ },
111
+ coefficients: [...data.coefficients]
112
+ };
113
+ }
114
+ /**
115
+ * Reads a parsed `.probes.json`.
116
+ *
117
+ * @param parsed - The parsed JSON.
118
+ * @param address - The file's address, for the error.
119
+ * @returns The grid.
120
+ * @throws IgnifxError with code `IGX-0709` when the header, a field or the coefficient count is wrong.
121
+ *
122
+ * @internal
123
+ */
124
+ function readLightProbeFile(parsed, address) {
125
+ const file = asRecord(parsed);
126
+ if (file === null || file["format"] !== "ignifx-probes" || file["formatVersion"] !== 1) throw invalid(address, `it must start with { "format": "${LIGHT_PROBE_FILE_FORMAT}", "formatVersion": 1 }`);
127
+ return readLightProbeData(file, address);
128
+ }
129
+ /**
130
+ * Checks a grid's fields.
131
+ *
132
+ * @param value - The candidate grid.
133
+ * @param address - Where it came from, for the error.
134
+ * @returns A grid with copied, checked fields.
135
+ * @throws IgnifxError with code `IGX-0709` on a malformed field.
136
+ *
137
+ * @internal
138
+ */
139
+ function readLightProbeData(value, address) {
140
+ const record = asRecord(value);
141
+ if (record === null) throw invalid(address, "it is not an object");
142
+ const grid = readLightProbeGrid(record);
143
+ if (typeof grid === "string") throw invalid(address, grid);
144
+ const { origin, cellSize, counts } = grid;
145
+ const coefficients = record["coefficients"];
146
+ const expected = counts.x * counts.y * counts.z * FLOATS_PER_PROBE;
147
+ if (!Array.isArray(coefficients) || coefficients.length !== expected || !coefficients.every((n) => Number.isFinite(n))) throw invalid(address, `coefficients must be ${String(expected)} finite numbers (12 per probe)`);
148
+ return {
149
+ origin,
150
+ cellSize,
151
+ counts,
152
+ coefficients: coefficients.map(Number)
153
+ };
154
+ }
155
+ /**
156
+ * Checks the grid fields of a candidate grid, for a file and for a bake alike.
157
+ *
158
+ * @remarks
159
+ * Besides the format's count limits, `origin` stays below 1e20 in size and `cellSize` between
160
+ * 1e-30 and 1e20, so the constants the shader is generated with stay valid 32-bit floats.
161
+ *
162
+ * @param record - An object with `origin`, `cellSize` and `counts`.
163
+ * @returns The checked copies, or what is wrong with them.
164
+ *
165
+ * @internal
166
+ */
167
+ function readLightProbeGrid(record) {
168
+ const origin = readVec3(record["origin"], (n) => Number.isFinite(n) && Math.abs(n) < MAX_COORDINATE);
169
+ const cellSize = readVec3(record["cellSize"], (n) => Number.isFinite(n) && n > MIN_CELL && n < MAX_COORDINATE);
170
+ const counts = readVec3(record["counts"], (n) => Number.isSafeInteger(n) && n >= 1);
171
+ if (origin === null || cellSize === null || counts === null) return "origin (finite, below 1e20), cellSize (from 1e-30 to 1e20) and counts (whole, at least 1) must each be { x, y, z }";
172
+ if (counts.x > MAX_X || counts.y * counts.z > MAX_YZ) return `counts.x must be at most ${String(MAX_X)} and counts.y × counts.z at most ${String(MAX_YZ)}`;
173
+ return {
174
+ origin,
175
+ cellSize,
176
+ counts
177
+ };
178
+ }
179
+ /**
180
+ * The diffuse light a white surface receives at a point, read from the grid on the CPU the same way
181
+ * the shader reads it: trilinear between the eight surrounding probes, clamped at the grid's edges.
182
+ *
183
+ * @param data - The grid.
184
+ * @param x - World X.
185
+ * @param y - World Y.
186
+ * @param z - World Z.
187
+ * @param normal - The surface normal, unit length.
188
+ * @returns Linear RGB.
189
+ *
190
+ * @beta
191
+ */
192
+ function sampleLightProbes(data, x, y, z, normal) {
193
+ const { counts } = data;
194
+ const gx = gridCoordinate(x, data.origin.x, data.cellSize.x, counts.x);
195
+ const gy = gridCoordinate(y, data.origin.y, data.cellSize.y, counts.y);
196
+ const gz = gridCoordinate(z, data.origin.z, data.cellSize.z, counts.z);
197
+ const out = [
198
+ 0,
199
+ 0,
200
+ 0
201
+ ];
202
+ for (let corner = 0; corner < 8; corner += 1) {
203
+ const ix = corner & 1 ? gx.high : gx.low;
204
+ const iy = corner & 2 ? gy.high : gy.low;
205
+ const iz = corner & 4 ? gz.high : gz.low;
206
+ const weight = (corner & 1 ? gx.t : 1 - gx.t) * (corner & 2 ? gy.t : 1 - gy.t) * (corner & 4 ? gz.t : 1 - gz.t);
207
+ const base = (ix + counts.x * (iy + counts.y * iz)) * FLOATS_PER_PROBE;
208
+ for (let channel = 0; channel < 3; channel += 1) {
209
+ const c = (index) => data.coefficients[base + index * 3 + channel] ?? 0;
210
+ out[channel] = (out[channel] ?? 0) + weight * (c(0) + c(1) * normal.y + c(2) * normal.z + c(3) * normal.x);
211
+ }
212
+ }
213
+ return out;
214
+ }
215
+ /**
216
+ * Packs a grid into the half-float RGBA texels the shader reads: probe `(i, j, k)`'s coefficient `c`
217
+ * at texel `(i + countX·c, j + countY·k)`.
218
+ *
219
+ * @param data - The grid.
220
+ * @returns The width, height and texels (four half floats each, alpha 1).
221
+ *
222
+ * @internal
223
+ */
224
+ function packLightProbeTexels(data) {
225
+ const { x: nx, y: ny, z: nz } = data.counts;
226
+ const width = nx * 4;
227
+ const height = ny * nz;
228
+ const texels = new Uint16Array(width * height * 4);
229
+ const one = toHalfFloat(1);
230
+ for (let k = 0; k < nz; k += 1) for (let j = 0; j < ny; j += 1) for (let i = 0; i < nx; i += 1) {
231
+ const base = (i + nx * (j + ny * k)) * FLOATS_PER_PROBE;
232
+ for (let c = 0; c < 4; c += 1) {
233
+ const texel = (i + nx * c + width * (j + ny * k)) * 4;
234
+ for (let channel = 0; channel < 3; channel += 1) texels[texel + channel] = toHalfFloat(data.coefficients[base + c * 3 + channel] ?? 0);
235
+ texels[texel + 3] = one;
236
+ }
237
+ }
238
+ return {
239
+ width,
240
+ height,
241
+ texels
242
+ };
243
+ }
244
+ /**
245
+ * Converts a number to IEEE 754 half precision, rounding to nearest and saturating to ±65504.
246
+ *
247
+ * @param value - The number.
248
+ * @returns The 16 bits.
249
+ *
250
+ * @internal
251
+ */
252
+ function toHalfFloat(value) {
253
+ if (Number.isNaN(value)) return 32256;
254
+ const sign = value < 0 || Object.is(value, -0) ? 32768 : 0;
255
+ const magnitude = Math.min(Math.abs(value), 65504);
256
+ if (magnitude < 2 ** -24) return sign;
257
+ if (magnitude < 2 ** -14) return sign | Math.round(magnitude / 2 ** -24);
258
+ const exponent = Math.floor(Math.log2(magnitude));
259
+ const mantissa = Math.round((magnitude / 2 ** exponent - 1) * 1024);
260
+ return sign | (exponent + 15 << 10) + mantissa;
261
+ }
262
+ /**
263
+ * Finds the probes around a coordinate on one axis.
264
+ *
265
+ * @param value - The world coordinate.
266
+ * @param origin - The grid origin on this axis.
267
+ * @param cell - The cell size on this axis.
268
+ * @param count - The probe count on this axis.
269
+ * @returns The cell.
270
+ */
271
+ function gridCoordinate(value, origin, cell, count) {
272
+ const g = Math.min(Math.max((value - origin) / cell, 0), count - 1);
273
+ const low = Math.min(Math.floor(g), Math.max(count - 2, 0));
274
+ return {
275
+ low,
276
+ high: Math.min(low + 1, count - 1),
277
+ t: g - low
278
+ };
279
+ }
280
+ /**
281
+ * Reads `{ x, y, z }` whose components all pass a check.
282
+ *
283
+ * @param value - The candidate.
284
+ * @param check - The per-component test.
285
+ * @returns A copy, or `null`.
286
+ */
287
+ function readVec3(value, check) {
288
+ const record = asRecord(value);
289
+ if (record === null) return null;
290
+ const { x, y, z } = record;
291
+ if (typeof x !== "number" || typeof y !== "number" || typeof z !== "number" || ![
292
+ x,
293
+ y,
294
+ z
295
+ ].every(check)) return null;
296
+ return {
297
+ x,
298
+ y,
299
+ z
300
+ };
301
+ }
302
+ /**
303
+ * Narrows a value to a plain record.
304
+ *
305
+ * @param value - The candidate.
306
+ * @returns The record, or `null` for anything else.
307
+ */
308
+ function asRecord(value) {
309
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
310
+ return value;
311
+ }
312
+ /**
313
+ * The error for a malformed grid.
314
+ *
315
+ * @param address - Where it came from.
316
+ * @param problem - What is wrong.
317
+ * @returns The error.
318
+ */
319
+ function invalid(address, problem) {
320
+ return new IgnifxError(CoreErrorCode.invalidAssetFile, `${address} is not an ${LIGHT_PROBE_FILE_FORMAT} file.`, {
321
+ context: {
322
+ file: address,
323
+ format: LIGHT_PROBE_FILE_FORMAT
324
+ },
325
+ hint: `Fix the file: ${problem}.`
326
+ });
327
+ }
328
+ //#endregion
329
+ export { LightProbeAsset as a, readLightProbeFile as c, writeLightProbeFile as d, LIGHT_PROBE_FORMAT_VERSION as i, readLightProbeGrid as l, LIGHT_PROBE_FILE_EXTENSIONS as n, createLightProbeAsset as o, LIGHT_PROBE_FILE_FORMAT as r, packLightProbeTexels as s, LIGHT_PROBE_ASSET_TYPE as t, sampleLightProbes as u };
330
+
331
+ //# sourceMappingURL=light-probe-asset-B60_X-yN.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"light-probe-asset-B60_X-yN.js","names":[],"sources":["../src/render/light-probe-asset.ts"],"sourcesContent":["import { CoreErrorCode } from \"../errors/error-codes.js\";\nimport { IgnifxError } from \"../errors/ignifx-error.js\";\nimport type { App } from \"../app/types.js\";\nimport type { AssetHandle } from \"../assets/types.js\";\nimport type { Vec3Like } from \"../math/types.js\";\n\n/**\n * Light probes (`docs/plan/2026-11-gi-phase-2-execution-plan.md`, step B2): a regular grid of baked\n * irradiance samples that a `LightProbeVolume` lights PBR materials with, in place of the scene\n * environment's diffuse light. Everything here is plain data and runs in Node.\n *\n * Each probe stores four RGB coefficients of first-order spherical harmonics, already convolved and\n * scaled the way Babylon Lite's environment harmonics are, so the diffuse light a white surface with\n * normal `n` receives is `c0 + c1·n.y + c2·n.z + c3·n.x` (Lite's `environmentIrradiance`, L1 part).\n */\n\n/**\n * The asset type light-probe grids are registered under.\n *\n * @public\n */\nexport const LIGHT_PROBE_ASSET_TYPE = \"lightprobes\";\n\n/**\n * The address extensions that select the light-probe loader.\n *\n * @public\n */\nexport const LIGHT_PROBE_FILE_EXTENSIONS: readonly string[] = Object.freeze([\".probes.json\"]);\n\n/**\n * The `format` header every `.probes.json` carries.\n *\n * @public\n */\nexport const LIGHT_PROBE_FILE_FORMAT = \"ignifx-probes\";\n\n/**\n * The `formatVersion` this engine reads and writes.\n *\n * @public\n */\nexport const LIGHT_PROBE_FORMAT_VERSION = 1;\n\n/** Floats per probe: four RGB coefficients. */\nconst FLOATS_PER_PROBE = 12;\n\n/** The largest grid side along X (the texture is four times as wide) and the largest Y·Z product. */\nconst MAX_X = 1024;\nconst MAX_YZ = 4096;\n\n/** The bounds that keep the generated shader constants valid 32-bit floats. */\nconst MAX_COORDINATE = 1e20;\nconst MIN_CELL = 1e-30;\n\n/**\n * A grid of light probes, as a `.probes.json` stores it.\n *\n * @remarks\n * Probe `(i, j, k)` sits at `origin + (i, j, k) · cellSize`. `coefficients` holds 12 floats per probe,\n * probes ordered X fastest, then Y, then Z (`index = i + countX·(j + countY·k)`); each probe's floats\n * are `c0.rgb, c1.rgb, c2.rgb, c3.rgb` in linear RGB (see the module remarks).\n *\n * @public\n */\nexport interface LightProbeData {\n /** The world position of probe `(0, 0, 0)`. */\n readonly origin: Vec3Like;\n /** The distance between neighbouring probes along each axis, in metres. */\n readonly cellSize: Vec3Like;\n /** How many probes along X, Y and Z; each at least 1. */\n readonly counts: { readonly x: number; readonly y: number; readonly z: number };\n /** 12 floats per probe, `countX · countY · countZ · 12` in all. */\n readonly coefficients: readonly number[];\n}\n\n/**\n * A loaded light-probe grid.\n *\n * @example\n * ```ts\n * const probes = await app.assets.loadAsync<LightProbeAsset>(\"lighting/hall.probes.json\");\n * world.createEntity(\"Probes\").addComponent(LightProbeVolume, { probes });\n * ```\n *\n * @beta\n */\nexport class LightProbeAsset {\n /** The type name the asset service registers light-probe grids under. */\n static assetType: string = LIGHT_PROBE_ASSET_TYPE;\n\n /** The grid. */\n readonly data: LightProbeData;\n\n /**\n * Wraps a checked grid. Use the loader or {@link createLightProbeAsset}.\n *\n * @param data - The grid, already checked by `readLightProbeData`.\n *\n * @internal\n */\n constructor(data: LightProbeData) {\n this.data = data;\n }\n}\n\n/**\n * Publishes a grid built in code, such as the result of a bake, as an asset.\n *\n * @param app - The app.\n * @param data - The grid.\n * @returns A handle a `LightProbeVolume` can take.\n * @throws IgnifxError with code `IGX-0709` when the grid is malformed.\n *\n * @beta\n */\nexport function createLightProbeAsset(app: App, data: LightProbeData): AssetHandle<LightProbeAsset> {\n return app.assets.register(new LightProbeAsset(readLightProbeData(data, \"light probe data\")), {\n type: LIGHT_PROBE_ASSET_TYPE,\n });\n}\n\n/**\n * Turns a grid into the JSON a `.probes.json` file holds.\n *\n * @param data - The grid.\n * @returns The file contents, with the format header.\n *\n * @beta\n */\nexport function writeLightProbeFile(data: LightProbeData): Record<string, unknown> {\n return {\n format: LIGHT_PROBE_FILE_FORMAT,\n formatVersion: LIGHT_PROBE_FORMAT_VERSION,\n origin: { x: data.origin.x, y: data.origin.y, z: data.origin.z },\n cellSize: { x: data.cellSize.x, y: data.cellSize.y, z: data.cellSize.z },\n counts: { x: data.counts.x, y: data.counts.y, z: data.counts.z },\n coefficients: [...data.coefficients],\n };\n}\n\n/**\n * Reads a parsed `.probes.json`.\n *\n * @param parsed - The parsed JSON.\n * @param address - The file's address, for the error.\n * @returns The grid.\n * @throws IgnifxError with code `IGX-0709` when the header, a field or the coefficient count is wrong.\n *\n * @internal\n */\nexport function readLightProbeFile(parsed: unknown, address: string): LightProbeData {\n const file = asRecord(parsed);\n if (\n file === null ||\n file[\"format\"] !== LIGHT_PROBE_FILE_FORMAT ||\n file[\"formatVersion\"] !== LIGHT_PROBE_FORMAT_VERSION\n ) {\n throw invalid(address, `it must start with { \"format\": \"${LIGHT_PROBE_FILE_FORMAT}\", \"formatVersion\": 1 }`);\n }\n return readLightProbeData(file, address);\n}\n\n/**\n * Checks a grid's fields.\n *\n * @param value - The candidate grid.\n * @param address - Where it came from, for the error.\n * @returns A grid with copied, checked fields.\n * @throws IgnifxError with code `IGX-0709` on a malformed field.\n *\n * @internal\n */\nexport function readLightProbeData(value: unknown, address: string): LightProbeData {\n const record = asRecord(value);\n if (record === null) {\n throw invalid(address, \"it is not an object\");\n }\n const grid = readLightProbeGrid(record);\n if (typeof grid === \"string\") {\n throw invalid(address, grid);\n }\n const { origin, cellSize, counts } = grid;\n const coefficients = record[\"coefficients\"];\n const expected = counts.x * counts.y * counts.z * FLOATS_PER_PROBE;\n if (\n !Array.isArray(coefficients) ||\n coefficients.length !== expected ||\n !coefficients.every((n) => Number.isFinite(n))\n ) {\n throw invalid(address, `coefficients must be ${String(expected)} finite numbers (12 per probe)`);\n }\n return { origin, cellSize, counts, coefficients: coefficients.map(Number) };\n}\n\n/**\n * The grid part of a light-probe grid: where it is, how far apart the probes are, and how many.\n *\n * @internal\n */\nexport interface LightProbeGrid {\n readonly origin: { x: number; y: number; z: number };\n readonly cellSize: { x: number; y: number; z: number };\n readonly counts: { x: number; y: number; z: number };\n}\n\n/**\n * Checks the grid fields of a candidate grid, for a file and for a bake alike.\n *\n * @remarks\n * Besides the format's count limits, `origin` stays below 1e20 in size and `cellSize` between\n * 1e-30 and 1e20, so the constants the shader is generated with stay valid 32-bit floats.\n *\n * @param record - An object with `origin`, `cellSize` and `counts`.\n * @returns The checked copies, or what is wrong with them.\n *\n * @internal\n */\nexport function readLightProbeGrid(record: Readonly<Record<string, unknown>>): LightProbeGrid | string {\n const origin = readVec3(record[\"origin\"], (n) => Number.isFinite(n) && Math.abs(n) < MAX_COORDINATE);\n const cellSize = readVec3(record[\"cellSize\"], (n) => Number.isFinite(n) && n > MIN_CELL && n < MAX_COORDINATE);\n const counts = readVec3(record[\"counts\"], (n) => Number.isSafeInteger(n) && n >= 1);\n if (origin === null || cellSize === null || counts === null) {\n return \"origin (finite, below 1e20), cellSize (from 1e-30 to 1e20) and counts (whole, at least 1) must each be { x, y, z }\";\n }\n if (counts.x > MAX_X || counts.y * counts.z > MAX_YZ) {\n return `counts.x must be at most ${String(MAX_X)} and counts.y × counts.z at most ${String(MAX_YZ)}`;\n }\n return { origin, cellSize, counts };\n}\n\n/**\n * The diffuse light a white surface receives at a point, read from the grid on the CPU the same way\n * the shader reads it: trilinear between the eight surrounding probes, clamped at the grid's edges.\n *\n * @param data - The grid.\n * @param x - World X.\n * @param y - World Y.\n * @param z - World Z.\n * @param normal - The surface normal, unit length.\n * @returns Linear RGB.\n *\n * @beta\n */\nexport function sampleLightProbes(\n data: LightProbeData,\n x: number,\n y: number,\n z: number,\n normal: Vec3Like,\n): [number, number, number] {\n const { counts } = data;\n const gx = gridCoordinate(x, data.origin.x, data.cellSize.x, counts.x);\n const gy = gridCoordinate(y, data.origin.y, data.cellSize.y, counts.y);\n const gz = gridCoordinate(z, data.origin.z, data.cellSize.z, counts.z);\n const out: [number, number, number] = [0, 0, 0];\n for (let corner = 0; corner < 8; corner += 1) {\n const ix = corner & 1 ? gx.high : gx.low;\n const iy = corner & 2 ? gy.high : gy.low;\n const iz = corner & 4 ? gz.high : gz.low;\n const weight = (corner & 1 ? gx.t : 1 - gx.t) * (corner & 2 ? gy.t : 1 - gy.t) * (corner & 4 ? gz.t : 1 - gz.t);\n const base = (ix + counts.x * (iy + counts.y * iz)) * FLOATS_PER_PROBE;\n for (let channel = 0; channel < 3; channel += 1) {\n const c = (index: number): number => data.coefficients[base + index * 3 + channel] ?? 0;\n out[channel] = (out[channel] ?? 0) + weight * (c(0) + c(1) * normal.y + c(2) * normal.z + c(3) * normal.x);\n }\n }\n return out;\n}\n\n/**\n * Packs a grid into the half-float RGBA texels the shader reads: probe `(i, j, k)`'s coefficient `c`\n * at texel `(i + countX·c, j + countY·k)`.\n *\n * @param data - The grid.\n * @returns The width, height and texels (four half floats each, alpha 1).\n *\n * @internal\n */\nexport function packLightProbeTexels(data: LightProbeData): { width: number; height: number; texels: Uint16Array } {\n const { x: nx, y: ny, z: nz } = data.counts;\n const width = nx * 4;\n const height = ny * nz;\n const texels = new Uint16Array(width * height * 4);\n const one = toHalfFloat(1);\n for (let k = 0; k < nz; k += 1) {\n for (let j = 0; j < ny; j += 1) {\n for (let i = 0; i < nx; i += 1) {\n const base = (i + nx * (j + ny * k)) * FLOATS_PER_PROBE;\n for (let c = 0; c < 4; c += 1) {\n const texel = (i + nx * c + width * (j + ny * k)) * 4;\n for (let channel = 0; channel < 3; channel += 1) {\n texels[texel + channel] = toHalfFloat(data.coefficients[base + c * 3 + channel] ?? 0);\n }\n texels[texel + 3] = one;\n }\n }\n }\n }\n return { width, height, texels };\n}\n\n/**\n * Converts a number to IEEE 754 half precision, rounding to nearest and saturating to ±65504.\n *\n * @param value - The number.\n * @returns The 16 bits.\n *\n * @internal\n */\nexport function toHalfFloat(value: number): number {\n if (Number.isNaN(value)) {\n return 0x7e00;\n }\n const sign = value < 0 || Object.is(value, -0) ? 0x8000 : 0;\n const magnitude = Math.min(Math.abs(value), 65504);\n if (magnitude < 2 ** -24) {\n return sign;\n }\n if (magnitude < 2 ** -14) {\n return sign | Math.round(magnitude / 2 ** -24);\n }\n const exponent = Math.floor(Math.log2(magnitude));\n const mantissa = Math.round((magnitude / 2 ** exponent - 1) * 1024);\n // A mantissa that rounds up to 1024 carries into the exponent.\n return sign | (((exponent + 15) << 10) + mantissa);\n}\n\n/** A grid axis lookup: the two probe indices around a point and the blend between them. */\ninterface AxisCell {\n readonly low: number;\n readonly high: number;\n readonly t: number;\n}\n\n/**\n * Finds the probes around a coordinate on one axis.\n *\n * @param value - The world coordinate.\n * @param origin - The grid origin on this axis.\n * @param cell - The cell size on this axis.\n * @param count - The probe count on this axis.\n * @returns The cell.\n */\nfunction gridCoordinate(value: number, origin: number, cell: number, count: number): AxisCell {\n const g = Math.min(Math.max((value - origin) / cell, 0), count - 1);\n const low = Math.min(Math.floor(g), Math.max(count - 2, 0));\n const high = Math.min(low + 1, count - 1);\n return { low, high, t: g - low };\n}\n\n/**\n * Reads `{ x, y, z }` whose components all pass a check.\n *\n * @param value - The candidate.\n * @param check - The per-component test.\n * @returns A copy, or `null`.\n */\nfunction readVec3(value: unknown, check: (n: number) => boolean): { x: number; y: number; z: number } | null {\n const record = asRecord(value);\n if (record === null) {\n return null;\n }\n const { x, y, z } = record;\n if (typeof x !== \"number\" || typeof y !== \"number\" || typeof z !== \"number\" || ![x, y, z].every(check)) {\n return null;\n }\n return { x, y, z };\n}\n\n/**\n * Narrows a value to a plain record.\n *\n * @param value - The candidate.\n * @returns The record, or `null` for anything else.\n */\nfunction asRecord(value: unknown): Record<string, unknown> | null {\n if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n return null;\n }\n // Boundary narrowing of parsed JSON (coding standards §5.2).\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n return value as Record<string, unknown>;\n}\n\n/**\n * The error for a malformed grid.\n *\n * @param address - Where it came from.\n * @param problem - What is wrong.\n * @returns The error.\n */\nfunction invalid(address: string, problem: string): IgnifxError {\n return new IgnifxError(CoreErrorCode.invalidAssetFile, `${address} is not an ${LIGHT_PROBE_FILE_FORMAT} file.`, {\n context: { file: address, format: LIGHT_PROBE_FILE_FORMAT },\n hint: `Fix the file: ${problem}.`,\n });\n}\n"],"mappings":"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"}
@@ -0,0 +1,284 @@
1
+ import { i as readSceneEnvironment } from "./environment-DZ6WUHbm.js";
2
+ import { a as markMaterialDirty, o as rebuildMaterialPipelines } from "./material-CGk5mAah.js";
3
+ import { s as packLightProbeTexels } from "./light-probe-asset-B60_X-yN.js";
4
+ import { n as deviceOf } from "./render-texture-UqRHRLQy.js";
5
+ import { createRenderTexture2D, enableMaterialPlugins, getPbrUnlit, isPbrMaterial, isPbrSkybox } from "@babylonjs/lite";
6
+ //#region src/lite/gpu/light-probes.ts
7
+ /**
8
+ * Light probes on the GPU (`docs/plan/2026-11-gi-phase-2-execution-plan.md`, step B2). Its own chunk,
9
+ * loaded only once a world has a `LightProbeVolume` (`CONSTITUTION.md` §2.5). Every Lite claim was
10
+ * read from `@babylonjs/lite@1.34.0`.
11
+ *
12
+ * - **Texture.** The grid's coefficients, packed by `packLightProbeTexels`, in an `rgba16float`
13
+ * texture read with `textureLoad` (plugins bind `texture_2d<f32>` only, `index.d.ts` 10607, so no
14
+ * 3D texture).
15
+ * - **Plugin.** Lite declares `environmentIrradiance` with `let` inside the IBL code
16
+ * (`lib/material/pbr/fragments/ibl-fragment.js`), so a plugin cannot replace it. Instead the plugin
17
+ * adds `(probes − environment) · surfaceAlbedo · occlusion` to `color`, recomputing the
18
+ * environment's harmonics from the scene uniforms the IBL code reads. Its point,
19
+ * `CUSTOM_FRAGMENT_BEFORE_FINALCOLORCOMPOSITION`, is injected twice (`AI` before the IBL code, `NI`
20
+ * after it; `lib/material/plugin/plugin-bridge-shared.js` line 13), so a private counter applies it
21
+ * on the second pass only. Its priority runs it before the HDR linear-output plugin saves `color`.
22
+ * - **Grid constants** are written into the WGSL, so a different grid is a different plugin and a
23
+ * material rebuild: grids change rarely. `intensity` is a uniform on the host material's block,
24
+ * so changing it rebuilds nothing.
25
+ */
26
+ /**
27
+ * The name the plugin carries; part of Lite's pipeline cache key.
28
+ *
29
+ * @internal
30
+ */
31
+ const LIGHT_PROBE_PLUGIN_NAME = "ignifx-light-probes";
32
+ /** The uniform field the plugin adds to each host material's block. */
33
+ const INTENSITY_FIELD = "ignifxLpIntensity";
34
+ /**
35
+ * A WGSL float literal.
36
+ *
37
+ * @param value - A finite number.
38
+ * @returns The literal.
39
+ */
40
+ function f(value) {
41
+ return Number.isInteger(value) ? `${String(value)}.0` : String(value);
42
+ }
43
+ /**
44
+ * The plugin's WGSL.
45
+ *
46
+ * @param shape - The grid.
47
+ * @returns The definitions and the composition code.
48
+ *
49
+ * @internal
50
+ */
51
+ function lightProbePluginWgsl(shape) {
52
+ const [nx, ny, nz] = shape.counts;
53
+ const origin = `vec3<f32>(${shape.origin.map(f).join(",")})`;
54
+ const inverse = `vec3<f32>(${shape.cellSize.map((size) => f(1 / size)).join(",")})`;
55
+ const maxCell = `vec3<f32>(${f(nx - 1)},${f(ny - 1)},${f(nz - 1)})`;
56
+ return {
57
+ definitions: `var<private> igxLpPass:i32;fn igxLpTexel(c:vec3<i32>,k:i32)->vec3<f32>{return textureLoad(ignifxLp,vec2<i32>(c.x+${String(nx)}*k,c.y+${String(ny)}*c.z),0).rgb;}fn igxLpAt(c:vec3<i32>,n:vec3<f32>)->vec3<f32>{return igxLpTexel(c,0)+igxLpTexel(c,1)*n.y+igxLpTexel(c,2)*n.z+igxLpTexel(c,3)*n.x;}fn igxLpSample(p:vec3<f32>,n:vec3<f32>)->vec3<f32>{let m=${maxCell};let g=clamp((p-${origin})*${inverse},vec3<f32>(0.0),m);let lo=min(floor(g),max(m-1.0,vec3<f32>(0.0)));let t=g-lo;let hi=min(lo+1.0,m);var r=vec3<f32>(0.0);for(var i=0;i<8;i++){let s=vec3<i32>(i&1,(i>>1u)&1,(i>>2u)&1)==vec3<i32>(1);let w=select(1.0-t,t,s);r+=igxLpAt(vec3<i32>(select(lo,hi,s)),n)*(w.x*w.y*w.z);}return max(r,vec3<f32>(0.0));}`,
58
+ composition: `igxLpPass=igxLpPass+1;if(igxLpPass==2){let igxC=cos(scene.envRotationY);let igxS=sin(scene.envRotationY);let igxN=vec3<f32>(N.x*igxC+N.z*igxS,N.y,-N.x*igxS+N.z*igxC);let igxEnv=(scene.vSphericalL00.rgb+scene.vSphericalL1_1.rgb*igxN.y+scene.vSphericalL10.rgb*igxN.z+scene.vSphericalL11.rgb*igxN.x+scene.vSphericalL2_2.rgb*(igxN.y*igxN.x)+scene.vSphericalL2_1.rgb*(igxN.y*igxN.z)+scene.vSphericalL20.rgb*(3.0*igxN.z*igxN.z-1.0)+scene.vSphericalL21.rgb*(igxN.z*igxN.x)+scene.vSphericalL22.rgb*(igxN.x*igxN.x-igxN.y*igxN.y))*material.environmentIntensity;color+=(igxLpSample(input.worldPos,N)*material.${INTENSITY_FIELD}-igxEnv)*surfaceAlbedo*occlusion;}`
59
+ };
60
+ }
61
+ /**
62
+ * Installs Lite's material-plugin bridges, which the plugin needs, unless the project already did.
63
+ *
64
+ * @remarks
65
+ * Idempotent (`lib/material/plugin/enable-material-plugins.js` replaces its one scene hook). The
66
+ * HDR path calls it before `registerScene` (`./hdr-output.ts`); here it runs after, which works for
67
+ * PBR because the bridge assigns a material's plugin identity during the rebuild that attaching
68
+ * the plugin queues. `light-probe.browser.test.ts` covers that case with HDR off.
69
+ *
70
+ * @param scene - The registered scene.
71
+ *
72
+ * @internal
73
+ */
74
+ function enableLightProbePlugins(scene) {
75
+ enableMaterialPlugins(scene);
76
+ }
77
+ /**
78
+ * Uploads packed probe texels into a texture.
79
+ *
80
+ * @param engine - The engine.
81
+ * @param width - The texel width.
82
+ * @param height - The texel height.
83
+ * @param texels - Four half floats per texel.
84
+ * @returns The texture, or `null` when the engine has no device.
85
+ *
86
+ * @internal
87
+ */
88
+ function createLightProbeTexture(engine, width, height, texels) {
89
+ const device = deviceOf(engine);
90
+ if (device === null) return null;
91
+ const texture = createRenderTexture2D(engine, width, height, {
92
+ format: "rgba16float",
93
+ minFilter: "nearest",
94
+ magFilter: "nearest"
95
+ });
96
+ device.queue.writeTexture({ texture: texture.texture }, texels, { bytesPerRow: width * 8 }, {
97
+ width,
98
+ height
99
+ });
100
+ return texture;
101
+ }
102
+ /**
103
+ * Builds the plugin for one grid and its texture.
104
+ *
105
+ * @param shape - The grid.
106
+ * @param texture - The packed texture.
107
+ * @param uniforms - The live settings; the plugin reads them on every uniform write.
108
+ * @returns The plugin, shared by every lit PBR material.
109
+ *
110
+ * @internal
111
+ */
112
+ function createLightProbePlugin(shape, texture, uniforms) {
113
+ const wgsl = lightProbePluginWgsl(shape);
114
+ const fragment = {
115
+ CUSTOM_FRAGMENT_DEFINITIONS: wgsl.definitions,
116
+ CUSTOM_FRAGMENT_BEFORE_FINALCOLORCOMPOSITION: wgsl.composition
117
+ };
118
+ return {
119
+ name: LIGHT_PROBE_PLUGIN_NAME,
120
+ priority: -100,
121
+ getSamplers: () => [{
122
+ texture: "ignifxLp",
123
+ sampler: "ignifxLpSampler"
124
+ }],
125
+ getUniforms: () => ({ ubo: [{
126
+ name: INTENSITY_FIELD,
127
+ type: "f32"
128
+ }] }),
129
+ writeUbo: (data, offsets) => {
130
+ const byteOffset = offsets.get(INTENSITY_FIELD);
131
+ if (byteOffset !== void 0) data[byteOffset / 4] = uniforms.intensity;
132
+ },
133
+ bindTextures: (out) => {
134
+ out.push({ texture });
135
+ },
136
+ getCustomCode: (stage) => stage === "fragment" ? fragment : null
137
+ };
138
+ }
139
+ /**
140
+ * Re-uploads the plugin's uniforms on every material that carries it, after
141
+ * {@link LightProbeUniforms} changed.
142
+ *
143
+ * @param scene - The scene.
144
+ * @param plugin - The plugin.
145
+ *
146
+ * @internal
147
+ */
148
+ function refreshLightProbeUniforms(scene, plugin) {
149
+ const meshes = scene.meshes;
150
+ for (let index = 0; index < meshes.length; index += 1) {
151
+ const material = meshes[index]?.material;
152
+ if (material === void 0 || material === null || !isPbrMaterial(material)) continue;
153
+ if (material.plugins?.includes(plugin) === true) markMaterialDirty(material);
154
+ }
155
+ }
156
+ /**
157
+ * Gives every lit PBR material `next` in place of `previous`, rebuilding the ones that changed.
158
+ *
159
+ * @param scene - The registered scene.
160
+ * @param previous - The plugin to take off, or `null`.
161
+ * @param next - The plugin to put on, or `null` to only take `previous` off.
162
+ *
163
+ * @internal
164
+ */
165
+ function swapLightProbePlugin(scene, previous, next) {
166
+ const meshes = scene.meshes;
167
+ for (let index = 0; index < meshes.length; index += 1) {
168
+ const material = meshes[index]?.material;
169
+ if (material === void 0 || material === null || !isPbrMaterial(material)) continue;
170
+ const current = material.plugins ?? [];
171
+ const lit = getPbrUnlit(material) === void 0 && !isPbrSkybox(material);
172
+ const hasPrevious = previous !== null && current.includes(previous);
173
+ const wantsNext = next !== null && lit;
174
+ if (!hasPrevious && (!wantsNext || current.includes(next))) continue;
175
+ const kept = hasPrevious ? current.filter((plugin) => plugin !== previous) : current;
176
+ material.plugins = wantsNext && !kept.includes(next) ? [...kept, next] : kept;
177
+ rebuildMaterialPipelines(scene, material);
178
+ }
179
+ }
180
+ //#endregion
181
+ //#region src/render/gpu/light-probes.ts
182
+ /**
183
+ * The render layer's half of light probes (`docs/plan/2026-11-gi-phase-2-execution-plan.md`, step
184
+ * B2): which volume lights the scene, and keeping its plugin on every lit PBR material. Loaded with
185
+ * `../../lite/gpu/light-probes.ts` as one chunk, only once a world has a `LightProbeVolume`.
186
+ */
187
+ /** Frames a replaced texture outlives its plugin, so no in-flight bind group still names it. */
188
+ const RETIRE_FRAMES = 8;
189
+ /**
190
+ * Creates the runtime.
191
+ *
192
+ * @param engine - The engine.
193
+ * @param scene - The registered render scene.
194
+ * @returns The runtime.
195
+ *
196
+ * @internal
197
+ */
198
+ function createLightProbeRuntime(engine, scene) {
199
+ enableLightProbePlugins(scene);
200
+ let applied = null;
201
+ const retiring = [];
202
+ const apply = (asset, intensity) => {
203
+ const { data } = asset;
204
+ const packed = packLightProbeTexels(data);
205
+ const texture = createLightProbeTexture(engine, packed.width, packed.height, packed.texels);
206
+ if (texture === null) return null;
207
+ const uniforms = { intensity };
208
+ return {
209
+ asset,
210
+ uniforms,
211
+ plugin: createLightProbePlugin({
212
+ origin: [
213
+ data.origin.x,
214
+ data.origin.y,
215
+ data.origin.z
216
+ ],
217
+ cellSize: [
218
+ data.cellSize.x,
219
+ data.cellSize.y,
220
+ data.cellSize.z
221
+ ],
222
+ counts: [
223
+ data.counts.x,
224
+ data.counts.y,
225
+ data.counts.z
226
+ ]
227
+ }, texture, uniforms),
228
+ destroy: () => texture.texture.destroy()
229
+ };
230
+ };
231
+ const replace = (next) => {
232
+ swapLightProbePlugin(scene, applied?.plugin ?? null, next?.plugin ?? null);
233
+ if (applied !== null) retiring.push({
234
+ destroy: applied.destroy,
235
+ frames: RETIRE_FRAMES
236
+ });
237
+ applied = next;
238
+ };
239
+ return {
240
+ get isLighting() {
241
+ return applied !== null;
242
+ },
243
+ update(volumes) {
244
+ for (let index = retiring.length - 1; index >= 0; index -= 1) {
245
+ const entry = retiring[index];
246
+ if (entry !== void 0 && --entry.frames <= 0) {
247
+ entry.destroy();
248
+ retiring.splice(index, 1);
249
+ }
250
+ }
251
+ let winner = null;
252
+ let asset = null;
253
+ if (readSceneEnvironment(scene) !== null) for (const volume of volumes) {
254
+ const loaded = volume.isEnabledInHierarchy ? volume.loadedProbes() : null;
255
+ if (loaded !== null) {
256
+ winner = volume;
257
+ asset = loaded;
258
+ }
259
+ }
260
+ if (winner === null || asset === null) {
261
+ if (applied !== null) replace(null);
262
+ return;
263
+ }
264
+ if (applied === null || applied.asset !== asset) {
265
+ replace(apply(asset, winner.intensity));
266
+ return;
267
+ }
268
+ if (applied.uniforms.intensity !== winner.intensity) {
269
+ applied.uniforms.intensity = winner.intensity;
270
+ refreshLightProbeUniforms(scene, applied.plugin);
271
+ }
272
+ swapLightProbePlugin(scene, null, applied.plugin);
273
+ },
274
+ dispose() {
275
+ replace(null);
276
+ for (const entry of retiring) entry.destroy();
277
+ retiring.length = 0;
278
+ }
279
+ };
280
+ }
281
+ //#endregion
282
+ export { createLightProbeRuntime };
283
+
284
+ //# sourceMappingURL=light-probes-DkYN89Qw.js.map