@forgeax/engine-math 0.0.0-dev.8d955ade1c79

package/src/color.ts

@@ -0,0 +1,177 @@
+// color.ts — RGBA color namespace (M5 / T-032)
+//
+// 6-function surface: create / clone / srgbToLinear / linearToSrgb / fromHex / toHex
+//
+// Design anchors:
+//   - branded Float32Array length 4 [r, g, b, a]; `as Color` casts are funneled inside factories (D-P15)
+//   - sRGB ↔ linear: IEC 61966-2-1 piecewise gamma; RGB channels only, alpha pass-through
+//     - srgbToLinear: cutoff 0.04045 / linear segment v/12.92 / power segment ((v+0.055)/1.055)^2.4
+//     - linearToSrgb: cutoff 0.0031308 / linear segment 12.92*v / power segment 1.055*v^(1/2.4) - 0.055
+//     - negatives / NaN returned verbatim (HDR-friendly + IEEE-754 NaN propagation)
+//   - fromHex (D-P7): only `#RRGGBB` (7 chars) and `#RRGGBBAA` (9 chars); illegal inputs silently fall
+//     back to (0, 0, 0, 1) without throwing (D-P12 degenerate family / AC-06)
+//     - #RGB / #RGBA short forms are not supported (stricter than bevy_color::Srgba::hex; less ambiguous
+//       in practice; wiki/sources/2026-05-05-bevy-0-19-math-transform-color §Srgba::hex mentions short
+//       forms but D-P7 actively tightens the contract)
+//   - toHex: alpha=1 → `#rrggbb`; alpha<1 → `#rrggbbaa`; components are clamped to [0, 1] then
+//     multiplied by 255 and rounded; output is lowercase, symmetric with fromHex's tolerant input
+//
+// Related: requirements §Surface color lower bound 6 + AC-06 silent fall-back (never raises);
+//          plan-strategy D-P7 / D-P12 / §appendix A degenerate registry #14-#16;
+//          wiki/sources/2026-05-05-bevy-0-19-math-transform-color §sRGB piecewise gamma;
+//          wiki/glam-rs-overview §LinearRgba.
+
+import type { Color, ColorLike } from './types';
+
+export type { Color, ColorLike };
+
+// === create / copy ===
+
+/** Create a Color (default RGBA = (0, 0, 0, 1) = opaque black). */
+export function create(r = 0, g = 0, b = 0, a = 1): Color {
+  return Float32Array.of(r, g, b, a) as Color;
+}
+
+/** Allocate a new Color copy. */
+export function clone(c: ColorLike): Color {
+  return Float32Array.of(c[0] as number, c[1] as number, c[2] as number, c[3] as number) as Color;
+}
+
+// === sRGB ↔ linear (IEC 61966-2-1 piecewise gamma) ===
+
+/**
+ * Single-channel sRGB → linear (component-level helper).
+ *
+ * @degrade NaN input → NaN output (IEEE-754 arithmetic propagation); negatives returned verbatim
+ * to preserve HDR / specialized rendering needs (same convention as bevy_color::gamma_function;
+ * wiki/sources bevy-0-19-color §gamma_function).
+ *
+ * @example
+ * ```ts
+ * srgbChannelToLinear(NaN);  // → NaN (IEEE-754 propagation)
+ * srgbChannelToLinear(-0.1); // → -0.1 (HDR / negative kept verbatim)
+ * ```
+ */
+function srgbChannelToLinear(v: number): number {
+  if (Number.isNaN(v)) return Number.NaN;
+  if (v <= 0) return v;
+  if (v <= 0.04045) return v / 12.92;
+  return ((v + 0.055) / 1.055) ** 2.4;
+}
+
+/** Single-channel linear → sRGB (component-level helper). */
+function linearChannelToSrgb(v: number): number {
+  if (Number.isNaN(v)) return Number.NaN;
+  if (v <= 0) return v;
+  if (v <= 0.0031308) return v * 12.92;
+  return 1.055 * v ** (1 / 2.4) - 0.055;
+}
+
+/**
+ * out = sRGB → linear conversion (RGB channels only; alpha passed through).
+ *
+ * @degrade NaN propagation / negatives returned verbatim (HDR-friendly); alpha is strictly untouched.
+ *
+ * @example
+ * ```ts
+ * color.srgbToLinear(out, color.create(NaN, -0.1, 0.5, 0.8));
+ * // → out = (NaN, -0.1, ~0.214, 0.8); alpha 0.8 passed through unchanged.
+ * ```
+ */
+export function srgbToLinear(out: Color, c: ColorLike): Color {
+  out[0] = srgbChannelToLinear(c[0] as number);
+  out[1] = srgbChannelToLinear(c[1] as number);
+  out[2] = srgbChannelToLinear(c[2] as number);
+  out[3] = c[3] as number;
+  return out;
+}
+
+/**
+ * out = linear → sRGB conversion (RGB channels only; alpha passed through).
+ *
+ * @degrade NaN propagation / negatives returned verbatim; alpha is strictly untouched.
+ *
+ * @example
+ * ```ts
+ * color.linearToSrgb(out, color.create(NaN, -0.05, 0.5, 1));
+ * // → out = (NaN, -0.05, ~0.735, 1); alpha is strictly untouched.
+ * ```
+ */
+export function linearToSrgb(out: Color, c: ColorLike): Color {
+  out[0] = linearChannelToSrgb(c[0] as number);
+  out[1] = linearChannelToSrgb(c[1] as number);
+  out[2] = linearChannelToSrgb(c[2] as number);
+  out[3] = c[3] as number;
+  return out;
+}
+
+// === Hex parse / serialize ===
+
+const HEX_PATTERN = /^#([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})?$/;
+
+/**
+ * Write a Color from a hex string.
+ *
+ * Only supports the two forms `#RRGGBB` (7 chars) and `#RRGGBBAA` (9 chars) (D-P7);
+ * the CSS-style `#RGB` / `#RGBA` short forms are not supported.
+ *
+ * @degrade Any illegal input (short form / non-hex chars / missing # / wrong length / empty string,
+ * etc.) silently falls back to (0, 0, 0, 1); never throws (D-P12 / AC-06).
+ *
+ * @example
+ * ```ts
+ * color.fromHex(out, '#ff8000');   // → (1, 0.502, 0, 1)
+ * color.fromHex(out, '#ff800080'); // → (1, 0.502, 0, 0.502)
+ * color.fromHex(out, '#fff');      // → (0, 0, 0, 1) short form unsupported → silent fall-back
+ * ```
+ */
+export function fromHex(out: Color, hex: string): Color {
+  const match = typeof hex === 'string' ? HEX_PATTERN.exec(hex) : null;
+  if (match === null) {
+    out[0] = 0;
+    out[1] = 0;
+    out[2] = 0;
+    out[3] = 1;
+    return out;
+  }
+  out[0] = Number.parseInt(match[1] as string, 16) / 255;
+  out[1] = Number.parseInt(match[2] as string, 16) / 255;
+  out[2] = Number.parseInt(match[3] as string, 16) / 255;
+  out[3] = match[4] !== undefined ? Number.parseInt(match[4], 16) / 255 : 1;
+  return out;
+}
+
+/** Per-component [0, 1] clamp + ×255 + round + 2-digit hex (lowercase). */
+function toHexByte(v: number): string {
+  if (Number.isNaN(v)) return '00';
+  const clamped = Math.max(0, Math.min(1, v));
+  const byte = Math.round(clamped * 255);
+  return byte.toString(16).padStart(2, '0');
+}
+
+/**
+ * Serialize as hex string: alpha=1 → `#rrggbb`; alpha<1 → `#rrggbbaa`.
+ *
+ * @degrade Out-of-range components (HDR > 1 / negatives) are clamped to [0, 1] then rounded;
+ * **truncated** rather than throwing (symmetric with fromHex's silent fall-back). NaN components →
+ * literal '00' (same byte as 0.0; prevents the hex-string builder from throwing; alpha=NaN takes the
+ * alpha=1 path, emitting the short `#rrggbb` form).
+ *
+ * @example
+ * ```ts
+ * color.toHex(color.create(2, -0.1, 0.5, 1));    // → '#ff0080' (HDR/negative clamp)
+ * color.toHex(color.create(1, 0, 0, 0.5));        // → '#ff000080'
+ * color.toHex(color.create(NaN, 0, 0, NaN));      // → '#000000' (NaN→'00', alpha=NaN takes short form)
+ * ```
+ */
+export function toHex(c: ColorLike): string {
+  const r = toHexByte(c[0] as number);
+  const g = toHexByte(c[1] as number);
+  const b = toHexByte(c[2] as number);
+  const aValue = c[3] as number;
+  if (aValue >= 1 || Number.isNaN(aValue)) {
+    return `#${r}${g}${b}`;
+  }
+  const a = toHexByte(aValue);
+  return `#${r}${g}${b}${a}`;
+}

package/src/easing.ts

@@ -0,0 +1,49 @@
+// easing.ts — easing-function namespace (solo round 20260713-233409)
+//
+// 4-function surface: cubicInOut / smoothstep / smootherstep / elasticInOut
+// (GLSL `smoothstep`, Perlin's smootherstep; Bevy `EaseFunction::SmoothStep`/`SmootherStep`).
+// Scalar time-remaps t → number: take a normalized parameter and return an eased value. The
+// growable home for Bevy's `EaseFunction` family — further variants (sine / quad / bounce /
+// steps) land here add-only.
+//
+// Every function clamps the input to [0, 1] first (GLSL / Bevy semantics), so out-of-range t
+// saturates to the endpoints rather than extrapolating the curve.
+
+import { clamp } from './_internal/scalar';
+
+/** Cubic ease-in-out: Bevy `EaseFunction::CubicInOut`, clamped to [0, 1]. */
+export function cubicInOut(t: number): number {
+  const x = clamp(t, 0, 1);
+  return x < 0.5 ? 4 * x * x * x : 1 - (-2 * x + 2) ** 3 / 2;
+}
+
+/**
+ * Smoothstep S-curve: `3t² − 2t³` on the clamped input. GLSL `smoothstep` (with edges 0/1),
+ * Bevy `EaseFunction::SmoothStep`. f(0)=0, f(1)=1, f′(0)=f′(1)=0 (slow-in / slow-out).
+ * Input clamped to [0, 1]. Use to ease a normalized time / lerp factor instead of a linear ramp.
+ */
+export function smoothstep(t: number): number {
+  const x = clamp(t, 0, 1);
+  return x * x * (3 - 2 * x);
+}
+
+/**
+ * Smootherstep (Perlin) S-curve: `6t⁵ − 15t⁴ + 10t³` on the clamped input. Bevy
+ * `EaseFunction::SmootherStep`. Like {@link smoothstep} but ALSO has zero 2nd derivatives at
+ * the endpoints (f″(0)=f″(1)=0), so acceleration is continuous — a gentler, more natural ease.
+ * Input clamped to [0, 1].
+ */
+export function smootherstep(t: number): number {
+  const x = clamp(t, 0, 1);
+  return x * x * x * (x * (x * 6 - 15) + 10);
+}
+
+/** Elastic ease-in-out: Bevy `EaseFunction::ElasticInOut`, clamped to [0, 1]. */
+export function elasticInOut(t: number): number {
+  const x = clamp(t, 0, 1);
+  if (x === 0 || x === 1) return x;
+  const c5 = (2 * Math.PI) / 4.5;
+  return x < 0.5
+    ? -(2 ** (20 * x - 10) * Math.sin((20 * x - 11.125) * c5)) / 2
+    : (2 ** (-20 * x + 10) * Math.sin((20 * x - 11.125) * c5)) / 2 + 1;
+}

package/src/euler.ts

@@ -0,0 +1,239 @@
+// euler.ts — Euler angle namespace (M4 / T-028)
+//
+// 6-function surface (≥ 6 lower bound):
+//   create / clone / set / fromQuat / toQuat / fromRotationMatrix
+//
+// Memory layout: plain object `{ x: number, y: number, z: number, order: EulerOrder }`
+// (not a Float32Array). Rationale:
+//   - need to store length=3 plus a string order; strings cannot live inside a TypedArray
+//   - performance-insensitive (euler is only used at the editor/IO boundary; runtime always converts to Quat)
+//
+// 6 orders (intrinsic rotation; literal order x → y → z):
+//   XYZ / YXZ / ZXY / ZYX / YZX / XZY
+//
+// Degenerate convention (plan-strategy §appendix A degenerate registry #16):
+//   - fromQuat(q, order) gimbal-lock (pitch ≈ ±π/2) → pick an equivalent branch; never throws
+//   - fromRotationMatrix follows the same convention
+//
+// Related: requirements §Surface euler lower bound 6 + 6-order full support;
+//          plan-strategy §1.1 euler.ts + §appendix A degenerate registry #16 + D-P19 EulerOrder union;
+//          wiki/glam-rs-overview Hamilton convention +
+//          Three.js Euler.setFromQuaternion / setFromRotationMatrix 6-order formulas.
+//
+// Degenerate-semantics registry (plan-strategy.md §appendix A; D-P16 dual promise:
+// runtime silent + JSDoc `@degrade` + `@example` guard pattern landing together):
+//   #16 euler.fromQuat(q, order) gimbal-lock  → pick equivalent branch (no throw)
+//   #17 euler.fromRotationMatrix gimbal-lock  → same as above
+
+import * as quat from './quat';
+import type { Euler, EulerOrder, Mat3Like, Quat, QuatLike } from './types';
+
+export type { Euler, EulerOrder };
+
+/** Create an Euler, defaulting to (0, 0, 0, 'XYZ'). */
+export function create(): Euler {
+  return { x: 0, y: 0, z: 0, order: 'XYZ' };
+}
+
+/** Allocate a new Euler copy. */
+export function clone(a: Euler): Euler {
+  return { x: a.x, y: a.y, z: a.z, order: a.order };
+}
+
+/** out.x/y/z/order = inputs; returns out (in-place). */
+export function set(out: Euler, x: number, y: number, z: number, order: EulerOrder): Euler {
+  out.x = x;
+  out.y = y;
+  out.z = z;
+  out.order = order;
+  return out;
+}
+
+/**
+ * out (Quat) = quaternion from euler. Returns out.
+ *
+ * Routes directly to quat.fromEuler (D-P2 + 6-order coverage already implemented inside quat).
+ *
+ * @example
+ * ```ts
+ * euler.toQuat(quatBuf, eulerInstance);
+ * ```
+ */
+export function toQuat(out: Quat, e: Euler): Quat {
+  return quat.fromEuler(out, e.x, e.y, e.z, e.order);
+}
+
+/**
+ * out (Euler) = euler angles from quaternion in given order. Returns out.
+ *
+ * Implementation path: quat → 3x3 column-major rotation matrix → fromRotationMatrix(order).
+ * This concentrates the 6-order formulas in fromRotationMatrix and avoids dual maintenance.
+ *
+ * @degrade gimbal lock (pitch ≈ ±π/2, sin/cos critical) → set yaw to 0 and let roll absorb the
+ *          full rotation (registry #16; same equivalent-branch semantics as Three.js; no throw).
+ *
+ * @example
+ * ```ts
+ * euler.fromQuat(out, q, 'XYZ');
+ * ```
+ */
+export function fromQuat(out: Euler, q: QuatLike, order: EulerOrder): Euler {
+  // Expand q into a 3x3 column-major rotation matrix (matching the index convention of quat.fromRotationMatrix)
+  const x = q[0] as number;
+  const y = q[1] as number;
+  const z = q[2] as number;
+  const w = q[3] as number;
+  const xx = x * x;
+  const xy = x * y;
+  const xz = x * z;
+  const yy = y * y;
+  const yz = y * z;
+  const zz = z * z;
+  const wx = w * x;
+  const wy = w * y;
+  const wz = w * z;
+
+  // mat3 column-major: m[col*3+row] → m00=col0row0, m01=col0row1, m10=col1row0...
+  // R[row][col] maps to m[col*3+row]:
+  //   R[0][0]=m00,R[0][1]=m10,R[0][2]=m20
+  //   R[1][0]=m01,R[1][1]=m11,R[1][2]=m21
+  //   R[2][0]=m02,R[2][1]=m12,R[2][2]=m22
+  const m = new Float32Array(9);
+  m[0] = 1 - 2 * (yy + zz);
+  m[1] = 2 * (xy + wz);
+  m[2] = 2 * (xz - wy);
+  m[3] = 2 * (xy - wz);
+  m[4] = 1 - 2 * (xx + zz);
+  m[5] = 2 * (yz + wx);
+  m[6] = 2 * (xz + wy);
+  m[7] = 2 * (yz - wx);
+  m[8] = 1 - 2 * (xx + yy);
+
+  return fromRotationMatrix(out, m, order);
+}
+
+/**
+ * out (Euler) = euler from a 3x3 rotation matrix m (column-major, length 9) in `order`. Returns out.
+ *
+ * Uses the Three.js Euler.setFromRotationMatrix formulas (intrinsic rotation + Hamilton convention).
+ * Each of the 6 orders has an analytic formula; near gimbal-lock (middle axis sin/cos near ±1)
+ * an equivalent branch is selected.
+ *
+ * @degrade gimbal lock → middle axis is fixed at ±π/2; the remaining two axes degenerate
+ * (one is set to 0; the other absorbs the rotation).
+ *
+ * @example
+ * ```ts
+ * euler.fromRotationMatrix(out, mat3InstanceColumnMajor, 'XYZ');
+ * ```
+ */
+export function fromRotationMatrix(out: Euler, m: Mat3Like, order: EulerOrder): Euler {
+  // Column-major indexing (matches quat.fromRotationMatrix):
+  //   m00 m01 m02 = column 0 (col=0)'s row=0/1/2
+  //   m10 m11 m12 = column 1 (col=1)'s row=0/1/2
+  //   m20 m21 m22 = column 2 (col=2)'s row=0/1/2
+  // Mathematically R[row][col] = m[c*3 + r].
+  // Thus, in the Three.js formulas, m11 (R[0][0]) corresponds to our m[0],
+  //                                m12 (R[0][1]) corresponds to m[3],
+  //                                m13 (R[0][2]) corresponds to m[6],
+  //                                m21 (R[1][0]) corresponds to m[1], etc.
+  // For readability and alignment with Three.js naming, alias (_ij denotes R[i-1][j-1]):
+  const _11 = m[0] as number;
+  const _21 = m[1] as number;
+  const _31 = m[2] as number;
+  const _12 = m[3] as number;
+  const _22 = m[4] as number;
+  const _32 = m[5] as number;
+  const _13 = m[6] as number;
+  const _23 = m[7] as number;
+  const _33 = m[8] as number;
+
+  out.order = order;
+  switch (order) {
+    case 'XYZ':
+      out.y = Math.asin(clamp11(_13));
+      if (Math.abs(_13) < 1 - 1e-7) {
+        out.x = Math.atan2(-_23, _33);
+        out.z = Math.atan2(-_12, _11);
+      } else {
+        // gimbal lock
+        out.x = Math.atan2(_32, _22);
+        out.z = 0;
+      }
+      break;
+    case 'YXZ':
+      out.x = Math.asin(-clamp11(_23));
+      if (Math.abs(_23) < 1 - 1e-7) {
+        out.y = Math.atan2(_13, _33);
+        out.z = Math.atan2(_21, _22);
+      } else {
+        out.y = Math.atan2(-_31, _11);
+        out.z = 0;
+      }
+      break;
+    case 'ZXY':
+      out.x = Math.asin(clamp11(_32));
+      if (Math.abs(_32) < 1 - 1e-7) {
+        out.y = Math.atan2(-_31, _33);
+        out.z = Math.atan2(-_12, _22);
+      } else {
+        out.y = 0;
+        out.z = Math.atan2(_21, _11);
+      }
+      break;
+    case 'ZYX':
+      out.y = Math.asin(-clamp11(_31));
+      if (Math.abs(_31) < 1 - 1e-7) {
+        out.x = Math.atan2(_32, _33);
+        out.z = Math.atan2(_21, _11);
+      } else {
+        out.x = 0;
+        out.z = Math.atan2(-_12, _22);
+      }
+      break;
+    case 'YZX':
+      out.z = Math.asin(clamp11(_21));
+      if (Math.abs(_21) < 1 - 1e-7) {
+        out.x = Math.atan2(-_23, _22);
+        out.y = Math.atan2(-_31, _11);
+      } else {
+        out.x = 0;
+        out.y = Math.atan2(_13, _33);
+      }
+      break;
+    case 'XZY':
+      out.z = Math.asin(-clamp11(_12));
+      if (Math.abs(_12) < 1 - 1e-7) {
+        out.x = Math.atan2(_32, _22);
+        out.y = Math.atan2(_13, _11);
+      } else {
+        out.x = Math.atan2(-_23, _33);
+        out.y = 0;
+      }
+      break;
+    default:
+      // Silent fallback to 'XYZ' (same convention as quat.fromEuler D-P2)
+      out.y = Math.asin(clamp11(_13));
+      if (Math.abs(_13) < 1 - 1e-7) {
+        out.x = Math.atan2(-_23, _33);
+        out.z = Math.atan2(-_12, _11);
+      } else {
+        out.x = Math.atan2(_32, _22);
+        out.z = 0;
+      }
+      out.order = 'XYZ';
+      break;
+  }
+
+  return out;
+}
+
+/**
+ * Internal: clamp to [-1, 1] to keep asin from receiving out-of-range inputs (floating-point error
+ * may make |x| slightly > 1; same guard as Three.js; not counted in the surface).
+ */
+function clamp11(v: number): number {
+  if (v < -1) return -1;
+  if (v > 1) return 1;
+  return v;
+}

package/src/f32-to-f16-bytes.ts

@@ -0,0 +1,71 @@
+// f32-to-f16-bytes.ts — IEEE 754 binary16 half-float conversion.
+//
+// Pure arithmetic codec extracted from runtime/render-resource-table.ts (D-3)
+// so build-time image-importer and runtime uploadCubemapFromEquirect share
+// a single SSOT. Takes a Uint8Array view over packed Float32 RGBA pixels
+// and returns a Uint8Array with half the byte length of the equivalent
+// binary16 interleaved pixels (little-endian).
+//
+// Out-of-range f32 values saturate to +/-inf, NaN propagates, and subnormals
+// round-to-zero (industry-standard f32->f16 path, semantic-preserving
+// extraction).
+//
+// Related: plan-strategy §2 D-3; research Finding 5 + C3; requirements C3;
+//          w1 test file: packages/math/src/__tests__/f32-to-f16-bytes.test.ts.
+
+/**
+ * Convert a packed float32 RGBA byte buffer into the equivalent float16 RGBA
+ * byte buffer (IEEE 754 binary16, little-endian). The output length is
+ * `src.byteLength / 2`.
+ *
+ * @param src A Uint8Array whose underlying buffer is an interleaved Float32Array.
+ * @returns A Uint8Array of packed binary16 pixels, exactly half the length.
+ */
+export function f32ToF16Bytes(src: Uint8Array): Uint8Array {
+  const f32 = new Float32Array(src.buffer, src.byteOffset, src.byteLength / 4);
+  const out = new Uint8Array(f32.length * 2);
+  const view = new DataView(out.buffer);
+  const scratch = new ArrayBuffer(4);
+  const scratchF = new Float32Array(scratch);
+  const scratchU = new Uint32Array(scratch);
+  for (let i = 0; i < f32.length; i++) {
+    scratchF[0] = f32[i] ?? 0;
+    const bits = scratchU[0] ?? 0;
+    const sign = (bits >>> 31) & 0x1;
+    const exp = (bits >>> 23) & 0xff;
+    let mant = bits & 0x7fffff;
+    let half: number;
+    if (exp === 0xff) {
+      half = (sign << 15) | 0x7c00 | (mant ? 0x200 : 0);
+    } else if (exp === 0) {
+      half = sign << 15;
+    } else {
+      const e = exp - 127 + 15;
+      if (e >= 0x1f) {
+        half = (sign << 15) | 0x7c00;
+      } else if (e <= 0) {
+        if (e < -10) {
+          half = sign << 15;
+        } else {
+          mant = (mant | 0x800000) >> (1 - e);
+          if (mant & 0x1000) mant += 0x2000;
+          half = (sign << 15) | (mant >> 13);
+        }
+      } else {
+        if (mant & 0x1000) {
+          mant += 0x2000;
+          if (mant & 0x800000) {
+            mant = 0;
+            half = (sign << 15) | ((e + 1) << 10);
+          } else {
+            half = (sign << 15) | (e << 10) | (mant >> 13);
+          }
+        } else {
+          half = (sign << 15) | (e << 10) | (mant >> 13);
+        }
+      }
+    }
+    view.setUint16(i * 2, half & 0xffff, true);
+  }
+  return out;
+}