@woosh/meep-engine 3.9.0 → 3.10.0

package/src/core/color/parse_color_normalized.js

@@ -0,0 +1,38 @@
+import { uint8_to_float } from "../binary/uint8_to_float.js";
+import { parse_color } from "./parse_color.js";
+
+/**
+ * Parses a CSS colour into four channels all on the same `[0, 1]` scale.
+ *
+ * {@link parse_color} returns a mixed unit — RGB in bytes, alpha already normalised — which is the most
+ * surprising thing about it and, until now, meant every caller wanting floats had to know to divide three of
+ * the four elements by 255. `Color.parse` carried exactly that knowledge, which is the kind of thing that
+ * belongs in the colour package rather than in whoever is reading from it.
+ *
+ * `parse_color` keeps its published contract unchanged; the units are documented there and a downstream caller
+ * may well be relying on the byte scale. This is the normalised view of the same parse.
+ *
+ * The result is **encoded** sRGB, since that is what a CSS literal holds — see the note on {@link Color}.
+ *
+ * @param {number[]|ArrayLike<number>} output length >= 4, receives r, g, b, a
+ * @param {string|number} value a CSS colour string, or a 24-bit `0xRRGGBB` integer
+ * @returns {number[]|ArrayLike<number>} output
+ * @throws Error if the value cannot be parsed
+ *
+ * @see parse_color for the byte-scaled form
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function parse_color_normalized(output, value) {
+
+    const parsed = parse_color(value);
+
+    output[0] = uint8_to_float(parsed[0]);
+    output[1] = uint8_to_float(parsed[1]);
+    output[2] = uint8_to_float(parsed[2]);
+
+    // alpha comes out of parse_color already on 0..1, which is the asymmetry this function exists to hide
+    output[3] = parsed[3];
+
+    return output;
+}

package/src/core/color/rgb2uint24.d.ts

@@ -1,9 +1,2 @@
-/**
- *
- * @param {number} r in 0..1 range
- * @param {number} g in 0..1 range
- * @param {number} b in 0..1 range
- * @returns {number}
- */
-export function rgb2uint24(r: number, g: number, b: number): number;
+export { rgb_to_uint24 as rgb2uint24 } from "./rgb_to_uint24.js";
 //# sourceMappingURL=rgb2uint24.d.ts.map

package/src/core/color/rgb2uint24.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rgb2uint24.d.ts","sourceRoot":"","sources":["../../../../src/core/color/rgb2uint24.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,8BALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAWlB"}
+{"version":3,"file":"rgb2uint24.d.ts","sourceRoot":"","sources":["../../../../src/core/color/rgb2uint24.js"],"names":[],"mappings":""}

package/src/core/color/rgb2uint24.js

@@ -1,20 +1,7 @@
-import { float_to_uint8 } from "../binary/float_to_uint8.js";
-
-/**
- *
- * @param {number} r in 0..1 range
- * @param {number} g in 0..1 range
- * @param {number} b in 0..1 range
- * @returns {number}
- */
-export function rgb2uint24(r, g, b) {
-    const _r = float_to_uint8(r);
-    const _g = float_to_uint8(g);
-    const _b = float_to_uint8(b);
-
-    return (_b & 0xFF)
-        | (_g & 0xFF) << 8
-        | (_r & 0xFF) << 16
-        ;
-}
-
+/**
+ * @deprecated Renamed to `rgb_to_uint24`, following the package's `name_to_name` convention.
+ *
+ * Kept as a re-export rather than removed: this is a library, and an import path is as much a published
+ * interface as a function signature.
+ */
+export { rgb_to_uint24 as rgb2uint24 } from "./rgb_to_uint24.js";

package/src/core/color/rgb2uint32.d.ts

@@ -1,10 +1,2 @@
-/**
- *
- * @param {number} r in 0..1 range
- * @param {number} g in 0..1 range
- * @param {number} b in 0..1 range
- * @param {number} a in 0..1 range
- * @returns {number}
- */
-export function rgb2uint32(r: number, g: number, b: number, a: number): number;
+export { rgb_to_uint32 as rgb2uint32 } from "./rgb_to_uint32.js";
 //# sourceMappingURL=rgb2uint32.d.ts.map

package/src/core/color/rgb2uint32.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rgb2uint32.d.ts","sourceRoot":"","sources":["../../../../src/core/color/rgb2uint32.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,8BANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAQlB"}
+{"version":3,"file":"rgb2uint32.d.ts","sourceRoot":"","sources":["../../../../src/core/color/rgb2uint32.js"],"names":[],"mappings":""}

package/src/core/color/rgb2uint32.js

@@ -1,18 +1,7 @@
-import { float_to_uint8 } from "../binary/float_to_uint8.js";
-import { rgb2uint24 } from "./rgb2uint24.js";
-
-/**
- *
- * @param {number} r in 0..1 range
- * @param {number} g in 0..1 range
- * @param {number} b in 0..1 range
- * @param {number} a in 0..1 range
- * @returns {number}
- */
-export function rgb2uint32(r, g, b, a) {
-    const partial = rgb2uint24(r, g, b);
-
-    const _a = float_to_uint8(a);
-
-    return (partial << 8) | (_a & 0xFF);
-}
+/**
+ * @deprecated Renamed to `rgb_to_uint32`, following the package's `name_to_name` convention.
+ *
+ * Kept as a re-export rather than removed: this is a library, and an import path is as much a published
+ * interface as a function signature.
+ */
+export { rgb_to_uint32 as rgb2uint32 } from "./rgb_to_uint32.js";

package/src/core/color/rgb_to_luminance.d.ts

@@ -1,12 +1,21 @@
 /**
- * Calculates Luminance (perceived brightness) using modern Rec.709 coefficients.
+ * Calculates relative luminance using Rec.709 coefficients.
  *
  * Matches sRGB and HDTV standards.
  *
- * @param {number} r Red component (linear or gamma-corrected)
- * @param {number} g Green component (linear or gamma-corrected)
- * @param {number} b Blue component (linear or gamma-corrected)
- * @return {number} The calculated luma value
+ * **Input must be linear.** These coefficients define two different quantities depending on what you feed
+ * them: applied to linear values they give *luminance* (Y), applied to encoded sRGB they give *luma* (Y′).
+ * Both are legitimate and both use these exact numbers by definition, but they are not interchangeable —
+ * luma is not a physical brightness and does not sum or average correctly. The GPU twin,
+ * `chunk_rgb_to_luminance`, states the same requirement.
+ *
+ * @param {number} r Red component, **linear**
+ * @param {number} g Green component, **linear**
+ * @param {number} b Blue component, **linear**
+ * @return {number} relative luminance; luma (Y′) if the input was encoded
+ *
+ * @see chunk_rgb_to_luminance the WGSL implementation of the same weights
+ * @see sRGB_to_linear to decode encoded sRGB before calling this
  */
 export function rgb_to_luminance(r: number, g: number, b: number): number;
 //# sourceMappingURL=rgb_to_luminance.d.ts.map

package/src/core/color/rgb_to_luminance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rgb_to_luminance.d.ts","sourceRoot":"","sources":["../../../../src/core/color/rgb_to_luminance.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,oCALW,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAIjB"}
+{"version":3,"file":"rgb_to_luminance.d.ts","sourceRoot":"","sources":["../../../../src/core/color/rgb_to_luminance.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,oCARW,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAOjB"}

package/src/core/color/rgb_to_luminance.js

@@ -1,13 +1,24 @@
-/**
- * Calculates Luminance (perceived brightness) using modern Rec.709 coefficients.
- *
- * Matches sRGB and HDTV standards.
- *
- * @param {number} r Red component (linear or gamma-corrected)
- * @param {number} g Green component (linear or gamma-corrected)
- * @param {number} b Blue component (linear or gamma-corrected)
- * @return {number} The calculated luma value
- */
-export function rgb_to_luminance(r, g, b) {
-    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
-}
+import { REC709_LUMINANCE_B, REC709_LUMINANCE_G, REC709_LUMINANCE_R } from "./REC709_PRIMARIES.js";
+
+/**
+ * Calculates relative luminance using Rec.709 coefficients.
+ *
+ * Matches sRGB and HDTV standards.
+ *
+ * **Input must be linear.** These coefficients define two different quantities depending on what you feed
+ * them: applied to linear values they give *luminance* (Y), applied to encoded sRGB they give *luma* (Y′).
+ * Both are legitimate and both use these exact numbers by definition, but they are not interchangeable —
+ * luma is not a physical brightness and does not sum or average correctly. The GPU twin,
+ * `chunk_rgb_to_luminance`, states the same requirement.
+ *
+ * @param {number} r Red component, **linear**
+ * @param {number} g Green component, **linear**
+ * @param {number} b Blue component, **linear**
+ * @return {number} relative luminance; luma (Y′) if the input was encoded
+ *
+ * @see chunk_rgb_to_luminance the WGSL implementation of the same weights
+ * @see sRGB_to_linear to decode encoded sRGB before calling this
+ */
+export function rgb_to_luminance(r, g, b) {
+    return REC709_LUMINANCE_R * r + REC709_LUMINANCE_G * g + REC709_LUMINANCE_B * b;
+}

package/src/core/color/rgb_to_uint24.d.ts

@@ -0,0 +1,9 @@
+/**
+ *
+ * @param {number} r in 0..1 range
+ * @param {number} g in 0..1 range
+ * @param {number} b in 0..1 range
+ * @returns {number}
+ */
+export function rgb_to_uint24(r: number, g: number, b: number): number;
+//# sourceMappingURL=rgb_to_uint24.d.ts.map

package/src/core/color/rgb_to_uint24.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rgb_to_uint24.d.ts","sourceRoot":"","sources":["../../../../src/core/color/rgb_to_uint24.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,iCALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAWlB"}

package/src/core/color/rgb_to_uint24.js

@@ -0,0 +1,20 @@
+import { float_to_uint8 } from "../binary/float_to_uint8.js";
+
+/**
+ *
+ * @param {number} r in 0..1 range
+ * @param {number} g in 0..1 range
+ * @param {number} b in 0..1 range
+ * @returns {number}
+ */
+export function rgb_to_uint24(r, g, b) {
+    const _r = float_to_uint8(r);
+    const _g = float_to_uint8(g);
+    const _b = float_to_uint8(b);
+
+    return (_b & 0xFF)
+        | (_g & 0xFF) << 8
+        | (_r & 0xFF) << 16
+        ;
+}
+

package/src/core/color/rgb_to_uint32.d.ts

@@ -0,0 +1,10 @@
+/**
+ *
+ * @param {number} r in 0..1 range
+ * @param {number} g in 0..1 range
+ * @param {number} b in 0..1 range
+ * @param {number} a in 0..1 range
+ * @returns {number} the packed value as an unsigned 32-bit integer
+ */
+export function rgb_to_uint32(r: number, g: number, b: number, a: number): number;
+//# sourceMappingURL=rgb_to_uint32.d.ts.map

package/src/core/color/rgb_to_uint32.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rgb_to_uint32.d.ts","sourceRoot":"","sources":["../../../../src/core/color/rgb_to_uint32.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,iCANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAWlB"}

package/src/core/color/rgb_to_uint32.js

@@ -0,0 +1,21 @@
+import { float_to_uint8 } from "../binary/float_to_uint8.js";
+import { rgb_to_uint24 } from "./rgb_to_uint24.js";
+
+/**
+ *
+ * @param {number} r in 0..1 range
+ * @param {number} g in 0..1 range
+ * @param {number} b in 0..1 range
+ * @param {number} a in 0..1 range
+ * @returns {number} the packed value as an unsigned 32-bit integer
+ */
+export function rgb_to_uint32(r, g, b, a) {
+    const partial = rgb_to_uint24(r, g, b);
+
+    const _a = float_to_uint8(a);
+
+    // `<<` and `|` are signed 32-bit operations, so any red >= 0x80 overflows into the sign bit and white
+    // packs as -1. `>>> 0` is the only JS operator that reinterprets the result as unsigned, and it makes the
+    // return value match what the name promises.
+    return ((partial << 8) | (_a & 0xFF)) >>> 0;
+}

package/src/core/color/sRGB/linear_to_sRGB.d.ts

@@ -1,4 +1,11 @@
 /**
+ * On the two spellings of the sRGB token.
+ *
+ * This directory writes it `sRGB`, as the standard does; the OkLab family next door writes `linear_srgb_*`.
+ * That is not drift left to be tidied: the OkLab names are Ottosson's own, carried over from his reference
+ * implementation along with the coefficients, and renaming them would make them harder to check against the
+ * source they came from. The rule is therefore: `sRGB` in this package's own names, and the upstream spelling
+ * wherever a function is a port of someone else's published code.
  *
  * @param {number} c
  * @return {number}

package/src/core/color/sRGB/linear_to_sRGB.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"linear_to_sRGB.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/sRGB/linear_to_sRGB.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,kDAHW,MAAM,GACL,MAAM,CAQjB;AAED;;;;;;GAMG;AACH,uCALW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,iBAC1B,MAAM,SACN,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,gBAC1B,MAAM,QAahB"}
+{"version":3,"file":"linear_to_sRGB.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/sRGB/linear_to_sRGB.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,kDAHW,MAAM,GACL,MAAM,CAQjB;AAED;;;;;;GAMG;AACH,uCALW,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,iBAC1B,MAAM,SACN,MAAM,EAAE,GAAC,UAAU,MAAM,CAAC,gBAC1B,MAAM,QAahB"}

package/src/core/color/sRGB/linear_to_sRGB.js

@@ -1,32 +1,39 @@
-/**
- *
- * @param {number} c
- * @return {number}
- */
-export function convert_channel_linear_to_sRGB(c) {
-    if (c < 0.0031308) {
-        return c * 12.92;
-    } else {
-        return 1.055 * (Math.pow(c, 0.4166666666666667)) - 0.055;
-    }
-}
-
-/**
- *
- * @param {number[]|ArrayLike<number>} output
- * @param {number} output_offset
- * @param {number[]|ArrayLike<number>} input
- * @param {number} input_offset
- */
-export function linear_to_sRGB(
-    output, output_offset,
-    input, input_offset
-) {
-    const r = input[input_offset];
-    const g = input[input_offset + 1];
-    const b = input[input_offset + 2];
-
-    output[output_offset] = convert_channel_linear_to_sRGB(r);
-    output[output_offset + 1] = convert_channel_linear_to_sRGB(g);
-    output[output_offset + 2] = convert_channel_linear_to_sRGB(b);
-}
+/**
+ * On the two spellings of the sRGB token.
+ *
+ * This directory writes it `sRGB`, as the standard does; the OkLab family next door writes `linear_srgb_*`.
+ * That is not drift left to be tidied: the OkLab names are Ottosson's own, carried over from his reference
+ * implementation along with the coefficients, and renaming them would make them harder to check against the
+ * source they came from. The rule is therefore: `sRGB` in this package's own names, and the upstream spelling
+ * wherever a function is a port of someone else's published code.
+ *
+ * @param {number} c
+ * @return {number}
+ */
+export function convert_channel_linear_to_sRGB(c) {
+    if (c < 0.0031308) {
+        return c * 12.92;
+    } else {
+        return 1.055 * (Math.pow(c, 0.4166666666666667)) - 0.055;
+    }
+}
+
+/**
+ *
+ * @param {number[]|ArrayLike<number>} output
+ * @param {number} output_offset
+ * @param {number[]|ArrayLike<number>} input
+ * @param {number} input_offset
+ */
+export function linear_to_sRGB(
+    output, output_offset,
+    input, input_offset
+) {
+    const r = input[input_offset];
+    const g = input[input_offset + 1];
+    const b = input[input_offset + 2];
+
+    output[output_offset] = convert_channel_linear_to_sRGB(r);
+    output[output_offset + 1] = convert_channel_linear_to_sRGB(g);
+    output[output_offset + 2] = convert_channel_linear_to_sRGB(b);
+}

package/src/core/color/xyz/hpe_to_xyz.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Hunt-Pointer-Estévez (HPE) cone response back to CIE linear XYZ. The inverse of {@link xyz_to_hpe}.
+ *
+ * The forward matrix leaves Z alone, so the inverse only has to undo the 2x2 block acting on X and Y and then
+ * subtract Z's contribution back out. Coefficients are the exact algebraic inverse rather than a separately
+ * published matrix, so the round trip closes to floating-point precision instead of to the precision of
+ * whichever table was quoted.
+ *
+ * In-place safe: reads all three inputs before the first write, matching {@link xyz_to_hpe}.
+ *
+ * Takes the offset form `(out, out_offset, input, input_offset)`, with the `(out, input)` form also accepted;
+ * see {@link rgb_to_xyz}.
+ *
+ * @param {number[]} out
+ * @param {number|number[]} out_offset offset into `out`, or `input` for the legacy 2-argument form
+ * @param {number[]} [input]
+ * @param {number} [input_offset]
+ *
+ * @see xyz_to_hpe
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function hpe_to_xyz(out: number[], out_offset: number | number[], input?: number[], input_offset?: number): void;
+//# sourceMappingURL=hpe_to_xyz.d.ts.map

package/src/core/color/xyz/hpe_to_xyz.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hpe_to_xyz.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/xyz/hpe_to_xyz.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,gCATW,MAAM,EAAE,cACR,MAAM,GAAC,MAAM,EAAE,UACf,MAAM,EAAE,iBACR,MAAM,QAsBhB"}

package/src/core/color/xyz/hpe_to_xyz.js

@@ -0,0 +1,39 @@
+/**
+ * Hunt-Pointer-Estévez (HPE) cone response back to CIE linear XYZ. The inverse of {@link xyz_to_hpe}.
+ *
+ * The forward matrix leaves Z alone, so the inverse only has to undo the 2x2 block acting on X and Y and then
+ * subtract Z's contribution back out. Coefficients are the exact algebraic inverse rather than a separately
+ * published matrix, so the round trip closes to floating-point precision instead of to the precision of
+ * whichever table was quoted.
+ *
+ * In-place safe: reads all three inputs before the first write, matching {@link xyz_to_hpe}.
+ *
+ * Takes the offset form `(out, out_offset, input, input_offset)`, with the `(out, input)` form also accepted;
+ * see {@link rgb_to_xyz}.
+ *
+ * @param {number[]} out
+ * @param {number|number[]} out_offset offset into `out`, or `input` for the legacy 2-argument form
+ * @param {number[]} [input]
+ * @param {number} [input_offset]
+ *
+ * @see xyz_to_hpe
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function hpe_to_xyz(out, out_offset, input, input_offset) {
+
+    if (typeof out_offset !== "number") {
+        // legacy (out, input) form
+        input = out_offset;
+        out_offset = 0;
+        input_offset = 0;
+    }
+
+    const l = input[input_offset];
+    const m = input[input_offset + 1];
+    const s = input[input_offset + 2];
+
+    out[out_offset] = 1.91019683405203 * l - 1.11212389278787 * m + 0.201907956767499 * s;
+    out[out_offset + 1] = 0.370950088248689 * l + 0.629054257392613 * m - 0.00000805514218435915 * s;
+    out[out_offset + 2] = s;
+}

package/src/core/color/xyz/rgb_to_xyz.d.ts

@@ -3,8 +3,23 @@
  * Assumes linear RGB space
  * Assumes D65 standard illuminant
  * @see https://www.image-engineering.de/library/technotes/958-how-to-convert-between-srgb-and-ciexyz
+ *
+ * ## Two call forms
+ *
+ * The offset form `(out, out_offset, input, input_offset)` is the package's standard, shared with
+ * `linear_to_sRGB`, `xyz_to_lab`, `xyz_to_ycxcz`, `tonemap_aces` and the rest of the modern layer. It is what
+ * lets a caller work straight out of a packed buffer instead of copying a triple in and out - which matters
+ * here more than anywhere else, since these two are the most-imported conversions in the package and chaining
+ * them with `xyz_to_lab` previously required remembering that one side had offsets and the other did not.
+ *
+ * The original `(out, input)` form still works and is detected by the type of the second argument. It is kept
+ * because this is a library and its callers are not all in this repository; new code should use the offset
+ * form.
+ *
  * @param {number[]|Float32Array|Float64Array} out
- * @param {number[]|Float32Array|Float64Array} input
+ * @param {number|number[]|Float32Array|Float64Array} out_offset offset into `out`, or `input` for the legacy 2-argument form
+ * @param {number[]|Float32Array|Float64Array} [input]
+ * @param {number} [input_offset]
  */
-export function rgb_to_xyz(out: number[] | Float32Array | Float64Array, input: number[] | Float32Array | Float64Array): void;
+export function rgb_to_xyz(out: number[] | Float32Array | Float64Array, out_offset: number | number[] | Float32Array | Float64Array, input?: number[] | Float32Array | Float64Array, input_offset?: number): void;
 //# sourceMappingURL=rgb_to_xyz.d.ts.map

package/src/core/color/xyz/rgb_to_xyz.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rgb_to_xyz.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/xyz/rgb_to_xyz.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,gCAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,SAClC,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,QAW5C"}
+{"version":3,"file":"rgb_to_xyz.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/xyz/rgb_to_xyz.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,gCALW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,GAAC,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,UACzC,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,QAoBhB"}

package/src/core/color/xyz/rgb_to_xyz.js

@@ -1,18 +1,44 @@
-/**
- * Convert to CIE XYZ color model
- * Assumes linear RGB space
- * Assumes D65 standard illuminant
- * @see https://www.image-engineering.de/library/technotes/958-how-to-convert-between-srgb-and-ciexyz
- * @param {number[]|Float32Array|Float64Array} out
- * @param {number[]|Float32Array|Float64Array} input
- */
-export function rgb_to_xyz(out, input) {
-
-    const x = input[0];
-    const y = input[1];
-    const z = input[2];
-
-    out[0] = 0.41239079926595948129 * x + 0.35758433938387796373 * y + 0.18048078840183428751 * z;
-    out[1] = 0.21263900587151035754 * x + 0.71516867876775592746 * y + 0.07219231536073371500 * z;
-    out[2] = 0.01933081871559185069 * x + 0.11919477979462598791 * y + 0.95053215224966058086 * z;
-}
+import { REC709_LUMINANCE_B, REC709_LUMINANCE_G, REC709_LUMINANCE_R } from "../REC709_PRIMARIES.js";
+
+/**
+ * Convert to CIE XYZ color model
+ * Assumes linear RGB space
+ * Assumes D65 standard illuminant
+ * @see https://www.image-engineering.de/library/technotes/958-how-to-convert-between-srgb-and-ciexyz
+ *
+ * ## Two call forms
+ *
+ * The offset form `(out, out_offset, input, input_offset)` is the package's standard, shared with
+ * `linear_to_sRGB`, `xyz_to_lab`, `xyz_to_ycxcz`, `tonemap_aces` and the rest of the modern layer. It is what
+ * lets a caller work straight out of a packed buffer instead of copying a triple in and out - which matters
+ * here more than anywhere else, since these two are the most-imported conversions in the package and chaining
+ * them with `xyz_to_lab` previously required remembering that one side had offsets and the other did not.
+ *
+ * The original `(out, input)` form still works and is detected by the type of the second argument. It is kept
+ * because this is a library and its callers are not all in this repository; new code should use the offset
+ * form.
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number|number[]|Float32Array|Float64Array} out_offset offset into `out`, or `input` for the legacy 2-argument form
+ * @param {number[]|Float32Array|Float64Array} [input]
+ * @param {number} [input_offset]
+ */
+export function rgb_to_xyz(out, out_offset, input, input_offset) {
+
+    if (typeof out_offset !== "number") {
+        // legacy (out, input) form
+        input = out_offset;
+        out_offset = 0;
+        input_offset = 0;
+    }
+
+    const x = input[input_offset];
+    const y = input[input_offset + 1];
+    const z = input[input_offset + 2];
+
+    out[out_offset] = 0.41239079926595948129 * x + 0.35758433938387796373 * y + 0.18048078840183428751 * z;
+    // the Y row is the Rec.709 luminance weights by definition, so it reads them from the same place
+    // rgb_to_luminance does rather than carrying its own copy at its own precision
+    out[out_offset + 1] = REC709_LUMINANCE_R * x + REC709_LUMINANCE_G * y + REC709_LUMINANCE_B * z;
+    out[out_offset + 2] = 0.01933081871559185069 * x + 0.11919477979462598791 * y + 0.95053215224966058086 * z;
+}

package/src/core/color/xyz/xyz_cmf_tabulated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"xyz_cmf_tabulated.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/xyz/xyz_cmf_tabulated.js"],"names":[],"mappings":"AA6KA;;;;;;;GAOG;AACH,uCAJW,MAAM,EAAE,iBACR,MAAM,GACJ,MAAM,EAAE,CA+BpB;AAhND;;;;;;;;;GASG;AAEH,iCAAkC;AAClC,iCAAkC"}
+{"version":3,"file":"xyz_cmf_tabulated.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/xyz/xyz_cmf_tabulated.js"],"names":[],"mappings":"AA8KA;;;;;;;GAOG;AACH,uCAJW,MAAM,EAAE,iBACR,MAAM,GACJ,MAAM,EAAE,CAoCpB;AArND;;;;;;;;;GASG;AAEH,iCAAkC;AAClC,iCAAkC"}