@ignifx/core 0.4.0 → 0.5.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.
@@ -1,4 +1,277 @@
1
- import { n as EPSILON, o as clamp01, u as lerp } from "./math-utils-BcDnL-gi.js";
1
+ //#region src/math/math-utils.ts
2
+ /**
3
+ * Scalar helpers shared by the vector, quaternion and matrix types and by game code.
4
+ *
5
+ * Angles are **degrees** in every public API unless the name ends in `Rad`/`Radians`
6
+ * (coding standards §5.1, ADR-0011). Every function here is a pure scalar function: none of them
7
+ * allocate, so they are safe in per-frame code (coding standards §7).
8
+ */
9
+ /**
10
+ * The default tolerance for approximate float comparisons. Chosen for single-precision positions in
11
+ * metres: `Float32Array` round-tripping loses roughly 1e-7 of relative precision, so 1e-6 is the
12
+ * smallest value that does not report false differences on data that has been through the GPU.
13
+ *
14
+ * @public
15
+ */
16
+ const EPSILON = 1e-6;
17
+ /**
18
+ * Multiplier that converts degrees to radians.
19
+ *
20
+ * @public
21
+ */
22
+ const DEG_TO_RAD = Math.PI / 180;
23
+ /**
24
+ * Multiplier that converts radians to degrees.
25
+ *
26
+ * @public
27
+ */
28
+ const RAD_TO_DEG = 180 / Math.PI;
29
+ /**
30
+ * Converts an angle from degrees to radians.
31
+ *
32
+ * @param degrees - The angle in degrees.
33
+ * @returns The same angle in radians.
34
+ *
35
+ * @public
36
+ */
37
+ function degToRad(degrees) {
38
+ return degrees * DEG_TO_RAD;
39
+ }
40
+ /**
41
+ * Converts an angle from radians to degrees.
42
+ *
43
+ * @param radians - The angle in radians.
44
+ * @returns The same angle in degrees.
45
+ *
46
+ * @public
47
+ */
48
+ function radToDeg(radians) {
49
+ return radians * RAD_TO_DEG;
50
+ }
51
+ /**
52
+ * Constrains a value to an inclusive range.
53
+ *
54
+ * @param value - The value to constrain.
55
+ * @param min - The lower bound.
56
+ * @param max - The upper bound.
57
+ * @returns `min` when `value` is smaller, `max` when it is larger, otherwise `value` unchanged.
58
+ * `NaN` propagates.
59
+ *
60
+ * @example
61
+ * ```ts
62
+ * clamp(12, 0, 10); // 10
63
+ * ```
64
+ *
65
+ * @public
66
+ */
67
+ function clamp(value, min, max) {
68
+ if (value < min) return min;
69
+ if (value > max) return max;
70
+ return value;
71
+ }
72
+ /**
73
+ * Constrains a value to the 0–1 range.
74
+ *
75
+ * @param value - The value to constrain.
76
+ * @returns The value clamped into `[0, 1]`.
77
+ *
78
+ * @public
79
+ */
80
+ function clamp01(value) {
81
+ return clamp(value, 0, 1);
82
+ }
83
+ /**
84
+ * Linearly interpolates between two values. The interpolant is **not** clamped, so values outside
85
+ * `[0, 1]` extrapolate; wrap `t` in {@link clamp01} when that is not wanted.
86
+ *
87
+ * @param a - The value returned at `t === 0`.
88
+ * @param b - The value returned at `t === 1`.
89
+ * @param t - The interpolant.
90
+ * @returns The interpolated value.
91
+ *
92
+ * @example
93
+ * ```ts
94
+ * lerp(0, 10, 0.25); // 2.5
95
+ * ```
96
+ *
97
+ * @public
98
+ */
99
+ function lerp(a, b, t) {
100
+ return a + (b - a) * t;
101
+ }
102
+ /**
103
+ * The inverse of {@link lerp}: finds the interpolant that maps `a`–`b` onto `value`.
104
+ *
105
+ * @param a - The value that maps to 0.
106
+ * @param b - The value that maps to 1.
107
+ * @param value - The value to locate.
108
+ * @returns The interpolant, clamped into `[0, 1]`. Returns 0 when `a` and `b` are equal.
109
+ *
110
+ * @public
111
+ */
112
+ function inverseLerp(a, b, value) {
113
+ if (a === b) return 0;
114
+ return clamp01((value - a) / (b - a));
115
+ }
116
+ /**
117
+ * Smoothly interpolates between two edges with a Hermite curve (the GLSL `smoothstep`), easing in
118
+ * and out instead of the straight ramp of {@link lerp}.
119
+ *
120
+ * @param edge0 - The value below which the result is 0.
121
+ * @param edge1 - The value above which the result is 1.
122
+ * @param x - The value to map.
123
+ * @returns A value in `[0, 1]`. Degenerate edges (`edge0 === edge1`) step from 0 to 1 at the edge.
124
+ *
125
+ * @example
126
+ * ```ts
127
+ * smoothStep(0, 1, 0.5); // 0.5, but with zero slope at 0 and 1
128
+ * ```
129
+ *
130
+ * @public
131
+ */
132
+ function smoothStep(edge0, edge1, x) {
133
+ if (edge0 === edge1) return x < edge0 ? 0 : 1;
134
+ const t = clamp01((x - edge0) / (edge1 - edge0));
135
+ return t * t * (3 - 2 * t);
136
+ }
137
+ /**
138
+ * Moves a value towards a target without overshooting it.
139
+ *
140
+ * @param current - The value to move.
141
+ * @param target - The value to move towards.
142
+ * @param maxDelta - The largest step allowed this call; negative values move away from the target.
143
+ * @returns The stepped value, exactly `target` once the remaining distance fits in `maxDelta`.
144
+ *
145
+ * @example
146
+ * ```ts
147
+ * // frame-rate independent approach at 2 units per second
148
+ * health = moveTowards(health, 100, 2 * time.deltaTime);
149
+ * ```
150
+ *
151
+ * @public
152
+ */
153
+ function moveTowards(current, target, maxDelta) {
154
+ const delta = target - current;
155
+ if (Math.abs(delta) <= maxDelta) return target;
156
+ return current + (delta < 0 ? -maxDelta : maxDelta);
157
+ }
158
+ /**
159
+ * Wraps a value into `[0, length)`, the way a looping animation time behaves. Unlike `%` the result
160
+ * is never negative.
161
+ *
162
+ * @param t - The value to wrap.
163
+ * @param length - The positive period to wrap into.
164
+ * @returns The wrapped value, clamped into `[0, length]` so float error cannot escape the range.
165
+ *
166
+ * @example
167
+ * ```ts
168
+ * repeat(-1, 4); // 3
169
+ * ```
170
+ *
171
+ * @public
172
+ */
173
+ function repeat(t, length) {
174
+ return clamp(t - Math.floor(t / length) * length, 0, length);
175
+ }
176
+ /**
177
+ * Bounces a value back and forth between 0 and `length`, the way a ping-pong animation behaves.
178
+ *
179
+ * @param t - The value to fold.
180
+ * @param length - The positive half-period to fold into.
181
+ * @returns A value in `[0, length]` that rises then falls as `t` increases.
182
+ *
183
+ * @example
184
+ * ```ts
185
+ * pingPong(5, 4); // 3
186
+ * ```
187
+ *
188
+ * @public
189
+ */
190
+ function pingPong(t, length) {
191
+ return length - Math.abs(repeat(t, length * 2) - length);
192
+ }
193
+ /**
194
+ * Compares two numbers with an absolute tolerance. Use this instead of `===` on anything that has
195
+ * been through a matrix, a quaternion or a `Float32Array`.
196
+ *
197
+ * @param a - The first value.
198
+ * @param b - The second value.
199
+ * @param epsilon - The largest difference still considered equal. Defaults to {@link EPSILON}.
200
+ * @returns `true` when the values differ by no more than `epsilon`. `NaN` is never approximately
201
+ * equal to anything, including itself.
202
+ *
203
+ * @public
204
+ */
205
+ function approximately(a, b, epsilon = EPSILON) {
206
+ return Math.abs(a - b) <= epsilon;
207
+ }
208
+ /**
209
+ * The sign of a value, with zero treated as positive (matching Unity's `Mathf.Sign`, and unlike
210
+ * `Math.sign`, which returns 0 and `-0`).
211
+ *
212
+ * @param value - The value to inspect.
213
+ * @returns `-1` for negative values, `1` for positive values and for both `0` and `-0`, and `NaN`
214
+ * for `NaN`.
215
+ *
216
+ * @public
217
+ */
218
+ function sign(value) {
219
+ if (Number.isNaN(value)) return NaN;
220
+ return value < 0 ? -1 : 1;
221
+ }
222
+ /**
223
+ * Wraps an angle in degrees into `[-180, 180)`, the range rotations are most readable in.
224
+ *
225
+ * @param degrees - The angle to wrap.
226
+ * @returns The equivalent angle in `[-180, 180)`; exactly `180` wraps to `-180`.
227
+ *
228
+ * @example
229
+ * ```ts
230
+ * wrapAngleDegrees(370); // 10
231
+ * wrapAngleDegrees(-190); // 170
232
+ * ```
233
+ *
234
+ * @public
235
+ */
236
+ function wrapAngleDegrees(degrees) {
237
+ return repeat(degrees + 180, 360) - 180;
238
+ }
239
+ /**
240
+ * The shortest signed rotation from one angle to another, in degrees.
241
+ *
242
+ * @param fromDegrees - The starting angle.
243
+ * @param toDegrees - The target angle.
244
+ * @returns The signed difference in `[-180, 180)`.
245
+ *
246
+ * @example
247
+ * ```ts
248
+ * deltaAngleDegrees(350, 10); // 20, not -340
249
+ * ```
250
+ *
251
+ * @public
252
+ */
253
+ function deltaAngleDegrees(fromDegrees, toDegrees) {
254
+ return wrapAngleDegrees(toDegrees - fromDegrees);
255
+ }
256
+ /**
257
+ * Interpolates between two angles in degrees the short way around the circle.
258
+ *
259
+ * @param fromDegrees - The angle returned at `t === 0`.
260
+ * @param toDegrees - The angle approached at `t === 1`.
261
+ * @param t - The interpolant; not clamped, matching {@link lerp}.
262
+ * @returns The interpolated angle. It is not wrapped, so feeding the result back in is stable.
263
+ *
264
+ * @example
265
+ * ```ts
266
+ * lerpAngleDegrees(350, 10, 0.5); // 360
267
+ * ```
268
+ *
269
+ * @public
270
+ */
271
+ function lerpAngleDegrees(fromDegrees, toDegrees, t) {
272
+ return fromDegrees + deltaAngleDegrees(fromDegrees, toDegrees) * t;
273
+ }
274
+ //#endregion
2
275
  //#region src/math/color.ts
3
276
  /**
4
277
  * Matches `#rrggbb`, `#rrggbbaa`, and the same two without the leading `#`.
@@ -346,6 +619,6 @@ var Color = class Color {
346
619
  }
347
620
  };
348
621
  //#endregion
349
- export { Color as t };
622
+ export { sign as _, approximately as a, degToRad as c, lerp as d, lerpAngleDegrees as f, repeat as g, radToDeg as h, RAD_TO_DEG as i, deltaAngleDegrees as l, pingPong as m, DEG_TO_RAD as n, clamp as o, moveTowards as p, EPSILON as r, clamp01 as s, Color as t, inverseLerp as u, smoothStep as v, wrapAngleDegrees as y };
350
623
 
351
- //# sourceMappingURL=color-DrR6GFTd.js.map
624
+ //# sourceMappingURL=color-CpvebMIh.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"color-CpvebMIh.js","names":[],"sources":["../src/math/math-utils.ts","../src/math/color.ts"],"sourcesContent":["/**\n * Scalar helpers shared by the vector, quaternion and matrix types and by game code.\n *\n * Angles are **degrees** in every public API unless the name ends in `Rad`/`Radians`\n * (coding standards §5.1, ADR-0011). Every function here is a pure scalar function: none of them\n * allocate, so they are safe in per-frame code (coding standards §7).\n */\n\n/**\n * The default tolerance for approximate float comparisons. Chosen for single-precision positions in\n * metres: `Float32Array` round-tripping loses roughly 1e-7 of relative precision, so 1e-6 is the\n * smallest value that does not report false differences on data that has been through the GPU.\n *\n * @public\n */\nexport const EPSILON: number = 1e-6;\n\n/**\n * Multiplier that converts degrees to radians.\n *\n * @public\n */\nexport const DEG_TO_RAD: number = Math.PI / 180;\n\n/**\n * Multiplier that converts radians to degrees.\n *\n * @public\n */\nexport const RAD_TO_DEG: number = 180 / Math.PI;\n\n/**\n * Converts an angle from degrees to radians.\n *\n * @param degrees - The angle in degrees.\n * @returns The same angle in radians.\n *\n * @public\n */\nexport function degToRad(degrees: number): number {\n return degrees * DEG_TO_RAD;\n}\n\n/**\n * Converts an angle from radians to degrees.\n *\n * @param radians - The angle in radians.\n * @returns The same angle in degrees.\n *\n * @public\n */\nexport function radToDeg(radians: number): number {\n return radians * RAD_TO_DEG;\n}\n\n/**\n * Constrains a value to an inclusive range.\n *\n * @param value - The value to constrain.\n * @param min - The lower bound.\n * @param max - The upper bound.\n * @returns `min` when `value` is smaller, `max` when it is larger, otherwise `value` unchanged.\n * `NaN` propagates.\n *\n * @example\n * ```ts\n * clamp(12, 0, 10); // 10\n * ```\n *\n * @public\n */\nexport function clamp(value: number, min: number, max: number): number {\n if (value < min) {\n return min;\n }\n if (value > max) {\n return max;\n }\n return value;\n}\n\n/**\n * Constrains a value to the 0–1 range.\n *\n * @param value - The value to constrain.\n * @returns The value clamped into `[0, 1]`.\n *\n * @public\n */\nexport function clamp01(value: number): number {\n return clamp(value, 0, 1);\n}\n\n/**\n * Linearly interpolates between two values. The interpolant is **not** clamped, so values outside\n * `[0, 1]` extrapolate; wrap `t` in {@link clamp01} when that is not wanted.\n *\n * @param a - The value returned at `t === 0`.\n * @param b - The value returned at `t === 1`.\n * @param t - The interpolant.\n * @returns The interpolated value.\n *\n * @example\n * ```ts\n * lerp(0, 10, 0.25); // 2.5\n * ```\n *\n * @public\n */\nexport function lerp(a: number, b: number, t: number): number {\n return a + (b - a) * t;\n}\n\n/**\n * The inverse of {@link lerp}: finds the interpolant that maps `a`–`b` onto `value`.\n *\n * @param a - The value that maps to 0.\n * @param b - The value that maps to 1.\n * @param value - The value to locate.\n * @returns The interpolant, clamped into `[0, 1]`. Returns 0 when `a` and `b` are equal.\n *\n * @public\n */\nexport function inverseLerp(a: number, b: number, value: number): number {\n if (a === b) {\n return 0;\n }\n return clamp01((value - a) / (b - a));\n}\n\n/**\n * Smoothly interpolates between two edges with a Hermite curve (the GLSL `smoothstep`), easing in\n * and out instead of the straight ramp of {@link lerp}.\n *\n * @param edge0 - The value below which the result is 0.\n * @param edge1 - The value above which the result is 1.\n * @param x - The value to map.\n * @returns A value in `[0, 1]`. Degenerate edges (`edge0 === edge1`) step from 0 to 1 at the edge.\n *\n * @example\n * ```ts\n * smoothStep(0, 1, 0.5); // 0.5, but with zero slope at 0 and 1\n * ```\n *\n * @public\n */\nexport function smoothStep(edge0: number, edge1: number, x: number): number {\n if (edge0 === edge1) {\n return x < edge0 ? 0 : 1;\n }\n const t = clamp01((x - edge0) / (edge1 - edge0));\n return t * t * (3 - 2 * t);\n}\n\n/**\n * Moves a value towards a target without overshooting it.\n *\n * @param current - The value to move.\n * @param target - The value to move towards.\n * @param maxDelta - The largest step allowed this call; negative values move away from the target.\n * @returns The stepped value, exactly `target` once the remaining distance fits in `maxDelta`.\n *\n * @example\n * ```ts\n * // frame-rate independent approach at 2 units per second\n * health = moveTowards(health, 100, 2 * time.deltaTime);\n * ```\n *\n * @public\n */\nexport function moveTowards(current: number, target: number, maxDelta: number): number {\n const delta = target - current;\n if (Math.abs(delta) <= maxDelta) {\n return target;\n }\n return current + (delta < 0 ? -maxDelta : maxDelta);\n}\n\n/**\n * Wraps a value into `[0, length)`, the way a looping animation time behaves. Unlike `%` the result\n * is never negative.\n *\n * @param t - The value to wrap.\n * @param length - The positive period to wrap into.\n * @returns The wrapped value, clamped into `[0, length]` so float error cannot escape the range.\n *\n * @example\n * ```ts\n * repeat(-1, 4); // 3\n * ```\n *\n * @public\n */\nexport function repeat(t: number, length: number): number {\n return clamp(t - Math.floor(t / length) * length, 0, length);\n}\n\n/**\n * Bounces a value back and forth between 0 and `length`, the way a ping-pong animation behaves.\n *\n * @param t - The value to fold.\n * @param length - The positive half-period to fold into.\n * @returns A value in `[0, length]` that rises then falls as `t` increases.\n *\n * @example\n * ```ts\n * pingPong(5, 4); // 3\n * ```\n *\n * @public\n */\nexport function pingPong(t: number, length: number): number {\n return length - Math.abs(repeat(t, length * 2) - length);\n}\n\n/**\n * Compares two numbers with an absolute tolerance. Use this instead of `===` on anything that has\n * been through a matrix, a quaternion or a `Float32Array`.\n *\n * @param a - The first value.\n * @param b - The second value.\n * @param epsilon - The largest difference still considered equal. Defaults to {@link EPSILON}.\n * @returns `true` when the values differ by no more than `epsilon`. `NaN` is never approximately\n * equal to anything, including itself.\n *\n * @public\n */\nexport function approximately(a: number, b: number, epsilon: number = EPSILON): boolean {\n return Math.abs(a - b) <= epsilon;\n}\n\n/**\n * The sign of a value, with zero treated as positive (matching Unity's `Mathf.Sign`, and unlike\n * `Math.sign`, which returns 0 and `-0`).\n *\n * @param value - The value to inspect.\n * @returns `-1` for negative values, `1` for positive values and for both `0` and `-0`, and `NaN`\n * for `NaN`.\n *\n * @public\n */\nexport function sign(value: number): number {\n if (Number.isNaN(value)) {\n return Number.NaN;\n }\n return value < 0 ? -1 : 1;\n}\n\n/**\n * Wraps an angle in degrees into `[-180, 180)`, the range rotations are most readable in.\n *\n * @param degrees - The angle to wrap.\n * @returns The equivalent angle in `[-180, 180)`; exactly `180` wraps to `-180`.\n *\n * @example\n * ```ts\n * wrapAngleDegrees(370); // 10\n * wrapAngleDegrees(-190); // 170\n * ```\n *\n * @public\n */\nexport function wrapAngleDegrees(degrees: number): number {\n return repeat(degrees + 180, 360) - 180;\n}\n\n/**\n * The shortest signed rotation from one angle to another, in degrees.\n *\n * @param fromDegrees - The starting angle.\n * @param toDegrees - The target angle.\n * @returns The signed difference in `[-180, 180)`.\n *\n * @example\n * ```ts\n * deltaAngleDegrees(350, 10); // 20, not -340\n * ```\n *\n * @public\n */\nexport function deltaAngleDegrees(fromDegrees: number, toDegrees: number): number {\n return wrapAngleDegrees(toDegrees - fromDegrees);\n}\n\n/**\n * Interpolates between two angles in degrees the short way around the circle.\n *\n * @param fromDegrees - The angle returned at `t === 0`.\n * @param toDegrees - The angle approached at `t === 1`.\n * @param t - The interpolant; not clamped, matching {@link lerp}.\n * @returns The interpolated angle. It is not wrapped, so feeding the result back in is stable.\n *\n * @example\n * ```ts\n * lerpAngleDegrees(350, 10, 0.5); // 360\n * ```\n *\n * @public\n */\nexport function lerpAngleDegrees(fromDegrees: number, toDegrees: number, t: number): number {\n return fromDegrees + deltaAngleDegrees(fromDegrees, toDegrees) * t;\n}\n","import { clamp01, EPSILON, lerp } from \"./math-utils.js\";\nimport type { ColorLike } from \"./types.js\";\n\n/**\n * Matches `#rrggbb`, `#rrggbbaa`, and the same two without the leading `#`.\n */\nconst HEX_PATTERN = /^#?(?:[\\da-f]{6}|[\\da-f]{8})$/iu;\n\n/**\n * Formats a 0-255 channel as two lowercase hex digits.\n *\n * @param value - The channel value, already rounded into 0-255.\n * @returns Two hex digits.\n */\nfunction hexByte(value: number): string {\n return value.toString(16).padStart(2, \"0\");\n}\n\n/**\n * An RGBA colour whose components are **linear** and normally in 0-1 (values above 1 are allowed\n * and mean HDR intensity). Lighting maths only works in linear space, which is why this is the\n * space ignifx stores; scene files and hex strings are sRGB, and\n * {@link Color.fromHex}/{@link Color.fromSrgb} are the doors between the two\n * (`docs/architecture/06-serialization-and-scene-format.md` section 3).\n *\n * Every method says which space it works in. The rule of thumb: if it takes or returns a hex string\n * or has `Srgb` in its name, it is sRGB; everything else is linear.\n *\n * @example\n * ```ts\n * const tint = Color.fromHex(\"#ff8800\") ?? new Color(1, 1, 1, 1); // parsed as sRGB, stored linear\n * tint.scaleRgb(2); // twice as bright, same alpha\n * tint.toHex(); // back to sRGB: \"#ffbe00\"\n * ```\n *\n * @public\n */\nexport class Color {\n /** The linear red component. */\n r: number;\n /** The linear green component. */\n g: number;\n /** The linear blue component. */\n b: number;\n /** The alpha component in 0-1. Alpha is always linear, never gamma encoded. */\n a: number;\n\n /**\n * Creates a colour from linear components.\n *\n * @param r - The linear red component. Defaults to 0.\n * @param g - The linear green component. Defaults to 0.\n * @param b - The linear blue component. Defaults to 0.\n * @param a - The alpha component. Defaults to 1 (opaque).\n */\n constructor(r: number = 0, g: number = 0, b: number = 0, a: number = 1) {\n this.r = r;\n this.g = g;\n this.b = b;\n this.a = a;\n }\n\n /**\n * Assigns every component at once, in linear space.\n *\n * @param r - The new linear red component.\n * @param g - The new linear green component.\n * @param b - The new linear blue component.\n * @param a - The new alpha component.\n * @returns This colour.\n */\n set(r: number, g: number, b: number, a: number): this {\n this.r = r;\n this.g = g;\n this.b = b;\n this.a = a;\n return this;\n }\n\n /**\n * Copies every component from another colour.\n *\n * @param c - The colour to read.\n * @returns This colour.\n */\n copyFrom(c: ColorLike): this {\n this.r = c.r;\n this.g = c.g;\n this.b = c.b;\n this.a = c.a;\n return this;\n }\n\n /**\n * Copies this colour into a new one.\n *\n * @returns A new colour. **Allocates.**\n */\n clone(): Color {\n return new Color(this.r, this.g, this.b, this.a);\n }\n\n /**\n * Multiplies this colour by another, component by component including alpha — the usual way a\n * tint is applied.\n *\n * @param c - The colour to multiply by.\n * @returns This colour.\n */\n multiply(c: ColorLike): this {\n this.r *= c.r;\n this.g *= c.g;\n this.b *= c.b;\n this.a *= c.a;\n return this;\n }\n\n /**\n * Scales the linear RGB components, leaving alpha alone. This is what \"brighter\" means: alpha is\n * coverage, not colour.\n *\n * @param factor - The intensity factor.\n * @returns This colour.\n */\n scaleRgb(factor: number): this {\n this.r *= factor;\n this.g *= factor;\n this.b *= factor;\n return this;\n }\n\n /**\n * Moves this colour towards a target, in linear space (which is where blending belongs; lerping\n * sRGB values darkens midpoints).\n *\n * @param target - The colour reached at `t === 1`.\n * @param t - The interpolant; not clamped.\n * @returns This colour.\n */\n lerp(target: ColorLike, t: number): this {\n return Color.lerpToRef(this, target, t, this);\n }\n\n /**\n * Compares this colour with another, component by component, with a tolerance.\n *\n * @param c - The colour to compare against.\n * @param epsilon - The largest per-component difference still considered equal.\n * @returns `true` when every component matches within `epsilon`.\n */\n equalsWithEpsilon(c: ColorLike, epsilon: number = EPSILON): boolean {\n return Color.equalsWithEpsilon(this, c, epsilon);\n }\n\n /**\n * Writes the **linear** components into a `Float32Array`, the form a shader wants. The output\n * comes first to mirror Babylon Lite's `toArray` helpers.\n *\n * @param out - The array to write into.\n * @param offset - The index of the red component. Defaults to 0.\n * @returns `out`.\n */\n toArray(out: Float32Array, offset: number = 0): Float32Array {\n out[offset] = this.r;\n out[offset + 1] = this.g;\n out[offset + 2] = this.b;\n out[offset + 3] = this.a;\n return out;\n }\n\n /**\n * Writes this colour's **sRGB-encoded** components into `out`, for display, pickers and files.\n * Components are clamped into 0-1 by the encoding curve.\n *\n * @param out - The colour to write; may be this colour. Its fields hold sRGB values afterwards,\n * not linear ones.\n * @returns `out`.\n */\n toSrgbToRef<TOut extends Color>(out: TOut): TOut {\n return out.set(Color.linearToSrgb(this.r), Color.linearToSrgb(this.g), Color.linearToSrgb(this.b), this.a);\n }\n\n /**\n * Encodes this colour as an sRGB hex string.\n *\n * @returns `#rrggbb` for an opaque colour, `#rrggbbaa` when alpha is below 1. **Allocates a\n * string.**\n *\n * @example\n * ```ts\n * new Color(1, 1, 1, 1).toHex(); // \"#ffffff\"\n * ```\n */\n toHex(): string {\n const r = hexByte(Math.round(Color.linearToSrgb(this.r) * 255));\n const g = hexByte(Math.round(Color.linearToSrgb(this.g) * 255));\n const b = hexByte(Math.round(Color.linearToSrgb(this.b) * 255));\n const alpha = clamp01(this.a);\n if (alpha >= 1) {\n return `#${r}${g}${b}`;\n }\n return `#${r}${g}${b}${hexByte(Math.round(alpha * 255))}`;\n }\n\n /**\n * Opaque white.\n *\n * @returns A new linear `(1, 1, 1, 1)`. **Allocates.**\n */\n static white(): Color {\n return new Color(1, 1, 1, 1);\n }\n\n /**\n * Opaque black.\n *\n * @returns A new linear `(0, 0, 0, 1)`. **Allocates.**\n */\n static black(): Color {\n return new Color(0, 0, 0, 1);\n }\n\n /**\n * Fully transparent black.\n *\n * @returns A new linear `(0, 0, 0, 0)`. **Allocates.**\n */\n static transparent(): Color {\n return new Color(0, 0, 0, 0);\n }\n\n /**\n * Copies any colour-shaped value into a `Color`.\n *\n * @param c - The linear colour to copy.\n * @returns A new colour. **Allocates.**\n */\n static from(c: ColorLike): Color {\n return new Color(c.r, c.g, c.b, c.a);\n }\n\n /**\n * Converts one **sRGB** channel to linear, using the IEC 61966-2-1 curve Babylon Lite uses\n * (`lib/math/color.js`).\n *\n * @param channel - The sRGB channel value; clamped into 0-1.\n * @returns The linear value.\n */\n static srgbToLinear(channel: number): number {\n const c = clamp01(channel);\n return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);\n }\n\n /**\n * Converts one **linear** channel to sRGB, the inverse of {@link Color.srgbToLinear}.\n *\n * @param channel - The linear channel value; clamped into 0-1, so HDR intensity is lost.\n * @returns The sRGB value.\n */\n static linearToSrgb(channel: number): number {\n const c = clamp01(channel);\n return c <= 0.0031308 ? c * 12.92 : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;\n }\n\n /**\n * Builds a colour from **sRGB** components, converting RGB to linear and taking alpha as-is.\n *\n * @param r - The sRGB red component, 0-1.\n * @param g - The sRGB green component, 0-1.\n * @param b - The sRGB blue component, 0-1.\n * @param a - The alpha component, 0-1. Defaults to 1.\n * @returns A new colour holding linear components. **Allocates.**\n */\n static fromSrgb(r: number, g: number, b: number, a: number = 1): Color {\n return Color.fromSrgbToRef(r, g, b, a, new Color());\n }\n\n /**\n * Writes a colour built from **sRGB** components into `out`.\n *\n * @param r - The sRGB red component, 0-1.\n * @param g - The sRGB green component, 0-1.\n * @param b - The sRGB blue component, 0-1.\n * @param a - The alpha component, 0-1.\n * @param out - The colour to write; holds linear components afterwards.\n * @returns `out`.\n */\n static fromSrgbToRef<TOut extends Color>(r: number, g: number, b: number, a: number, out: TOut): TOut {\n return out.set(Color.srgbToLinear(r), Color.srgbToLinear(g), Color.srgbToLinear(b), a);\n }\n\n /**\n * Parses an **sRGB** hex string into a linear colour.\n *\n * @param hex - `#rrggbb` or `#rrggbbaa`, with or without the leading `#`, in either case.\n * @returns A new colour, or `null` when the string is not a hex colour. Colours arrive from files\n * and user input, so a bad one is expected absence rather than API misuse (coding standards\n * section 5.5): the caller decides whether to substitute a default or raise a load error.\n * **Allocates.**\n *\n * @example\n * ```ts\n * const tint = Color.fromHex(\"#ff8800aa\") ?? Color.white();\n * ```\n */\n static fromHex(hex: string): Color | null {\n const out = new Color();\n return Color.fromHexToRef(hex, out) ? out : null;\n }\n\n /**\n * Parses an **sRGB** hex string into `out` as linear components.\n *\n * @param hex - `#rrggbb` or `#rrggbbaa`, with or without the leading `#`, in either case.\n * @param out - The colour to write; left untouched when parsing fails.\n * @returns `true` when `hex` was a valid hex colour.\n */\n static fromHexToRef(hex: string, out: Color): boolean {\n if (!HEX_PATTERN.test(hex)) {\n return false;\n }\n const body = hex.startsWith(\"#\") ? hex.slice(1) : hex;\n const r = Number.parseInt(body.slice(0, 2), 16) / 255;\n const g = Number.parseInt(body.slice(2, 4), 16) / 255;\n const b = Number.parseInt(body.slice(4, 6), 16) / 255;\n const a = body.length === 8 ? Number.parseInt(body.slice(6, 8), 16) / 255 : 1;\n Color.fromSrgbToRef(r, g, b, a, out);\n return true;\n }\n\n /**\n * Writes the component-wise product `a * b` into `out`, in linear space.\n *\n * @param a - The first colour.\n * @param b - The second colour.\n * @param out - The colour to write; may alias `a` or `b`.\n * @returns `out`.\n */\n static multiplyToRef<TOut extends Color>(a: ColorLike, b: ColorLike, out: TOut): TOut {\n return out.set(a.r * b.r, a.g * b.g, a.b * b.b, a.a * b.a);\n }\n\n /**\n * Writes `c` with its RGB scaled and its alpha untouched into `out`.\n *\n * @param c - The colour to scale.\n * @param factor - The intensity factor.\n * @param out - The colour to write; may alias `c`.\n * @returns `out`.\n */\n static scaleRgbToRef<TOut extends Color>(c: ColorLike, factor: number, out: TOut): TOut {\n return out.set(c.r * factor, c.g * factor, c.b * factor, c.a);\n }\n\n /**\n * Writes the linear-space interpolation of `a` and `b` into `out`.\n *\n * @param a - The colour written at `t === 0`.\n * @param b - The colour written at `t === 1`.\n * @param t - The interpolant; not clamped.\n * @param out - The colour to write; may alias `a` or `b`.\n * @returns `out`.\n */\n static lerpToRef<TOut extends Color>(a: ColorLike, b: ColorLike, t: number, out: TOut): TOut {\n return out.set(lerp(a.r, b.r, t), lerp(a.g, b.g, t), lerp(a.b, b.b, t), lerp(a.a, b.a, t));\n }\n\n /**\n * Compares two colours component by component, with a tolerance.\n *\n * @param a - The first colour.\n * @param b - The second colour.\n * @param epsilon - The largest per-component difference still considered equal.\n * @returns `true` when every component matches within `epsilon`.\n */\n static equalsWithEpsilon(a: ColorLike, b: ColorLike, epsilon: number = EPSILON): boolean {\n return (\n Math.abs(a.r - b.r) <= epsilon &&\n Math.abs(a.g - b.g) <= epsilon &&\n Math.abs(a.b - b.b) <= epsilon &&\n Math.abs(a.a - b.a) <= epsilon\n );\n }\n}\n"],"mappings":"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"}
@@ -1,5 +1,5 @@
1
1
  import { n as assertNever } from "./ignifx-error-R1ma_Lzv.js";
2
- import { s as degToRad } from "./math-utils-BcDnL-gi.js";
2
+ import { c as degToRad, t as Color } from "./color-CpvebMIh.js";
3
3
  import { AcesToneMapping, NeutralToneMapping, StandardToneMapping, loadEnvironment, setEnvironmentBlur, setEnvironmentRotation, setFog, setSceneImageProcessing } from "@babylonjs/lite";
4
4
  //#region src/lite/gpu/environment.ts
5
5
  /**
@@ -130,24 +130,46 @@ function setSceneEnvironmentBlur(scene, blur) {
130
130
  setEnvironmentBlur(scene, blur);
131
131
  }
132
132
  /**
133
- * Sets the colour the scene is cleared to each frame.
133
+ * Sets the colour the scene is cleared to each frame, so that it presents as the sRGB value given.
134
+ *
135
+ * @remarks
136
+ * Lite stores the clear value into the colour target untouched. Tone mapping, image processing and
137
+ * bloom's threshold never apply to it, and Lite's own transmission and solid-skybox paths read it
138
+ * as the colour that should come out (`lib/frame-graph/transmission.js` `executeRenderTaskLinear`,
139
+ * `lib/material/pbr/background-solid-skybox.js`). The default surface format is not an sRGB one,
140
+ * so the sRGB value is written unchanged. Only an `*-srgb` surface view (`rendering.srgb: true`)
141
+ * encodes on write; there the value is decoded first, so that the GPU's encoding gives it back.
142
+ * Every target ignifx renders the scene into uses the surface's format (`./render-path.ts`), so
143
+ * the same rule holds on the offscreen path.
134
144
  *
135
145
  * @param scene - The scene to change.
136
- * @param r - The linear red component, 0 to 1.
137
- * @param g - The linear green component, 0 to 1.
138
- * @param b - The linear blue component, 0 to 1.
146
+ * @param r - The sRGB red component, 0 to 1.
147
+ * @param g - The sRGB green component, 0 to 1.
148
+ * @param b - The sRGB blue component, 0 to 1.
139
149
  * @param a - The alpha component; only meaningful with a premultiplied canvas alpha mode.
140
150
  *
141
151
  * @internal
142
152
  */
143
153
  function setSceneClearColor(scene, r, g, b, a) {
144
154
  const clear = scene.clearColor;
145
- clear.r = r;
146
- clear.g = g;
147
- clear.b = b;
155
+ const decode = isSrgbEncodingFormat(scene.surface.format);
156
+ clear.r = decode ? Color.srgbToLinear(r) : r;
157
+ clear.g = decode ? Color.srgbToLinear(g) : g;
158
+ clear.b = decode ? Color.srgbToLinear(b) : b;
148
159
  clear.a = a;
149
160
  }
150
161
  /**
162
+ * Whether a colour target of this format encodes linear values to sRGB as they are stored.
163
+ *
164
+ * @param format - The target's format. Lite's null engine has none.
165
+ * @returns `true` for an `*-srgb` format.
166
+ *
167
+ * @internal
168
+ */
169
+ function isSrgbEncodingFormat(format) {
170
+ return format?.endsWith("-srgb") === true;
171
+ }
172
+ /**
151
173
  * Configures the scene's fog, or turns it off.
152
174
  *
153
175
  * @param scene - The scene to change.
@@ -221,4 +243,4 @@ function toneMappingCurve(name) {
221
243
  //#endregion
222
244
  export { setSceneClearColor as a, setSceneFog as c, readSceneEnvironment as i, setSceneImageProcessingOptions as l, installSceneEnvironment as n, setSceneEnvironmentBlur as o, loadSceneEnvironment as r, setSceneEnvironmentRotation as s, TONE_MAPPING_NAMES as t };
223
245
 
224
- //# sourceMappingURL=environment-C_JfuAjj.js.map
246
+ //# sourceMappingURL=environment-_EeJXzjk.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"environment-_EeJXzjk.js","names":[],"sources":["../src/lite/gpu/environment.ts"],"sourcesContent":["import {\n AcesToneMapping,\n loadEnvironment,\n loadSkybox,\n NeutralToneMapping,\n setEnvironmentBlur,\n setEnvironmentRotation,\n setFog,\n setSceneImageProcessing,\n StandardToneMapping,\n} from \"@babylonjs/lite\";\nimport { assertNever } from \"../../errors/ignifx-error.js\";\nimport { Color } from \"../../math/color.js\";\nimport { degToRad } from \"../../math/math-utils.js\";\nimport type { EnvironmentTextures, SceneContext, ToneMapping } from \"@babylonjs/lite\";\n\n/**\n * Environment half of the Babylon Lite adapter (`docs/architecture/07-rendering.md` §2.5): image\n * based lighting, the skybox, fog, image processing, and the clear colour.\n *\n * Everything here is `@internal`. Loading uploads cube maps, so the module is GPU-only.\n *\n * ## The BRDF LUT is mandatory (verified against `@babylonjs/lite@1.27.0`)\n *\n * `loadEnvironment(scene, url, options)` (`index.d.ts` 6779) takes a **required** `brdfUrl`: Lite\n * decodes the split-sum BRDF lookup table from a pre-baked RGBD PNG rather than computing it, \"for\n * pixel-perfect parity\" with Babylon.js (`lib/_chunks/env-helpers-*.js`, `loadBrdfImage`, which\n * `fetch`es the URL and decodes it with `createImageBitmap`). ignifx ships that PNG as\n * `tests/fixtures/assets/brdf-lut.png`, decoded from Babylon.js's own\n * `_environmentBRDFBase64Texture` (`packages/dev/core/src/Misc/brdfTextureTools.ts`, Apache-2.0).\n * It is 256×256 RGBA8 and 23 KB.\n *\n * ## Fog\n *\n * `SceneContext.fog` is `FogConfig | null` (`index.d.ts` 5350) with a numeric `mode`; Lite exports\n * no named constants for it, so {@link FOG_MODES} maps ignifx's names onto the numbers.\n *\n * **Fog has to be installed with `setFog`, not by assigning the field.** `scene.fog` is what the PBR\n * group builder reads to decide whether a material's program gets the fog block at all\n * (`lib/material/pbr/pbr-renderable.js` 140-159, `PBR_HAS_FOG`), but the block it compiles reads\n * `scene.vFogInfos.x` out of the scene uniform buffer — and the only writer of those slots is\n * `writeFogUbo`, which nothing registers except `setFog`\n * (`lib/scene/scene-ubo-extras.js`: `setFog` is `scene.fog = config` **plus**\n * `_registerSceneUboContributor(scene, writeFogUbo)`, and `_writePassSceneUBO` runs\n * `scene._sceneUboContributors` and nothing else, `lib/frame-graph/render-task.js` 372-379).\n * Lite says as much in `index.d.ts` 10471: \"importing `setFog` is what pulls the fog UBO writer into\n * the bundle\". Assigning `scene.fog` alone therefore compiles the fog block into every PBR pipeline\n * and leaves `vFogInfos` zeroed, so `vFogInfos.x > 0.0` is never true and the scene renders with no\n * fog at all — the cost with none of the effect.\n *\n * A **fresh** config object goes in on every change, because a render task caches its scene UBO on\n * the identity of `scene.fog` (`s[1] === fog`, `lib/frame-graph/render-task.js` 355-371): mutating\n * the installed object in place leaves the cache key equal and the new density or colour never\n * reaches the GPU. Turning fog off writes mode `0`, which is what the already-compiled fog block\n * reads as \"no fog\"; dropping the field back to `null` would only stop the writer and leave the last\n * fog standing. A scene that never had fog keeps its `null` and pays nothing.\n *\n * ## Image processing\n *\n * `setSceneImageProcessing` is **async** (`index.d.ts` 10917) because tone mapping is baked into\n * the PBR shaders at `registerScene` time; changing it recompiles the affected pipelines\n * (`rebuildScenePbrPipelines`). Setting exposure or contrast alone still goes through the same\n * call. Note that `loadEnvironment` **overwrites** all three (`toneMappingEnabled = true`,\n * `exposure = 0.8`, `contrast = 1.2`) as a side effect of installing an environment, which is why\n * the `Environment` component re-applies its own image processing after every install.\n *\n * ## Swapping the installed environment: `scene._envTextures`\n *\n * Lite 1.27.0 declares **no** public way to replace, clear, or read back a registered scene's\n * environment. `index.d.ts` has no `scene.environmentTexture`, no `unloadEnvironment`, and no\n * setter of any kind; `loadEnvironment` is the only installer and it fetches, decodes, and uploads\n * a fresh cube map every call. What it actually installs is one field —\n * `scene._envTextures = textures` (`lib/_chunks/env-helpers-CRI1i-A3.js` 24, and the same line in\n * `lib/loader-hdr/load-hdr.js` 23, `lib/loader-env/load-dds-env.js` 177 and\n * `lib/loader-gltf/gltf-ext-lights-image-based.js` 65) — and every consumer reads that field:\n *\n * - the PBR group builder, which bakes the cube view and sampler into each material's bind group\n * (`lib/material/pbr/pbr-material.js` 12 → `lib/material/pbr/pbr-renderable.js`);\n * - the scene-uniform packer, for `lodGenerationScale` (`lib/frame-graph/scene-uniforms-pack.js` 21);\n * - the env UBO contributor, for the diffuse spherical harmonics (`lib/scene/scene-ubo-extras.js` 24);\n * - the blur contributor, for `lodGenerationOffset` (`lib/scene/set-environment-blur.js` 8);\n * - the render task's scene-UBO cache key, which is keyed on the **object identity** of the field\n * (`lib/frame-graph/render-task.js` 358), so a new object re-uploads the harmonics by itself.\n *\n * Lite's own device-lost recovery replaces the field exactly this way\n * (`lib/loader-env/environment-recovery.js` 16 and 38), so {@link installSceneEnvironment} writes it\n * too. Bind groups are the one consumer that does *not* re-read it: they hold the `GPUTextureView`,\n * so a swap only reaches the specular reflection once the material groups have been rebuilt, which\n * `rebuildSceneRenderables` does (`lib/scene/scene-rebuild.js`, `rebuildEachGroup`). The\n * `Environment` component therefore reports an install as a topology change and lets the render-sync\n * system fire its one coalesced rebuild. This is the only place in ignifx that touches a Lite field\n * `index.d.ts` does not declare, which is what the adapter boundary exists for\n * (`CONSTITUTION.md` §3.4, ADR-0002); it is pinned by\n * `packages/core/test/lite/render/environment.browser.test.ts`, which fails loudly if the field is\n * renamed.\n */\n\n/**\n * The GPU-resident image-based-lighting textures `loadEnvironment` resolves to, re-exported under an\n * ignifx name (`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 LiteEnvironmentTextures = EnvironmentTextures;\n\n/**\n * ignifx fog mode names mapped to the numbers `FogConfig.mode` uses.\n *\n * @internal\n */\nexport const FOG_MODES = {\n /** No fog. */\n none: 0,\n /** Exponential fog. */\n exp: 1,\n /** Squared-exponential fog. */\n exp2: 2,\n /** Linear fog between `start` and `end`. */\n linear: 3,\n} as const;\n\n/**\n * The union of the fog mode names.\n *\n * @internal\n */\nexport type FogMode = keyof typeof FOG_MODES;\n\n/**\n * The tone-mapping curves `docs/architecture/07-rendering.md` §2.5 exposes.\n *\n * @public\n */\nexport const TONE_MAPPING_NAMES = [\"none\", \"standard\", \"aces\", \"neutral\"] as const;\n\n/**\n * The union of the tone-mapping curve names.\n *\n * @internal\n */\nexport type ToneMappingName = (typeof TONE_MAPPING_NAMES)[number];\n\n/**\n * How an ignifx `Environment` component configures image based lighting.\n *\n * @internal\n */\nexport interface EnvironmentLoadOptions {\n /** The `.env` file holding the prefiltered specular cube map and its spherical harmonics. */\n readonly url: string;\n /** The RGBD PNG BRDF lookup table. Required by Lite. */\n readonly brdfUrl: string;\n /** A `.dds` or `.env` skybox. Omit for a flat background. */\n readonly skyboxUrl?: string;\n /** The skybox cube's size, in metres. Lite defaults to 20. */\n readonly skyboxSize?: number;\n /** Skip the skybox entirely. */\n readonly skipSkybox?: boolean;\n /** Skip the reflective ground plane Lite would otherwise add. */\n readonly skipGround?: boolean;\n /** A texture for that ground plane. */\n readonly groundTextureUrl?: string;\n}\n\n/**\n * Loads an `.env` environment and installs it on a scene.\n *\n * @param scene - The scene to light.\n * @param options - The environment, BRDF, and skybox URLs.\n * @returns The GPU-resident environment textures, for materials that need them explicitly.\n *\n * @example\n * ```ts\n * await loadSceneEnvironment(scene, {\n * url: \"environments/studio.env\",\n * brdfUrl: \"environments/brdf-lut.png\",\n * });\n * ```\n *\n * @internal\n */\nexport function loadSceneEnvironment(\n scene: SceneContext,\n options: EnvironmentLoadOptions,\n): Promise<EnvironmentTextures> {\n const liteOptions: {\n brdfUrl: string;\n skyboxUrl?: string;\n skyboxSize?: number;\n skipSkybox?: boolean;\n skipGround?: boolean;\n groundTextureUrl?: string;\n } = { brdfUrl: options.brdfUrl };\n if (options.skyboxUrl !== undefined) {\n liteOptions.skyboxUrl = options.skyboxUrl;\n }\n if (options.skyboxSize !== undefined) {\n liteOptions.skyboxSize = options.skyboxSize;\n }\n if (options.skipSkybox !== undefined) {\n liteOptions.skipSkybox = options.skipSkybox;\n }\n if (options.skipGround !== undefined) {\n liteOptions.skipGround = options.skipGround;\n }\n if (options.groundTextureUrl !== undefined) {\n liteOptions.groundTextureUrl = options.groundTextureUrl;\n }\n return loadEnvironment(scene, options.url, liteOptions);\n}\n\n/**\n * The scene fields Babylon Lite 1.27.0 writes for image-based lighting but does not declare in\n * `index.d.ts`. Adapter-internal Lite mirror (coding standards §5.1); see the module header for the\n * `lib/` lines that prove each one.\n */\ninterface SceneEnvironmentSlot {\n /** What `loadEnvironment` installed, or `undefined` on a scene that has never had one. */\n _envTextures?: EnvironmentTextures | undefined;\n}\n\n/**\n * Views a scene through its undeclared environment slot.\n *\n * @param scene - The scene.\n * @returns The same object, typed so the slot is reachable.\n */\nfunction environmentSlotOf(scene: SceneContext): SceneEnvironmentSlot {\n // Boundary assertion (coding standards §5.2): `SceneContext` is a plain object literal Lite\n // creates in `lib/scene/scene-core.js`, and `_envTextures` is one of its own fields — it is\n // absent from `index.d.ts` because it is not part of Lite's declared surface, not because it is\n // a different object. See the module header for every `lib/` line that reads or writes it.\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n return scene as SceneContext & SceneEnvironmentSlot;\n}\n\n/**\n * Reports which environment textures a scene is currently lit by.\n *\n * @param scene - The scene to inspect.\n * @returns The installed textures, or `null` when no environment has ever been installed.\n *\n * @internal\n */\nexport function readSceneEnvironment(scene: SceneContext): EnvironmentTextures | null {\n // The underscore is Lite's, not ignifx's: coding standards §5.1 reserves `_field` for exactly\n // this, an adapter-internal mirror of a Lite field, and the module header proves the name.\n // oxlint-disable-next-line no-underscore-dangle\n return environmentSlotOf(scene)._envTextures ?? null;\n}\n\n/**\n * Points a scene at an already-loaded set of environment textures, without loading anything.\n *\n * @remarks\n * This is how an `Environment` component swaps environments at runtime: the textures belong to the\n * `EnvironmentAsset` that loaded them and stay alive as long as its handle is retained, so\n * switching between two loaded assets uploads nothing and frees nothing.\n *\n * The specular reflection follows only after the scene's material groups are rebuilt\n * (`rebuildRenderables` in `../shadow.ts`): a PBR bind group holds the cube map's `GPUTextureView`,\n * not the slot. The diffuse harmonics and the LOD scale follow immediately, because the render\n * task's scene-UBO cache is keyed on this object's identity.\n *\n * @param scene - The scene to light.\n * @param textures - The textures to light it with.\n * @returns `true` when the scene was lit by something else and now is not — the caller owes a\n * renderable rebuild; `false` when these textures were already installed and nothing was written.\n *\n * @example\n * ```ts\n * if (installSceneEnvironment(scene, asset.lite.textures)) {\n * await rebuildRenderables(scene);\n * }\n * ```\n *\n * @internal\n */\nexport function installSceneEnvironment(scene: SceneContext, textures: EnvironmentTextures): boolean {\n const slot = environmentSlotOf(scene);\n // As in `readSceneEnvironment`: an adapter-internal Lite mirror (coding standards §5.1).\n // oxlint-disable-next-line no-underscore-dangle\n if (slot._envTextures === textures) {\n return false;\n }\n // oxlint-disable-next-line no-underscore-dangle\n slot._envTextures = textures;\n return true;\n}\n\n/**\n * Loads a six-face cube-map skybox from a base URL.\n *\n * @param scene - The scene to give a background.\n * @param baseUrl - The URL prefix each face name is appended to.\n * @param extension - The face file extension, such as `\".jpg\"`.\n * @param size - The skybox cube's size, in metres.\n * @returns A promise that resolves when the faces are uploaded.\n *\n * @internal\n */\nexport function loadSceneSkybox(scene: SceneContext, baseUrl: string, extension: string, size?: number): Promise<void> {\n return loadSkybox(scene, baseUrl, extension, size);\n}\n\n/**\n * Rotates the environment around the world Y axis.\n *\n * @param scene - The scene to rotate the environment of.\n * @param degrees - The rotation, in degrees.\n *\n * @internal\n */\nexport function setSceneEnvironmentRotation(scene: SceneContext, degrees: number): void {\n setEnvironmentRotation(scene, degToRad(degrees));\n}\n\n/**\n * Blurs the environment's specular reflection.\n *\n * @param scene - The scene to change.\n * @param blur - The blur amount, 0 to 1.\n *\n * @internal\n */\nexport function setSceneEnvironmentBlur(scene: SceneContext, blur: number): void {\n setEnvironmentBlur(scene, blur);\n}\n\n/**\n * Sets the colour the scene is cleared to each frame, so that it presents as the sRGB value given.\n *\n * @remarks\n * Lite stores the clear value into the colour target untouched. Tone mapping, image processing and\n * bloom's threshold never apply to it, and Lite's own transmission and solid-skybox paths read it\n * as the colour that should come out (`lib/frame-graph/transmission.js` `executeRenderTaskLinear`,\n * `lib/material/pbr/background-solid-skybox.js`). The default surface format is not an sRGB one,\n * so the sRGB value is written unchanged. Only an `*-srgb` surface view (`rendering.srgb: true`)\n * encodes on write; there the value is decoded first, so that the GPU's encoding gives it back.\n * Every target ignifx renders the scene into uses the surface's format (`./render-path.ts`), so\n * the same rule holds on the offscreen path.\n *\n * @param scene - The scene to change.\n * @param r - The sRGB red component, 0 to 1.\n * @param g - The sRGB green component, 0 to 1.\n * @param b - The sRGB blue component, 0 to 1.\n * @param a - The alpha component; only meaningful with a premultiplied canvas alpha mode.\n *\n * @internal\n */\nexport function setSceneClearColor(scene: SceneContext, r: number, g: number, b: number, a: number): void {\n const clear = scene.clearColor;\n const decode = isSrgbEncodingFormat(scene.surface.format);\n clear.r = decode ? Color.srgbToLinear(r) : r;\n clear.g = decode ? Color.srgbToLinear(g) : g;\n clear.b = decode ? Color.srgbToLinear(b) : b;\n clear.a = a;\n}\n\n/**\n * Whether a colour target of this format encodes linear values to sRGB as they are stored.\n *\n * @param format - The target's format. Lite's null engine has none.\n * @returns `true` for an `*-srgb` format.\n *\n * @internal\n */\nexport function isSrgbEncodingFormat(format: string | undefined): boolean {\n return format?.endsWith(\"-srgb\") === true;\n}\n\n/**\n * Configures the scene's fog, or turns it off.\n *\n * @param scene - The scene to change.\n * @param mode - The fog falloff, or `\"none\"` to disable it.\n * @param r - The sRGB red component of the fog colour; Lite's fog block decodes it itself.\n * @param g - The sRGB green component.\n * @param b - The sRGB blue component.\n * @param density - The density, for the exponential modes.\n * @param start - Where linear fog begins, in metres.\n * @param end - Where linear fog reaches full strength, in metres.\n *\n * @internal\n */\nexport function setSceneFog(\n scene: SceneContext,\n mode: FogMode,\n r: number,\n g: number,\n b: number,\n density: number,\n start: number,\n end: number,\n): void {\n if (mode === \"none\" && scene.fog === null) {\n // A scene that never had fog pays nothing: no contributor, no fog block in any PBR pipeline.\n return;\n }\n setFog(scene, { mode: FOG_MODES[mode], density, start, end, color: [r, g, b] });\n}\n\n/**\n * Sets exposure, contrast, and the tone-mapping curve.\n *\n * @remarks\n * Asynchronous by nature: tone mapping is compiled into the PBR shaders, so changing it after\n * `registerScene` recompiles the scene's PBR pipelines. Exposure and contrast alone are uniform\n * values, but Lite routes them through the same call.\n *\n * @param scene - The scene to change.\n * @param exposure - The exposure multiplier.\n * @param contrast - The contrast multiplier.\n * @param toneMapping - The curve, or `\"none\"` to leave the colour untouched.\n * @returns A promise that resolves when any affected pipeline has been rebuilt.\n *\n * @internal\n */\nexport function setSceneImageProcessingOptions(\n scene: SceneContext,\n exposure: number,\n contrast: number,\n toneMapping: ToneMappingName,\n): Promise<void> {\n if (toneMapping === \"none\") {\n return setSceneImageProcessing(scene, { exposure, contrast, toneMappingEnabled: false });\n }\n return setSceneImageProcessing(scene, {\n exposure,\n contrast,\n toneMappingEnabled: true,\n toneMapping: toneMappingCurve(toneMapping),\n });\n}\n\n/**\n * Maps an ignifx tone-mapping name onto the Lite curve object.\n *\n * @param name - The curve name; `\"none\"` is handled by the caller.\n * @returns The Lite curve.\n */\nfunction toneMappingCurve(name: Exclude<ToneMappingName, \"none\">): ToneMapping {\n switch (name) {\n case \"standard\":\n return StandardToneMapping;\n case \"aces\":\n return AcesToneMapping;\n case \"neutral\":\n return NeutralToneMapping;\n default:\n return assertNever(name, \"tone mapping\");\n }\n}\n"],"mappings":";;;;;;;;;AAiHA,MAAa,YAAY;;CAEvB,MAAM;;CAEN,KAAK;;CAEL,MAAM;;CAEN,QAAQ;AACV;;;;;;AAcA,MAAa,qBAAqB;CAAC;CAAQ;CAAY;CAAQ;AAAS;;;;;;;;;;;;;;;;;;AAgDxE,SAAgB,qBACd,OACA,SAC8B;CAC9B,MAAM,cAOF,EAAE,SAAS,QAAQ,QAAQ;CAC/B,IAAI,QAAQ,cAAc,KAAA,GACxB,YAAY,YAAY,QAAQ;CAElC,IAAI,QAAQ,eAAe,KAAA,GACzB,YAAY,aAAa,QAAQ;CAEnC,IAAI,QAAQ,eAAe,KAAA,GACzB,YAAY,aAAa,QAAQ;CAEnC,IAAI,QAAQ,eAAe,KAAA,GACzB,YAAY,aAAa,QAAQ;CAEnC,IAAI,QAAQ,qBAAqB,KAAA,GAC/B,YAAY,mBAAmB,QAAQ;CAEzC,OAAO,gBAAgB,OAAO,QAAQ,KAAK,WAAW;AACxD;;;;;;;AAkBA,SAAS,kBAAkB,OAA2C;CAMpE,OAAO;AACT;;;;;;;;;AAUA,SAAgB,qBAAqB,OAAiD;CAIpF,OAAO,kBAAkB,KAAK,CAAC,CAAC,gBAAgB;AAClD;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,wBAAwB,OAAqB,UAAwC;CACnG,MAAM,OAAO,kBAAkB,KAAK;CAGpC,IAAI,KAAK,iBAAiB,UACxB,OAAO;CAGT,KAAK,eAAe;CACpB,OAAO;AACT;;;;;;;;;AAyBA,SAAgB,4BAA4B,OAAqB,SAAuB;CACtF,uBAAuB,OAAO,SAAS,OAAO,CAAC;AACjD;;;;;;;;;AAUA,SAAgB,wBAAwB,OAAqB,MAAoB;CAC/E,mBAAmB,OAAO,IAAI;AAChC;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,mBAAmB,OAAqB,GAAW,GAAW,GAAW,GAAiB;CACxG,MAAM,QAAQ,MAAM;CACpB,MAAM,SAAS,qBAAqB,MAAM,QAAQ,MAAM;CACxD,MAAM,IAAI,SAAS,MAAM,aAAa,CAAC,IAAI;CAC3C,MAAM,IAAI,SAAS,MAAM,aAAa,CAAC,IAAI;CAC3C,MAAM,IAAI,SAAS,MAAM,aAAa,CAAC,IAAI;CAC3C,MAAM,IAAI;AACZ;;;;;;;;;AAUA,SAAgB,qBAAqB,QAAqC;CACxE,OAAO,QAAQ,SAAS,OAAO,MAAM;AACvC;;;;;;;;;;;;;;;AAgBA,SAAgB,YACd,OACA,MACA,GACA,GACA,GACA,SACA,OACA,KACM;CACN,IAAI,SAAS,UAAU,MAAM,QAAQ,MAEnC;CAEF,OAAO,OAAO;EAAE,MAAM,UAAU;EAAO;EAAS;EAAO;EAAK,OAAO;GAAC;GAAG;GAAG;EAAC;CAAE,CAAC;AAChF;;;;;;;;;;;;;;;;;AAkBA,SAAgB,+BACd,OACA,UACA,UACA,aACe;CACf,IAAI,gBAAgB,QAClB,OAAO,wBAAwB,OAAO;EAAE;EAAU;EAAU,oBAAoB;CAAM,CAAC;CAEzF,OAAO,wBAAwB,OAAO;EACpC;EACA;EACA,oBAAoB;EACpB,aAAa,iBAAiB,WAAW;CAC3C,CAAC;AACH;;;;;;;AAQA,SAAS,iBAAiB,MAAqD;CAC7E,QAAQ,MAAR;EACE,KAAK,YACH,OAAO;EACT,KAAK,QACH,OAAO;EACT,KAAK,WACH,OAAO;EACT,SACE,OAAO,YAAY,MAAM,cAAc;CAC3C;AACF"}
package/dist/index.d.ts CHANGED
@@ -8222,7 +8222,7 @@ declare class RendererImpl implements Renderer {
8222
8222
  */
8223
8223
  attachHandles(engine: LiteEngine, scene: LiteScene, presenter?: ScenePresenter | null): void;
8224
8224
  /**
8225
- * Writes an sRGB colour onto the render scene's clear colour, decoded to linear.
8225
+ * Writes an sRGB colour onto the render scene's clear colour, so it presents as authored.
8226
8226
  *
8227
8227
  * @remarks
8228
8228
  * The one place `scene.clearColor` is written, so the precedence
@@ -8239,8 +8239,11 @@ declare class RendererImpl implements Renderer {
8239
8239
  * ignifx default is opaque black (`src/render/rendering-settings.ts`), so Lite's grey is only
8240
8240
  * ever seen by code that bypasses `createApp`.
8241
8241
  *
8242
- * Colours are stored in sRGB in every settings section and every component field, and Lite's
8243
- * `scene.clearColor` is linear, so each component is decoded on the way through.
8242
+ * Colours are stored in sRGB in every settings section and every component field, and the clear
8243
+ * reaches the swapchain without tone mapping or image processing, so an sRGB `0.5` presents as
8244
+ * byte `128`. The value is written unchanged on the default surface and decoded only for an
8245
+ * `*-srgb` surface view (`rendering.srgb: true`), which encodes it again on write
8246
+ * (`setSceneClearColor`).
8244
8247
  *
8245
8248
  * @param value - The sRGB colour, `0` to `1` per channel.
8246
8249
  *
@@ -14877,7 +14880,7 @@ interface EnvironmentAssetLiteHandles {
14877
14880
  * @example
14878
14881
  * ```ts
14879
14882
  * const studio = await app.assets.loadAsync<EnvironmentAsset>("environments/studio.env");
14880
- * world.createEntity("Env").addComponent(Environment, { environment: studio.retain() });
14883
+ * world.createEntity("Env").addComponent(Environment, { environment: studio });
14881
14884
  * ```
14882
14885
  *
14883
14886
  * @public
@@ -15091,17 +15094,18 @@ interface ImageProcessingSettings {
15091
15094
  * ```ts
15092
15095
  * const studio = await app.assets.loadAsync<EnvironmentAsset>("environments/studio.env");
15093
15096
  * const env = world.createEntity("Environment").addComponent(Environment, {
15094
- * environment: studio.retain(),
15097
+ * environment: studio,
15095
15098
  * imageProcessing: { exposure: 1.2, contrast: 1, toneMapping: "aces" },
15096
15099
  * });
15097
15100
  * ```
15098
15101
  *
15099
15102
  * @example
15100
- * Switching environments at runtime. Both handles stay retained, so switching back costs nothing.
15103
+ * Switching environments at runtime. The field takes no reference of its own: both handles stay
15104
+ * loaded until you release them, so switching back costs nothing.
15101
15105
  *
15102
15106
  * ```ts
15103
15107
  * const night = await app.assets.loadAsync<EnvironmentAsset>("environments/night.env");
15104
- * env.environment = night.retain();
15108
+ * env.environment = night;
15105
15109
  * ```
15106
15110
  *
15107
15111
  * @public
@@ -15394,6 +15398,9 @@ interface LightShadowSettings {
15394
15398
  * local `+Z`, a point light sits at its origin, and a hemispheric light's sky direction is its local
15395
15399
  * `+Y`.
15396
15400
  *
15401
+ * A disabled light, or one on an inactive entity, contributes nothing: its intensity reaches Lite
15402
+ * as `0` and its shadow generator is released. Enabling it again restores both on the next frame.
15403
+ *
15397
15404
  * @example
15398
15405
  * ```ts
15399
15406
  * const sun = world.createEntity("Sun");
@@ -15435,7 +15442,7 @@ export declare class Light extends Component implements ComponentHooks {
15435
15442
  };
15436
15443
  /**
15437
15444
  * Whether this light currently casts shadows — which needs the `shadows` rendering feature, a
15438
- * light kind Lite can shadow, and `shadows.enabled`.
15445
+ * light kind Lite can shadow, `shadows.enabled`, and the light enabled in the hierarchy.
15439
15446
  *
15440
15447
  * @returns `true` when a shadow generator is attached.
15441
15448
  */
@@ -15446,7 +15453,8 @@ export declare class Light extends Component implements ComponentHooks {
15446
15453
  onDetach(): void;
15447
15454
  /**
15448
15455
  * Writes every field that changed onto the Lite light, keeps the lights uniform buffer honest for
15449
- * a moving parent, and re-fits a shadow frustum that follows one. The `PreRender` system calls it.
15456
+ * a moving parent, and re-fits a shadow frustum that follows one. The `PreRender` system calls it
15457
+ * for every light, enabled or not, because a disabled light is dimmed to `0` rather than skipped.
15450
15458
  *
15451
15459
  * @param renderer - The rendering service, for the scene and the feature flags.
15452
15460
  * @returns `true` when the call changed the scene's light topology, which the system coalesces
@@ -16080,9 +16088,11 @@ interface MeshAssetLiteHandles {
16080
16088
  *
16081
16089
  * @example
16082
16090
  * ```ts
16083
- * using box = MeshAsset.box(app, { size: 2 });
16091
+ * const box = MeshAsset.box(app, { size: 2 }); // one reference, owned by this code
16084
16092
  * const cube = app.world.createEntity("Cube");
16085
- * cube.addComponent(MeshRenderer, { mesh: box.retain() });
16093
+ * cube.addComponent(MeshRenderer, { mesh: box }); // the field takes no reference
16094
+ * // Once nothing draws the box any more:
16095
+ * box.release();
16086
16096
  * ```
16087
16097
  *
16088
16098
  * @public
@@ -16348,9 +16358,9 @@ export declare class MeshAsset {
16348
16358
  *
16349
16359
  * @example
16350
16360
  * ```ts
16351
- * using box = MeshAsset.box(app, { size: 1 });
16361
+ * const box = MeshAsset.box(app, { size: 1 }); // release it once nothing draws it
16352
16362
  * const cube = world.createEntity("Cube");
16353
- * cube.addComponent(MeshRenderer, { mesh: box.retain(), castShadows: true });
16363
+ * cube.addComponent(MeshRenderer, { mesh: box, castShadows: true });
16354
16364
  * ```
16355
16365
  *
16356
16366
  * @public
@@ -16808,9 +16818,9 @@ interface InstanceRange {
16808
16818
  *
16809
16819
  * @example
16810
16820
  * ```ts
16811
- * using box = MeshAsset.box(app, { size: 0.5 });
16821
+ * const box = MeshAsset.box(app, { size: 0.5 }); // release it once nothing draws it
16812
16822
  * const field = world.createEntity("Asteroids");
16813
- * const renderer = field.addComponent(InstancedMeshRenderer, { mesh: box.retain(), capacity: 20_000 });
16823
+ * const renderer = field.addComponent(InstancedMeshRenderer, { mesh: box, capacity: 20_000 });
16814
16824
  *
16815
16825
  * const slab = new Float32Array(20_000 * 16);
16816
16826
  * // ... write 16 column-major floats per instance ...
@@ -16959,7 +16969,7 @@ export declare class InstancedMeshRenderer extends Component implements Componen
16959
16969
  * ```ts
16960
16970
  * const hero = await app.assets.loadAsync<ModelAsset>("models/hero.glb");
16961
16971
  * const entity = world.createEntity("Hero");
16962
- * const model = entity.addComponent(Model, { model: hero.retain() });
16972
+ * const model = entity.addComponent(Model, { model: hero });
16963
16973
  * model.attachToNode("hand.R", sword);
16964
16974
  * ```
16965
16975
  *