@woosh/meep-engine 3.9.0 → 3.10.0

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

@@ -1,10 +1,38 @@
 /**
  * Representation color and transparency (RGBA).
  *
+ * ## Colour space
+ *
+ * `Color` is **space-agnostic**. It is four floats and a change signal; it holds whatever the caller put in
+ * it and carries no record of which transfer function or primaries that was. There is deliberately no space
+ * tag, enum, or brand — this is a low-level container used on per-particle and per-vertex paths, and the
+ * contract lives in the *functions* that operate on a `Color` rather than in the object.
+ *
+ * That contract is worth knowing, because the two halves of the package disagree by default:
+ *
+ * - {@link Color#parse}, {@link Color#toHex} and {@link Color#toCssRGBAString} speak **encoded** sRGB, since
+ *   that is what CSS and hex literals are.
+ * - Everything in `operations/` (`color_lighten`, `color_darken`, `color_lerp`, …) and
+ *   {@link Color#computeLuminance} expect **linear** values.
+ *
+ * So `color_lighten(Color.parse('#808080'))` is wrong, quietly. Convert with
+ * {@link Color.from_sRGB_to_linear} first, or use the `color_srgb_*` wrappers in `operations/`, which do it
+ * for you.
+ *
+ * ## Range
+ *
+ * Values are 0 to 1 for SDR, but nothing enforces that: {@link Color#set} accepts any finite number so that
+ * HDR content and out-of-gamut intermediates work. The cost of that tolerance is that a channel which has
+ * gone wrong is usually still a perfectly finite number, so no assert will catch it for you.
+ *
+ * ## Notifications
+ *
+ * {@link Color#set} and everything routed through it fire `onChanged`. The numeric index setters do not —
+ * see the note on `set 0`.
+ *
  * @example
  *  const red = new Color(1,0,0);
  *
- * @extends {Array.<number>}
  * @class
  */
 export class Color {
@@ -40,23 +68,31 @@ export class Color {
      *  Color.parse("rgba(255, 0, 255, 0.5)");
      *  Color.parse("hsv(0.5, 1, 0.3)");
      *
+     * The result holds **encoded** sRGB; see {@link Color#parse}.
+     *
      * @param {string|number} value
      * @return {Color}
      * @throws Error if format could not be parsed
      */
     static parse(value: string | number): Color;
     /**
+     * Encode a linear colour to sRGB.
      *
-     * @param {Color} input
-     * @param {Color} [output]
-     * @returns {Color}
+     * Alpha is carried across unchanged; the transfer function applies to the three colour channels only.
+     *
+     * @param {Color} input **linear** sRGB
+     * @param {Color} [output] may be `input`
+     * @returns {Color} `output`, holding **encoded** sRGB
      */
     static from_linear_to_sRGB(input: Color, output?: Color): Color;
     /**
+     * Decode an sRGB colour to linear.
      *
-     * @param {Color} input
-     * @param {Color} [output]
-     * @returns {Color}
+     * Alpha is carried across unchanged; the transfer function applies to the three colour channels only.
+     *
+     * @param {Color} input **encoded** sRGB
+     * @param {Color} [output] may be `input`
+     * @returns {Color} `output`, holding **linear** sRGB
      */
     static from_sRGB_to_linear(input: Color, output?: Color): Color;
     /**
@@ -92,11 +128,24 @@ export class Color {
      */
     a: number;
     /**
+     * Fires whenever {@link Color#set} changes any channel, with the new four values followed by the old four.
+     *
+     * Allocated on first access rather than in the constructor. Every `Color` used to pay for a `Signal`
+     * whether or not anything subscribed — measured at 4x the construction cost — and `Color` is a low-level
+     * type used on per-particle and per-vertex paths where most instances never have a listener.
+     *
+     * This is a getter, but it behaves as the plain property it replaced: reading it always yields the same
+     * `Signal` for a given `Color`.
+     *
      * @readonly
-     * @type {Signal<number,number,number,number, number,number,number,number>}
+     * @returns {Signal<number,number,number,number, number,number,number,number>}
      */
-    readonly onChanged: any;
+    readonly get onChanged(): any;
     /**
+     * NOTE: the numeric index setters write the field directly, so they bypass {@link Color#set} — no
+     * equality check and, more importantly, no `onChanged` notification. Writing a `Color` positionally
+     * (by handing it to a function that takes an `(output, output_offset)` pair, for instance) is
+     * therefore an *unobserved* mutation. Prefer `set()` whenever the target may have listeners.
      *
      * @param {number} v
      */
@@ -217,16 +266,35 @@ export class Color {
      */
     setHSL(h: number, s: number, l: number): void;
     /**
-     * Hue Chroma Luma
-     * @param {number} h Hue
+     * Hue Chroma Luma.
+     *
+     * **Unbounded — the caller clamps.** The result is exact by construction: the written colour has chroma
+     * exactly `c` and Rec.601 luma exactly `l`. Not every `(h, c, l)` triple names a point inside the RGB
+     * cube, though, so a saturated one lands outside it — `setHCL(0, 1, 0.5)` gives `(1.2, 0.2, 0.2)`, which
+     * is the honest answer rather than an error. Clamping here would silently move the hue, and `Color` is a
+     * space-agnostic container that already tolerates out-of-range values for HDR, so gamut mapping belongs
+     * to the caller. Use `color_clamp` / `color_is_in_gamut` if you need the colour displayable.
+     *
+     * Contrast {@link Color#setHSL} and {@link Color#setHSV}, which cannot leave the cube for any input.
+     *
+     * @param {number} h Hue, 0..1 (1 represents 360deg); values outside the range wrap
      * @param {number} c Chroma
-     * @param {number} l Luma
+     * @param {number} l Luma (Rec.601 weighted)
      */
     setHCL(h: number, c: number, l: number): void;
     /**
-     * NOTE: I'm not sure if the implementation is correct, based on wikipedia article
-     * Hue Saturation Intensity
-     * @param {number} h 0..1 (hue rotation compressed to normal 0 to 1 range where 1 represents 360deg)
+     * Hue Saturation Intensity.
+     *
+     * Verified against the definition rather than against a table: the written colour satisfies both HSI
+     * invariants exactly — its intensity `(r + g + b) / 3` is `i`, and its saturation `1 - min(r,g,b) / i` is
+     * `s`. That settles the author's earlier note about not being sure the implementation was right; it is.
+     *
+     * **Unbounded — the caller clamps**, same as {@link Color#setHCL}. `setHSI(0, 1, 0.5)` gives
+     * `(1.5, 0, 0)`, and that is correct: intensity 0.5 at full saturation on a pure hue *requires* a red of
+     * 1.5, because the mean of the three channels has to come to 0.5. The triple is outside the RGB cube, so
+     * the colour is too.
+     *
+     * @param {number} h 0..1 (hue rotation compressed to normal 0 to 1 range where 1 represents 360deg); values outside the range wrap
      * @param {number} s 0..1
      * @param {number} i 0..1
      * @see https://en.wikipedia.org/wiki/HSL_and_HSV
@@ -260,17 +328,27 @@ export class Color {
      */
     toUint32(): number;
     /**
+     * Decodes a 24-bit `0xRRGGBB` value. Alpha is left untouched.
      *
-     * @param {number} value
+     * @param {number} value 24-bit `0xRRGGBB`
      */
     fromUint(value: number): void;
     /**
-     * Returns color in CSS hex color format
+     * Returns color in CSS hex color format.
+     *
+     * Produces **encoded** sRGB, because that is what a hex literal means. If this `Color` holds linear
+     * values, encode it with {@link Color.from_linear_to_sRGB} first or the result will read far too dark.
+     *
+     * Alpha is dropped — the three-channel `#RRGGBB` form is the only one written.
+     *
      * @example #FF0000
      * @returns {string}
      */
     toHex(): string;
     /**
+     * Returns color in CSS `rgba()` format.
+     *
+     * Produces **encoded** sRGB, same as {@link Color#toHex}.
      *
      * @returns {string}
      */
@@ -291,6 +369,11 @@ export class Color {
      */
     clone(): Color;
     /**
+     * Hashes all four channels.
+     *
+     * Via {@link Color#toUint32} rather than {@link Color#toUint}, so that alpha participates — {@link
+     * Color#equals} compares four channels, so hashing three made colours differing only in alpha collide.
+     * The `equals => same hash` contract held either way; this just stops the collision.
      *
      * @returns {number}
      */
@@ -333,26 +416,50 @@ export class Color {
      */
     fromBinaryBuffer(buffer: BinaryBuffer): void;
     /**
-     * @param {string|number} str CSS-style string
+     * Reads a CSS colour literal into this `Color`.
+     *
+     * The result holds **encoded** sRGB — CSS values are encoded by definition. Convert with
+     * {@link Color.from_sRGB_to_linear} before handing it to anything in `operations/`, or to
+     * {@link Color#computeLuminance}, all of which expect linear input.
+     *
+     * @param {string|number} str CSS-style string, or a 24-bit `0xRRGGBB` integer
      * @returns {void}
+     * @throws Error if the value cannot be parsed
      */
     parse(str: string | number): void;
     /**
+     * Per-channel linear interpolation between two other colours, written into this one.
+     *
+     * Interpolates the raw channels, which is the right thing when a colour is being treated as a vector, and
+     * is space-agnostic in the sense that it does whatever linear algebra you asked for in whatever space the
+     * inputs happened to be in. It is *not* perceptual: `color_lerp` converts to OkHSV and takes the shortest
+     * hue arc instead, and the two give substantially different results at mid-`f`.
      *
      * @param {Color} a
      * @param {Color} b
      * @param {number} f
      * @returns {this}
+     *
+     * @see color_lerp for the perceptual alternative
      */
     lerpColors(a: Color, b: Color, f: number): this;
     /**
-     * Multiply every component by a scalar value
+     * Multiply every component by a scalar value.
+     *
+     * **Alpha is scaled too** — this is a 4-vector multiply, not an exposure control. That is rarely what a
+     * caller reaching for "multiply a colour" wants, so it is called out here rather than left to be
+     * discovered: `multiplyScalar(0.5)` halves transparency along with brightness. Use `color_multiply_rgb`
+     * when the intent is exposure or tint.
+     *
      * @param {number} x
      * @returns {this}
      */
     multiplyScalar(x: number): this;
     /**
-     * Component-wise vector multiplication
+     * Component-wise vector multiplication.
+     *
+     * **Alpha is multiplied too**, same as {@link Color#multiplyScalar} — see the note there.
+     *
      * @param {Color} other
      * @returns {this}
      */
@@ -363,6 +470,7 @@ export class Color {
      */
     readonly isColor: boolean;
     [Symbol.iterator](): Generator<number, void, unknown>;
+    #private;
 }
 export namespace Color {
     let red: Readonly<Color>;

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

@@ -1 +1 @@
-{"version":3,"file":"Color.d.ts","sourceRoot":"","sources":["../../../../src/core/color/Color.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"Color.d.ts","sourceRoot":"","sources":["../../../../src/core/color/Color.js"],"names":[],"mappings":"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"}