@solidrt/3d 0.0.54 → 0.0.56

package/src/math.ts

@@ -99,6 +99,54 @@ export function invertAffine(out: Mat4, m: Mat4): Mat4 {
   return out
 }
 
+/**
+ * Invert a GENERAL matrix - a projection or a view-projection, where
+ * invertAffine's bottom-row shortcut does not hold. The camera's
+ * uInvViewProj (a world-space ray from a clip position) is the consumer;
+ * a world matrix should keep using invertAffine. `out` may alias `m`. A
+ * singular matrix yields the raw adjugate instead of NaNs, the same policy
+ * as invertAffine.
+ */
+export function invert(out: Mat4, m: Mat4): Mat4 {
+  let a00 = m[0], a01 = m[1], a02 = m[2], a03 = m[3]
+  let a10 = m[4], a11 = m[5], a12 = m[6], a13 = m[7]
+  let a20 = m[8], a21 = m[9], a22 = m[10], a23 = m[11]
+  let a30 = m[12], a31 = m[13], a32 = m[14], a33 = m[15]
+  // The twelve 2x2 minors every cofactor is built from (Laplace on pairs
+  // of rows), so each of the sixteen entries costs two multiplies.
+  let b00 = a00 * a11 - a01 * a10
+  let b01 = a00 * a12 - a02 * a10
+  let b02 = a00 * a13 - a03 * a10
+  let b03 = a01 * a12 - a02 * a11
+  let b04 = a01 * a13 - a03 * a11
+  let b05 = a02 * a13 - a03 * a12
+  let b06 = a20 * a31 - a21 * a30
+  let b07 = a20 * a32 - a22 * a30
+  let b08 = a20 * a33 - a23 * a30
+  let b09 = a21 * a32 - a22 * a31
+  let b10 = a21 * a33 - a23 * a31
+  let b11 = a22 * a33 - a23 * a32
+  let det = b00 * b11 - b01 * b10 + b02 * b09 + b03 * b08 - b04 * b07 + b05 * b06
+  let s = 1 / (det || 1)
+  out[0] = (a11 * b11 - a12 * b10 + a13 * b09) * s
+  out[1] = (a02 * b10 - a01 * b11 - a03 * b09) * s
+  out[2] = (a31 * b05 - a32 * b04 + a33 * b03) * s
+  out[3] = (a22 * b04 - a21 * b05 - a23 * b03) * s
+  out[4] = (a12 * b08 - a10 * b11 - a13 * b07) * s
+  out[5] = (a00 * b11 - a02 * b08 + a03 * b07) * s
+  out[6] = (a32 * b02 - a30 * b05 - a33 * b01) * s
+  out[7] = (a20 * b05 - a22 * b02 + a23 * b01) * s
+  out[8] = (a10 * b10 - a11 * b08 + a13 * b06) * s
+  out[9] = (a01 * b08 - a00 * b10 - a03 * b06) * s
+  out[10] = (a30 * b04 - a31 * b02 + a33 * b00) * s
+  out[11] = (a21 * b02 - a20 * b04 - a23 * b00) * s
+  out[12] = (a11 * b07 - a10 * b09 - a12 * b06) * s
+  out[13] = (a00 * b09 - a01 * b07 + a02 * b06) * s
+  out[14] = (a31 * b01 - a30 * b03 - a32 * b00) * s
+  out[15] = (a20 * b03 - a21 * b01 + a22 * b00) * s
+  return out
+}
+
 /** out = a * b (column vectors: b applies first). out may alias a or b. */
 export function multiply(out: Mat4, a: Mat4, b: Mat4): Mat4 {
   let a00 = a[0], a01 = a[1], a02 = a[2], a03 = a[3]
@@ -174,6 +222,68 @@ export function normalMatrix(out: Mat4, m: Mat4): Mat4 {
   return out
 }
 
+/** The determinant of a matrix's upper 3x3 - negative means the transform
+ * mirrors (flips handedness, and with it triangle winding). */
+export function det3(m: Mat4): number {
+  return (
+    m[0] * (m[5] * m[10] - m[6] * m[9]) -
+    m[4] * (m[1] * m[10] - m[2] * m[9]) +
+    m[8] * (m[1] * m[6] - m[2] * m[5])
+  )
+}
+
+/**
+ * Split an affine matrix into the TRS `compose()` builds: translation from
+ * the last column, scale from the basis column lengths (x negated when the
+ * matrix mirrors, so `compose(decompose(m))` keeps the handedness), and the
+ * rotation from the scale-normalized basis. Lossy for a SHEARED matrix -
+ * TRS cannot represent shear, so it is silently dropped; a zero-scale axis
+ * yields a best-effort unit rotation rather than NaNs.
+ */
+export function decompose(m: Mat4, position: Vec3, rotation: Quat, scale: Vec3): void {
+  position[0] = m[12]; position[1] = m[13]; position[2] = m[14]
+  let sx = Math.hypot(m[0], m[1], m[2])
+  let sy = Math.hypot(m[4], m[5], m[6])
+  let sz = Math.hypot(m[8], m[9], m[10])
+  if (det3(m) < 0) sx = -sx
+  scale[0] = sx; scale[1] = sy; scale[2] = sz
+  let ix = sx === 0 ? 0 : 1 / sx
+  let iy = sy === 0 ? 0 : 1 / sy
+  let iz = sz === 0 ? 0 : 1 / sz
+  // Row-major elements of the pure-rotation 3x3 (columns un-scaled).
+  let r00 = m[0] * ix, r01 = m[4] * iy, r02 = m[8] * iz
+  let r10 = m[1] * ix, r11 = m[5] * iy, r12 = m[9] * iz
+  let r20 = m[2] * ix, r21 = m[6] * iy, r22 = m[10] * iz
+  // Shepperd's method: branch on the largest diagonal term for stability.
+  let trace = r00 + r11 + r22
+  if (trace > 0) {
+    let s = Math.sqrt(trace + 1) * 2
+    rotation[3] = s / 4
+    rotation[0] = (r21 - r12) / s
+    rotation[1] = (r02 - r20) / s
+    rotation[2] = (r10 - r01) / s
+  } else if (r00 > r11 && r00 > r22) {
+    let s = Math.sqrt(1 + r00 - r11 - r22) * 2
+    rotation[3] = (r21 - r12) / s
+    rotation[0] = s / 4
+    rotation[1] = (r01 + r10) / s
+    rotation[2] = (r02 + r20) / s
+  } else if (r11 > r22) {
+    let s = Math.sqrt(1 + r11 - r00 - r22) * 2
+    rotation[3] = (r02 - r20) / s
+    rotation[0] = (r01 + r10) / s
+    rotation[1] = s / 4
+    rotation[2] = (r12 + r21) / s
+  } else {
+    let s = Math.sqrt(1 + r22 - r00 - r11) * 2
+    rotation[3] = (r10 - r01) / s
+    rotation[0] = (r02 + r20) / s
+    rotation[1] = (r12 + r21) / s
+    rotation[2] = s / 4
+  }
+  quatNormalize(rotation, rotation)
+}
+
 /**
  * Right-handed perspective projection with the engine's y-down clip flip
  * BAKED IN (row two is negated): geometry authored y-up displays y-up, and