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

package/src/frustum.ts

@@ -0,0 +1,240 @@
+// frustum.ts — view-frustum plane extraction and intersection tests (M1 / w4).
+//
+// Frustum representation: Float32Array(24) — 6 planes × 4 floats (nx, ny, nz, d) each,
+// normalized. Plane equation: nx*x + ny*y + nz*z + d = 0, positive side = inside frustum.
+//
+// Planes are extracted from a combined view-projection matrix (column-major) by
+// combining rows per the Gribb/Hartmann method (Gribb/Hartmann 2001 "Fast
+// Extraction of Viewing Frustum Planes from the World-View-Projection Matrix").
+// Plane normalization is built into fromViewProjection internally (D-6).
+//
+// Surface: create / fromViewProjection / intersectsBox / intersectsSphere.
+//
+// Related: requirements §AC-01 (frustum function signatures + test coverage);
+//          plan-strategy §D-6 (internal normalization).
+
+import type { Box3Like } from './box3';
+import type { Mat4Like, Vec3Like } from './types';
+
+/**
+ * Frustum storage: Float32Array(24) — 6 planes × 4 floats each (nx, ny, nz, d).
+ * Local brand (not part of the seven-piece SSOT; same rationale as Box3).
+ */
+export type Frustum = Float32Array & { readonly __frustum: void };
+
+/** Allocate a new Frustum (zero-initialized 6 planes). */
+export function create(): Frustum {
+  return new Float32Array(24) as Frustum;
+}
+
+/**
+ * Extract 6 frustum planes (left, right, bottom, top, near, far) from a
+ * combined view-projection matrix (column-major, right-handed).
+ *
+ * Uses Gribb/Hartmann method: each plane = sum or difference of VP rows,
+ * then normalized so (nx, ny, nz) is a unit vector and d is the signed
+ * distance from origin. Plane inside-half-space is nx*x + ny*y + nz*z + d > 0.
+ *
+ * Writes to `out` and returns it.
+ *
+ * @example
+ * ```ts
+ * const view = mat4.lookAt(mat4.create(), [0, 0, 5], [0, 0, 0], [0, 1, 0]);
+ * const proj = mat4.perspective(mat4.create(), Math.PI / 2, 1, 0.1, 100);
+ * const vp = mat4.create();
+ * mat4.multiply(vp, proj, view);
+ * const f = frustum.fromViewProjection(frustum.create(), vp);
+ * ```
+ */
+export function fromViewProjection(out: Frustum, vp: Mat4Like): Frustum {
+  const m0 = vp[0] as number;
+  const m1 = vp[1] as number;
+  const m2 = vp[2] as number;
+  const m3 = vp[3] as number;
+  const m4 = vp[4] as number;
+  const m5 = vp[5] as number;
+  const m6 = vp[6] as number;
+  const m7 = vp[7] as number;
+  const m8 = vp[8] as number;
+  const m9 = vp[9] as number;
+  const m10 = vp[10] as number;
+  const m11 = vp[11] as number;
+  const m12 = vp[12] as number;
+  const m13 = vp[13] as number;
+  const m14 = vp[14] as number;
+  const m15 = vp[15] as number;
+
+  // Left plane: row3 + row0
+  let nx = m3 + m0,
+    ny = m7 + m4,
+    nz = m11 + m8,
+    d = m15 + m12;
+  let len = Math.sqrt(nx * nx + ny * ny + nz * nz);
+  if (len > 0) {
+    const il = 1 / len;
+    nx *= il;
+    ny *= il;
+    nz *= il;
+    d *= il;
+  }
+  out[0] = nx;
+  out[1] = ny;
+  out[2] = nz;
+  out[3] = d;
+
+  // Right plane: row3 - row0
+  nx = m3 - m0;
+  ny = m7 - m4;
+  nz = m11 - m8;
+  d = m15 - m12;
+  len = Math.sqrt(nx * nx + ny * ny + nz * nz);
+  if (len > 0) {
+    const il = 1 / len;
+    nx *= il;
+    ny *= il;
+    nz *= il;
+    d *= il;
+  }
+  out[4] = nx;
+  out[5] = ny;
+  out[6] = nz;
+  out[7] = d;
+
+  // Bottom plane: row3 + row1
+  nx = m3 + m1;
+  ny = m7 + m5;
+  nz = m11 + m9;
+  d = m15 + m13;
+  len = Math.sqrt(nx * nx + ny * ny + nz * nz);
+  if (len > 0) {
+    const il = 1 / len;
+    nx *= il;
+    ny *= il;
+    nz *= il;
+    d *= il;
+  }
+  out[8] = nx;
+  out[9] = ny;
+  out[10] = nz;
+  out[11] = d;
+
+  // Top plane: row3 - row1
+  nx = m3 - m1;
+  ny = m7 - m5;
+  nz = m11 - m9;
+  d = m15 - m13;
+  len = Math.sqrt(nx * nx + ny * ny + nz * nz);
+  if (len > 0) {
+    const il = 1 / len;
+    nx *= il;
+    ny *= il;
+    nz *= il;
+    d *= il;
+  }
+  out[12] = nx;
+  out[13] = ny;
+  out[14] = nz;
+  out[15] = d;
+
+  // Near plane: row3 + row2
+  nx = m3 + m2;
+  ny = m7 + m6;
+  nz = m11 + m10;
+  d = m15 + m14;
+  len = Math.sqrt(nx * nx + ny * ny + nz * nz);
+  if (len > 0) {
+    const il = 1 / len;
+    nx *= il;
+    ny *= il;
+    nz *= il;
+    d *= il;
+  }
+  out[16] = nx;
+  out[17] = ny;
+  out[18] = nz;
+  out[19] = d;
+
+  // Far plane: row3 - row2
+  nx = m3 - m2;
+  ny = m7 - m6;
+  nz = m11 - m10;
+  d = m15 - m14;
+  len = Math.sqrt(nx * nx + ny * ny + nz * nz);
+  if (len > 0) {
+    const il = 1 / len;
+    nx *= il;
+    ny *= il;
+    nz *= il;
+    d *= il;
+  }
+  out[20] = nx;
+  out[21] = ny;
+  out[22] = nz;
+  out[23] = d;
+
+  return out;
+}
+
+/**
+ * Test whether an AABB intersects the frustum. Conservative: returns `true` when
+ * the box straddles a plane boundary, even if partially outside.
+ *
+ * For each plane, the signed distance of both the positive-most corner (p-vertex)
+ * and negative-most corner (n-vertex) are tested. The box is outside only when
+ * the p-vertex is on the negative side of any plane.
+ */
+export function intersectsBox(f: Frustum, box: Box3Like): boolean {
+  const bx = box[0] as number;
+  const by = box[1] as number;
+  const bz = box[2] as number;
+  const bX = box[3] as number;
+  const bY = box[4] as number;
+  const bZ = box[5] as number;
+
+  // For each plane, compute the p-vertex (most positive along plane normal)
+  // and test if it's on the negative side. If so, box is entirely outside.
+  for (let i = 0; i < 6; i++) {
+    const off = i * 4;
+    const nx = f[off] as number;
+    const ny = f[off + 1] as number;
+    const nz = f[off + 2] as number;
+    const d = f[off + 3] as number;
+
+    // p-vertex: corner maximizing dot(normal, corner) = corner select via sign of normal
+    const px = nx >= 0 ? bX : bx;
+    const py = ny >= 0 ? bY : by;
+    const pz = nz >= 0 ? bZ : bz;
+
+    if (nx * px + ny * py + nz * pz + d < 0) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Test whether a sphere intersects the frustum. Conservative: returns `true`
+ * when the sphere straddles a plane boundary.
+ *
+ * Computes signed distance from the sphere center to each plane;
+ * outside when distance < -radius.
+ */
+export function intersectsSphere(f: Frustum, center: Vec3Like, radius: number): boolean {
+  const cx = center[0] as number;
+  const cy = center[1] as number;
+  const cz = center[2] as number;
+
+  for (let i = 0; i < 6; i++) {
+    const off = i * 4;
+    const nx = f[off] as number;
+    const ny = f[off + 1] as number;
+    const nz = f[off + 2] as number;
+    const sd = f[off + 3] as number; // plane's d (signed distance from origin)
+
+    const dist = nx * cx + ny * cy + nz * cz + sd;
+    if (dist < -radius) {
+      return false;
+    }
+  }
+  return true;
+}

package/src/index.ts

@@ -0,0 +1,65 @@
+// @forgeax/engine-math — single-entry public API surface (D-P9 / AC-09)
+//
+// Shape: types SSOT top-level re-export + namespace `* as <ns>` wrappers.
+//
+// M1 placeholder state:
+//   - types.ts seven-piece brand established (T-002);
+//   - vec3 / mat4 / quat legacy implementations kept as baseline before M2 replacement;
+//   - vec2 / vec4 / mat3 / quat (new) / color / euler arrive incrementally in M2~M5.
+//
+// Design locks (research §F-3 V8 elements-kinds + plan-strategy §K-3 SoA alignment):
+//   - all numeric storage is Float32Array (types.ts brand)
+//   - sideEffects: false (package.json) lets bundlers tree-shake at namespace granularity
+//   - zero runtime dependencies (AC-16 + T-037 jq guard)
+//
+// Related: requirements §AC-09 single entry + top-level re-export;
+//          plan-strategy D-P9 no sub-path + §1.1 file layering.
+
+// === type SSOT top-level re-export ===
+export type {
+  Color,
+  ColorLike,
+  Euler,
+  EulerOrder,
+  Mat3,
+  Mat3Like,
+  Mat4,
+  Mat4Like,
+  Quat,
+  QuatLike,
+  Vec2,
+  Vec2Like,
+  Vec3,
+  Vec3Like,
+  Vec4,
+  Vec4Like,
+} from './types';
+
+// === namespace re-export ===
+//
+// Core 9 namespaces:
+//   - vector family vec2 / vec3 / vec4
+//   - matrix family mat3 / mat4
+//   - rotation quat / euler
+//   - color (sRGB↔linear + hex parse/format)
+//   - easing (scalar S-curve time remaps)
+//   - noise (Perlin noise, growable home for further variants)
+
+export * as box2 from './box2';
+export * as box3 from './box3';
+export * as circle2 from './circle2';
+export * as color from './color';
+export * as easing from './easing';
+export * as euler from './euler';
+export * as halfFloat from './f32-to-f16-bytes';
+export * as frustum from './frustum';
+export * as mat3 from './mat3';
+export * as mat4 from './mat4';
+export * as noise from './noise';
+export * as quat from './quat';
+export * as ray from './ray';
+export * as ray2 from './ray2';
+export * as sphere from './sphere';
+export * as vec2 from './vec2';
+export * as vec3 from './vec3';
+export * as vec4 from './vec4';

package/src/mat3.ts

@@ -0,0 +1,286 @@
+// mat3.ts — 3x3 matrix namespace (M3 / T-020)
+//
+// 10-function surface (≥ 10 lower bound):
+//   create / clone / identity / equals / multiply / transpose / invert /
+//   scale / fromMat4 / normalMatrix
+//
+// Memory layout lock (D-P4): 9 floats packed column-major; index mapping m[col*3 + row].
+// Primary use: CPU normal matrix (normalMatrix = transpose(invert(upper-left mat3 of mat4)));
+// callers that upload directly to a GPU UBO should pad to mat4 themselves
+// (see R4 + the reserved toGpuLayout hook).
+//
+// Degenerate convention (same as D-P1): invert(singular) → write identity into out, return out (does not return null).
+//
+// Four ironclad rules (gl-matrix wiki / research §F1):
+//   1. Out-param first (except for query functions, the first parameter = out, return out)
+//   2. Aliasing-safe (out may equal an input; read all source data into locals first)
+//   3. Module-as-namespace (pure functions; no class, no this)
+//   4. Float32Array by default (V8 elements-kinds consistency)
+//
+// Related: requirements §Surface mat3 lower bound 10 + AC-04 (normalMatrix);
+//          plan-strategy D-P4 9-float lock + D-P1 invert writes identity;
+//          wiki/gl-matrix-overview Out-param four ironclad rules;
+//          wiki/typescript-branded-types §7.2 factory template.
+//
+// Degenerate-semantics registry (plan-strategy.md §appendix A; shares numbering #3 with mat4):
+//   - mat3.invert(singular)        → out = identity (same convention as D-P1)
+//   - mat3.normalMatrix(singular)  → out = identity (via the internal branch in mat3.invert)
+
+import { EPS_DET } from './_internal/epsilon';
+import type { Mat3, Mat3Like, Mat4Like, Vec3Like } from './types';
+
+export type { Mat3, Mat3Like };
+
+/** Create a Mat3 (default all zero; callers usually call identity() right after). */
+export function create(): Mat3 {
+  return new Float32Array(9) as Mat3;
+}
+
+/** Allocate a new Mat3 copy. */
+export function clone(a: Mat3Like): Mat3 {
+  return Float32Array.of(
+    a[0] as number,
+    a[1] as number,
+    a[2] as number,
+    a[3] as number,
+    a[4] as number,
+    a[5] as number,
+    a[6] as number,
+    a[7] as number,
+    a[8] as number,
+  ) as Mat3;
+}
+
+/** out = 3x3 identity (column-major [1,0,0, 0,1,0, 0,0,1]). Returns out. */
+export function identity(out: Mat3): Mat3 {
+  out[0] = 1;
+  out[1] = 0;
+  out[2] = 0;
+  out[3] = 0;
+  out[4] = 1;
+  out[5] = 0;
+  out[6] = 0;
+  out[7] = 0;
+  out[8] = 1;
+  return out;
+}
+
+/** Approximate equality: each element differs by ≤ epsilon. NaN inputs always return false. */
+export function equals(a: Mat3Like, b: Mat3Like, epsilon = 1e-6): boolean {
+  for (let i = 0; i < 9; i++) {
+    const av = a[i] as number;
+    const bv = b[i] as number;
+    if (Number.isNaN(av) || Number.isNaN(bv)) return false;
+    if (Math.abs(av - bv) > epsilon) return false;
+  }
+  return true;
+}
+
+/**
+ * out = a * b (column-major matrix multiply). Returns out.
+ *
+ * Aliasing-safe: out may equal a or b; reads all 18 source elements into locals first.
+ */
+export function multiply(out: Mat3, a: Mat3Like, b: Mat3Like): Mat3 {
+  const a00 = a[0] as number;
+  const a01 = a[1] as number;
+  const a02 = a[2] as number;
+  const a10 = a[3] as number;
+  const a11 = a[4] as number;
+  const a12 = a[5] as number;
+  const a20 = a[6] as number;
+  const a21 = a[7] as number;
+  const a22 = a[8] as number;
+  const b00 = b[0] as number;
+  const b01 = b[1] as number;
+  const b02 = b[2] as number;
+  const b10 = b[3] as number;
+  const b11 = b[4] as number;
+  const b12 = b[5] as number;
+  const b20 = b[6] as number;
+  const b21 = b[7] as number;
+  const b22 = b[8] as number;
+  out[0] = a00 * b00 + a10 * b01 + a20 * b02;
+  out[1] = a01 * b00 + a11 * b01 + a21 * b02;
+  out[2] = a02 * b00 + a12 * b01 + a22 * b02;
+  out[3] = a00 * b10 + a10 * b11 + a20 * b12;
+  out[4] = a01 * b10 + a11 * b11 + a21 * b12;
+  out[5] = a02 * b10 + a12 * b11 + a22 * b12;
+  out[6] = a00 * b20 + a10 * b21 + a20 * b22;
+  out[7] = a01 * b20 + a11 * b21 + a21 * b22;
+  out[8] = a02 * b20 + a12 * b21 + a22 * b22;
+  return out;
+}
+
+/**
+ * out = transpose(a). Returns out.
+ *
+ * Aliasing-safe (transpose(m, m) is legal; reads the 6 off-diagonal elements into locals first).
+ */
+export function transpose(out: Mat3, a: Mat3Like): Mat3 {
+  const a01 = a[1] as number;
+  const a02 = a[2] as number;
+  const a12 = a[5] as number;
+  const a10 = a[3] as number;
+  const a20 = a[6] as number;
+  const a21 = a[7] as number;
+  out[0] = a[0] as number;
+  out[1] = a10;
+  out[2] = a20;
+  out[3] = a01;
+  out[4] = a[4] as number;
+  out[5] = a21;
+  out[6] = a02;
+  out[7] = a12;
+  out[8] = a[8] as number;
+  return out;
+}
+
+/**
+ * out = invert(a). Returns out.
+ *
+ * @degrade a singular (|det| < EPS_DET) → out = identity (same convention as D-P1; does not return null).
+ *
+ * @example
+ * ```ts
+ * // Caller-side guard:
+ * const det = mat3DetForGuard(m); // caller computes det to decide whether to invert
+ * const inv = mat3.invert(mat3.create(), m);
+ * // If m is singular, inv === identity (no NaN; safe to keep using).
+ * ```
+ */
+export function invert(out: Mat3, a: Mat3Like): Mat3 {
+  const a00 = a[0] as number;
+  const a01 = a[1] as number;
+  const a02 = a[2] as number;
+  const a10 = a[3] as number;
+  const a11 = a[4] as number;
+  const a12 = a[5] as number;
+  const a20 = a[6] as number;
+  const a21 = a[7] as number;
+  const a22 = a[8] as number;
+
+  // cofactors (column-major → derive from row/col indices)
+  const b01 = a22 * a11 - a12 * a21;
+  const b11 = -a22 * a10 + a12 * a20;
+  const b21 = a21 * a10 - a11 * a20;
+  const det = a00 * b01 + a01 * b11 + a02 * b21;
+
+  if (Math.abs(det) < EPS_DET) {
+    return identity(out);
+  }
+
+  const invDet = 1 / det;
+  out[0] = b01 * invDet;
+  out[1] = (-a22 * a01 + a02 * a21) * invDet;
+  out[2] = (a12 * a01 - a02 * a11) * invDet;
+  out[3] = b11 * invDet;
+  out[4] = (a22 * a00 - a02 * a20) * invDet;
+  out[5] = (-a12 * a00 + a02 * a10) * invDet;
+  out[6] = b21 * invDet;
+  out[7] = (-a21 * a00 + a01 * a20) * invDet;
+  out[8] = (a11 * a00 - a01 * a10) * invDet;
+  return out;
+}
+
+/**
+ * out = a * Scale(v) (per-column scale). Returns out.
+ *
+ * v takes the first 3 components (aligned with mat4.scale's vec3 input); mat3's third column is the z scale.
+ */
+export function scale(out: Mat3, a: Mat3Like, v: Vec3Like): Mat3 {
+  const x = v[0] as number;
+  const y = v[1] as number;
+  const z = v[2] as number;
+  out[0] = (a[0] as number) * x;
+  out[1] = (a[1] as number) * x;
+  out[2] = (a[2] as number) * x;
+  out[3] = (a[3] as number) * y;
+  out[4] = (a[4] as number) * y;
+  out[5] = (a[5] as number) * y;
+  out[6] = (a[6] as number) * z;
+  out[7] = (a[7] as number) * z;
+  out[8] = (a[8] as number) * z;
+  return out;
+}
+
+/**
+ * out = mat3 extracted from mat4's upper-left 3x3 (drop the 4th row and 4th column). Returns out.
+ *
+ * Column-major mapping: mat4 col0 [0..2] / col1 [4..6] / col2 [8..10] → mat3 col0/1/2.
+ */
+export function fromMat4(out: Mat3, m: Mat4Like): Mat3 {
+  out[0] = m[0] as number;
+  out[1] = m[1] as number;
+  out[2] = m[2] as number;
+  out[3] = m[4] as number;
+  out[4] = m[5] as number;
+  out[5] = m[6] as number;
+  out[6] = m[8] as number;
+  out[7] = m[9] as number;
+  out[8] = m[10] as number;
+  return out;
+}
+
+/**
+ * out = transpose(invert(upper-left 3x3 of m)) (the normal-transform matrix). Returns out.
+ *
+ * Used to transform normals from model space to world / view space; when m has a non-uniform
+ * scale, normals must use normalMatrix (the upper-left 3x3 of m alone is incorrect).
+ *
+ * Per-frame consumer: feat-20260518-pbr-direct-lighting-mvp M3 / w14 wires
+ * `render-system-record.ts` to call this helper once per renderable per frame
+ * (host-side computation; result lives in mesh SSBO `normalMatrix` slot at
+ * byte offset 64 within each PER_ENTITY_STRIDE = 256 B slot, plan-strategy
+ * D-5 + AC-08).
+ *
+ * @degrade upper-left 3x3 singular -> out = identity (same convention as D-P1, via mat3.invert).
+ *
+ * @example
+ * ```ts
+ * const N = mat3.normalMatrix(mat3.create(), modelViewMat);
+ * // vertex shader: normal_view = N * normal_model
+ * ```
+ */
+export function normalMatrix(out: Mat3, m: Mat4Like): Mat3 {
+  // 1. extract the upper-left 3x3
+  const m00 = m[0] as number;
+  const m01 = m[1] as number;
+  const m02 = m[2] as number;
+  const m10 = m[4] as number;
+  const m11 = m[5] as number;
+  const m12 = m[6] as number;
+  const m20 = m[8] as number;
+  const m21 = m[9] as number;
+  const m22 = m[10] as number;
+
+  // 2. inline invert + transpose (combine the two steps; avoid a temporary allocation)
+  const b01 = m22 * m11 - m12 * m21;
+  const b11 = -m22 * m10 + m12 * m20;
+  const b21 = m21 * m10 - m11 * m20;
+  const det = m00 * b01 + m01 * b11 + m02 * b21;
+
+  if (Math.abs(det) < EPS_DET) {
+    return identity(out);
+  }
+
+  const invDet = 1 / det;
+  // Elements of invert(upper-left), then transpose (swap rows/cols)
+  // invert column-major:
+  //   inv[0]=b01*invDet      inv[3]=b11*invDet      inv[6]=b21*invDet
+  //   inv[1]=...              inv[4]=...              inv[7]=...
+  //   inv[2]=...              inv[5]=...              inv[8]=...
+  // After transpose (i, j) = inv (j, i)
+  // More directly: transposing the invert result = transpose(invert).
+  // The transpose(invert) elements are written out below:
+  out[0] = b01 * invDet;
+  out[3] = (-m22 * m01 + m02 * m21) * invDet;
+  out[6] = (m12 * m01 - m02 * m11) * invDet;
+  out[1] = b11 * invDet;
+  out[4] = (m22 * m00 - m02 * m20) * invDet;
+  out[7] = (-m12 * m00 + m02 * m10) * invDet;
+  out[2] = b21 * invDet;
+  out[5] = (-m21 * m00 + m01 * m20) * invDet;
+  out[8] = (m11 * m00 - m01 * m10) * invDet;
+  return out;
+}