@woosh/meep-engine 3.61.2 → 3.62.0

package/src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_determinant.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Determinant of a 3×3 as the triple product of its columns, `dot(m[0], cross(m[1], m[2]))`. Same
+ * expression as {@link m4_linear_determinant}, the CPU twin of `mat4_linear_determinant`, which
+ * reads it through this.
+ *
+ * Written out rather than left to WGSL's `determinant`. The specification gives that builtin no
+ * accuracy at all ("Infinite ULP"), each backend expands it its own way, and no CPU model can stand
+ * in for it. This expression's accuracy is what `dot` and `cross` inherit from their operations. It
+ * is exactly zero for a column of zeros at any rotation, because every term of the expansion
+ * carries a factor from that column, even where the backend fuses the products.
+ *
+ * A caller dividing by a determinant tests that very number, not another expansion of it. Two
+ * expansions agree in exact arithmetic but not in f32, and near a singular matrix one can read zero
+ * where the other does not.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_mat3_determinant: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_mat3_determinant.d.ts.map

package/src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_determinant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_mat3_determinant.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_determinant.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,qCAFU,SAAS,CAQZ;0BAzBmB,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_determinant.js

@@ -0,0 +1,26 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+
+/**
+ * Determinant of a 3×3 as the triple product of its columns, `dot(m[0], cross(m[1], m[2]))`. Same
+ * expression as {@link m4_linear_determinant}, the CPU twin of `mat4_linear_determinant`, which
+ * reads it through this.
+ *
+ * Written out rather than left to WGSL's `determinant`. The specification gives that builtin no
+ * accuracy at all ("Infinite ULP"), each backend expands it its own way, and no CPU model can stand
+ * in for it. This expression's accuracy is what `dot` and `cross` inherit from their operations. It
+ * is exactly zero for a column of zeros at any rotation, because every term of the expansion
+ * carries a factor from that column, even where the backend fuses the products.
+ *
+ * A caller dividing by a determinant tests that very number, not another expansion of it. Two
+ * expansions agree in exact arithmetic but not in f32, and near a singular matrix one can read zero
+ * where the other does not.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_mat3_determinant = CodeChunk.from(
+    //language=WGSL
+    `
+fn mat3_determinant(m: mat3x3<f32>) -> f32 {
+    return dot(m[0], cross(m[1], m[2]));
+}
+`, []);

package/src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_singular_values.d.ts

@@ -1,5 +1,10 @@
 /**
- * The largest and smallest singular values of a 3×3 matrix.
+ * The largest and smallest singular values of a 3×3 matrix. **Expensive but correct**: a couple of
+ * hundred ALU operations, a transcendental pair and a handful of square roots, where the longest
+ * and shortest column (`mat4_extract_scale`) cost three lengths. Those are the same numbers for any
+ * rotation times a scale, and the real-time paths (virtual geometry's cut, the probe clipmap's
+ * bricks) read the columns and accept that a shear goes unaccounted. Reach for this only where a
+ * shear has to be measured, and not per instance per view per frame.
  *
  * They are what "how much does this transform stretch a distance" actually means: a vector's length
  * is scaled by something between σ_min and σ_max, and both bounds are attained. Column lengths are
@@ -7,23 +12,60 @@
  * `[[1,0,0],[k,1,0],[0,0,1]]`, every column has length 1 or √(1+k²) while the true ratio grows
  * without bound in `k`. A shear has no scale in any column and stretches space anyway.
  *
- * Computed as the square roots of the eigenvalues of `MᵀM`, which is symmetric and positive
- * semi-definite, through the closed form for a symmetric 3×3 (Smith 1961). No iteration, no
- * branching past the diagonal case, and **exact for a uniform scale**: `MᵀM` is then `s²I`, the
- * off-diagonal sum is zero, and both values come back as `s`. That matters more than the general
- * case — a conservative bound that answered 5.2 for an unscaled instance would over-refine every
- * ordinary object in a scene to buy correctness for a sheared one.
- *
- * **Not a degeneracy test.** σ_min is zero exactly when the matrix is singular *in exact
- * arithmetic*, and this once said so without the qualifier. In f32 it holds only on the diagonal
- * branch: the trigonometric one computes the smallest eigenvalue as a difference of nearly equal
- * numbers, and the `sqrt` turns its absolute error of about `eps·σ_max²` into about
- * `sqrt(eps)·σ_max ≈ 3.4e-4·σ_max` in σ_min. A rotated matrix with one column of zeros therefore
- * comes back with a σ_min near 1e-4 rather than 0, and a caller testing `σ_min > 0` before
- * inverting is let through with the NaN it was guarding against
- * (`shader_vgeo_cut_collect`, REVIEW_LEDGER M3). A caller about to invert should test the
- * **determinant**, which is the number the inverse divides by and which is exactly zero whenever a
- * column is.
+ * **Method.** M is first scaled by the power of two that brings its largest entry into [1, 2), and
+ * the values are scaled back at the end. That is exact, and it keeps every square and product below
+ * far inside f32's range whatever the transform's scale.
+ *
+ * The eigenvalues of `MᵀM` are the squared singular values, and Smith's closed form (1961) gives
+ * them as `q + p·β` for the roots `β = 2cos(φ + 2πk/3)` of `β³ − 3β − det B`, with
+ * `B = (MᵀM − qI) / p`. Only one root is taken from that form: the one that stands apart from the
+ * other two, which is the largest when `det B ≥ 0` and the smallest otherwise (Scherzinger &
+ * Dohrmann 2008; Eberly, "A Robust Eigensolver for 3×3 Symmetric Matrices"). The other two are
+ * ill-conditioned where two roots meet: `det(B)/2` then sits at ±1, the edge of `acos`'s domain, so
+ * one rounding of it moves φ by `acos(1 − 2⁻²⁴)/3 ≈ 1.2e-4`, and those two roots by √3·p times
+ * that. For a beam-like scale p is a third of σ_max², which is enough to take σ_min to zero. The
+ * root that stands apart is stationary in φ at both edges, and lies at least √3 from the others,
+ * where the cubic's slope `3(β² − 1)` is at least 6. One Newton step there squares whatever error
+ * the device's `cos` and `acos` leave, which WGSL bounds only loosely.
+ *
+ * That root is used only for its eigenvector `v`. `B − βI` has rank two, and the longest cross
+ * product of two of its rows is normal to both. The complement of `v` is built from `v`'s own
+ * components (Eberly's `ComputeOrthogonalComplement`): `u` is `v` crossed with `e_y` or `e_x`,
+ * whichever `v` leans on less, and `w = v × u`. So `u` and `w` are off from `v` by no more than the
+ * rounding of `v`'s smaller components. That matters, because any component of `v` in the plane
+ * lets σ_max leak into the plane's values, which feel it squared and amplified by (σ_max / σ_mid)².
+ *
+ * Every value returned is measured on M itself, because a small singular value cannot come from
+ * `MᵀM`: its rounding is absolute, at the scale of σ_max² (Demmel & Veselić 1992). `v` and the plane
+ * split M into `|Mv|` and the 3×2 `[Mu Mw]`, whose larger singular value comes out of a 2×2 form
+ * with no cancellation in it. That gives σ_max and σ_mid, and σ_min = |det M| / (σ_max · σ_mid).
+ *
+ * **Contract.**
+ *
+ * - **Exact when `MᵀM` comes out diagonal**: any axis-aligned scale, the identity and a uniform
+ *   scale among them. Both values are then square roots of the diagonal's extremes, scaled back by
+ *   the same power of two, so a uniform scale returns σ_max equal to σ_min, and both are the column
+ *   lengths to the accuracy of the device's `sqrt`. That matters more than the general case: a
+ *   conservative bound that answered 5.2 for an unscaled instance would over-refine every ordinary
+ *   object in a scene to buy correctness for a sheared one.
+ * - **Otherwise each value carries a relative error of order `u·K`**, with `u = 2⁻²⁴` and
+ *   `K = |m₀|·|m₁|·|m₂| / |det M| ≥ 1`. `K` is 1 when the columns are orthogonal: a rotation times
+ *   any scale, whatever the ratio of the scales. Rounding in `det M`, and in the three images of M,
+ *   is first order in `u·K`. The eigenvector's own error enters at second order, amplified by
+ *   (σ_max / σ_mid)². With orthogonal columns `v` lies on an axis to within u / (σ_max / σ_mid), so
+ *   that term stays below u. Otherwise σ_max / σ_mid is itself bounded by a multiple of K, so the
+ *   term stays below u·K while u·K is small.
+ * - **Either direction for σ_min, so it can over-estimate, but never past the shortest column's
+ *   length** as f32 computes it. σ_max can only fall short, and never below the longest column's
+ *   length. Every column is an image of a unit vector, so its length lies in [σ_min, σ_max] exactly,
+ *   and the result is held to both bounds. It follows that σ_min ≤ σ_max.
+ * - **σ_min is zero exactly when `mat3_determinant(M)` is**, or when it underflows. A column or a
+ *   row of zeros gives exactly zero at every rotation. A matrix that is singular only in exact
+ *   arithmetic, such as a child turned under a flattened parent, has a determinant of rounding noise,
+ *   and so a σ_min of the same noise rather than zero. A caller about to divide by a determinant
+ *   tests that very number: another expansion can differ from this one in rounding, enough to
+ *   disagree about zero near a singular matrix.
+ * - Valid for any finite M. Values below f32's normal range flush where the device flushes.
  *
  * @type {CodeChunk}
  *

package/src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_singular_values.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_mat3_singular_values.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_singular_values.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,yCALU,SAAS,CA6DZ;0BA1FmB,gCAAgC"}
+{"version":3,"file":"chunk_mat3_singular_values.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_singular_values.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,yCALU,SAAS,CAuI0B;0BAhNnB,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_singular_values.js

@@ -1,7 +1,14 @@
 import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { PI_DECLARATION } from "../../math/PI_DECLARATION.js";
+import { chunk_mat3_determinant } from "./chunk_mat3_determinant.js";
 
 /**
- * The largest and smallest singular values of a 3×3 matrix.
+ * The largest and smallest singular values of a 3×3 matrix. **Expensive but correct**: a couple of
+ * hundred ALU operations, a transcendental pair and a handful of square roots, where the longest
+ * and shortest column (`mat4_extract_scale`) cost three lengths. Those are the same numbers for any
+ * rotation times a scale, and the real-time paths (virtual geometry's cut, the probe clipmap's
+ * bricks) read the columns and accept that a shear goes unaccounted. Reach for this only where a
+ * shear has to be measured, and not per instance per view per frame.
  *
  * They are what "how much does this transform stretch a distance" actually means: a vector's length
  * is scaled by something between σ_min and σ_max, and both bounds are attained. Column lengths are
@@ -9,23 +16,60 @@ import { CodeChunk } from "../../../compiler/CodeChunk.js";
  * `[[1,0,0],[k,1,0],[0,0,1]]`, every column has length 1 or √(1+k²) while the true ratio grows
  * without bound in `k`. A shear has no scale in any column and stretches space anyway.
  *
- * Computed as the square roots of the eigenvalues of `MᵀM`, which is symmetric and positive
- * semi-definite, through the closed form for a symmetric 3×3 (Smith 1961). No iteration, no
- * branching past the diagonal case, and **exact for a uniform scale**: `MᵀM` is then `s²I`, the
- * off-diagonal sum is zero, and both values come back as `s`. That matters more than the general
- * case — a conservative bound that answered 5.2 for an unscaled instance would over-refine every
- * ordinary object in a scene to buy correctness for a sheared one.
+ * **Method.** M is first scaled by the power of two that brings its largest entry into [1, 2), and
+ * the values are scaled back at the end. That is exact, and it keeps every square and product below
+ * far inside f32's range whatever the transform's scale.
  *
- * **Not a degeneracy test.** σ_min is zero exactly when the matrix is singular *in exact
- * arithmetic*, and this once said so without the qualifier. In f32 it holds only on the diagonal
- * branch: the trigonometric one computes the smallest eigenvalue as a difference of nearly equal
- * numbers, and the `sqrt` turns its absolute error of about `eps·σ_max²` into about
- * `sqrt(eps)·σ_max ≈ 3.4e-4·σ_max` in σ_min. A rotated matrix with one column of zeros therefore
- * comes back with a σ_min near 1e-4 rather than 0, and a caller testing `σ_min > 0` before
- * inverting is let through with the NaN it was guarding against
- * (`shader_vgeo_cut_collect`, REVIEW_LEDGER M3). A caller about to invert should test the
- * **determinant**, which is the number the inverse divides by and which is exactly zero whenever a
- * column is.
+ * The eigenvalues of `MᵀM` are the squared singular values, and Smith's closed form (1961) gives
+ * them as `q + p·β` for the roots `β = 2cos(φ + 2πk/3)` of `β³ − 3β − det B`, with
+ * `B = (MᵀM − qI) / p`. Only one root is taken from that form: the one that stands apart from the
+ * other two, which is the largest when `det B ≥ 0` and the smallest otherwise (Scherzinger &
+ * Dohrmann 2008; Eberly, "A Robust Eigensolver for 3×3 Symmetric Matrices"). The other two are
+ * ill-conditioned where two roots meet: `det(B)/2` then sits at ±1, the edge of `acos`'s domain, so
+ * one rounding of it moves φ by `acos(1 − 2⁻²⁴)/3 ≈ 1.2e-4`, and those two roots by √3·p times
+ * that. For a beam-like scale p is a third of σ_max², which is enough to take σ_min to zero. The
+ * root that stands apart is stationary in φ at both edges, and lies at least √3 from the others,
+ * where the cubic's slope `3(β² − 1)` is at least 6. One Newton step there squares whatever error
+ * the device's `cos` and `acos` leave, which WGSL bounds only loosely.
+ *
+ * That root is used only for its eigenvector `v`. `B − βI` has rank two, and the longest cross
+ * product of two of its rows is normal to both. The complement of `v` is built from `v`'s own
+ * components (Eberly's `ComputeOrthogonalComplement`): `u` is `v` crossed with `e_y` or `e_x`,
+ * whichever `v` leans on less, and `w = v × u`. So `u` and `w` are off from `v` by no more than the
+ * rounding of `v`'s smaller components. That matters, because any component of `v` in the plane
+ * lets σ_max leak into the plane's values, which feel it squared and amplified by (σ_max / σ_mid)².
+ *
+ * Every value returned is measured on M itself, because a small singular value cannot come from
+ * `MᵀM`: its rounding is absolute, at the scale of σ_max² (Demmel & Veselić 1992). `v` and the plane
+ * split M into `|Mv|` and the 3×2 `[Mu Mw]`, whose larger singular value comes out of a 2×2 form
+ * with no cancellation in it. That gives σ_max and σ_mid, and σ_min = |det M| / (σ_max · σ_mid).
+ *
+ * **Contract.**
+ *
+ * - **Exact when `MᵀM` comes out diagonal**: any axis-aligned scale, the identity and a uniform
+ *   scale among them. Both values are then square roots of the diagonal's extremes, scaled back by
+ *   the same power of two, so a uniform scale returns σ_max equal to σ_min, and both are the column
+ *   lengths to the accuracy of the device's `sqrt`. That matters more than the general case: a
+ *   conservative bound that answered 5.2 for an unscaled instance would over-refine every ordinary
+ *   object in a scene to buy correctness for a sheared one.
+ * - **Otherwise each value carries a relative error of order `u·K`**, with `u = 2⁻²⁴` and
+ *   `K = |m₀|·|m₁|·|m₂| / |det M| ≥ 1`. `K` is 1 when the columns are orthogonal: a rotation times
+ *   any scale, whatever the ratio of the scales. Rounding in `det M`, and in the three images of M,
+ *   is first order in `u·K`. The eigenvector's own error enters at second order, amplified by
+ *   (σ_max / σ_mid)². With orthogonal columns `v` lies on an axis to within u / (σ_max / σ_mid), so
+ *   that term stays below u. Otherwise σ_max / σ_mid is itself bounded by a multiple of K, so the
+ *   term stays below u·K while u·K is small.
+ * - **Either direction for σ_min, so it can over-estimate, but never past the shortest column's
+ *   length** as f32 computes it. σ_max can only fall short, and never below the longest column's
+ *   length. Every column is an image of a unit vector, so its length lies in [σ_min, σ_max] exactly,
+ *   and the result is held to both bounds. It follows that σ_min ≤ σ_max.
+ * - **σ_min is zero exactly when `mat3_determinant(M)` is**, or when it underflows. A column or a
+ *   row of zeros gives exactly zero at every rotation. A matrix that is singular only in exact
+ *   arithmetic, such as a child turned under a flattened parent, has a determinant of rounding noise,
+ *   and so a σ_min of the same noise rather than zero. A caller about to divide by a determinant
+ *   tests that very number: another expansion can differ from this one in rounding, enough to
+ *   disagree about zero near a singular matrix.
+ * - Valid for any finite M. Values below f32's normal range flush where the device flushes.
  *
  * @type {CodeChunk}
  *
@@ -38,8 +82,21 @@ export const chunk_mat3_singular_values = CodeChunk.from(
 /**
  * @returns (largest, smallest) singular value
  */
-fn mat3_singular_values(m: mat3x3<f32>) -> vec2<f32> {
-    // MtM, symmetric and positive semi-definite; its eigenvalues are the squared singular values
+fn mat3_singular_values(input: mat3x3<f32>) -> vec2<f32> {
+    /*
+     The power of two that takes the largest entry into [1, 2), and its inverse, both built from the
+     entry's exponent bits so that each is exact; clamped to the normal exponents, so that a zero
+     matrix stays zero and nothing short of infinity overflows.
+     */
+    let magnitudes = max(abs(input[0]), max(abs(input[1]), abs(input[2])));
+    let exponent = clamp(
+        bitcast<u32>(max(magnitudes.x, max(magnitudes.y, magnitudes.z))) & 0x7f800000u,
+        0x00800000u, 0x7e800000u
+    );
+    let unit = bitcast<f32>(exponent);
+    let m = input * bitcast<f32>(0x7f000000u - exponent);
+
+    // MtM: its eigenvalues are the squared singular values, its diagonal the squared column lengths
     let a00 = dot(m[0], m[0]);
     let a11 = dot(m[1], m[1]);
     let a22 = dot(m[2], m[2]);
@@ -47,45 +104,106 @@ fn mat3_singular_values(m: mat3x3<f32>) -> vec2<f32> {
     let a02 = dot(m[0], m[2]);
     let a12 = dot(m[1], m[2]);
 
-    let p1 = a01 * a01 + a02 * a02 + a12 * a12;
-
-    if (p1 <= 0.0) {
-        // already diagonal — the uniform-scale case lands here, and lands exactly
-        let high = max(a00, max(a11, a22));
-        let low = min(a00, min(a11, a22));
+    let column_longest_squared = max(a00, max(a11, a22));
+    let column_shortest_squared = min(a00, min(a11, a22));
 
-        return vec2<f32>(sqrt(max(high, 0.0)), sqrt(max(low, 0.0)));
-    }
+    let p1 = a01 * a01 + a02 * a02 + a12 * a12;
 
-    let q = (a00 + a11 + a22) / 3.0;
+    /*
+     B = (MtM - qI) / p has MtM's eigenvectors, with its roots in [-2, 2]. Only v is taken from B,
+     and v's rounding reaches the values at second order, so q, 1/p and phi are left to multiply.
+     */
+    let q = (a00 + a11 + a22) * (1.0 / 3.0);
 
     let d0 = a00 - q;
     let d1 = a11 - q;
     let d2 = a22 - q;
 
-    let p2 = d0 * d0 + d1 * d1 + d2 * d2 + 2.0 * p1;
+    let p_squared = (d0 * d0 + d1 * d1 + d2 * d2 + 2.0 * p1) * (1.0 / 6.0);
 
-    let p = sqrt(p2 / 6.0);
+    /*
+     Orthogonal columns, whose lengths are the singular values: a uniform scale lands here, exactly.
+     So does a matrix whose deviator is too small to normalise B by, which after the scaling is far
+     below what f32 resolves, so that the lengths are the values.
+     */
+    if (p1 <= 0.0 || !(p_squared > 0.0)) {
+        return vec2<f32>(sqrt(column_longest_squared), sqrt(column_shortest_squared)) * unit;
+    }
+
+    let inverse_p = inverseSqrt(p_squared);
 
-    // det(B) / 2, with B = (A - qI) / p
-    let b00 = d0 / p;
-    let b11 = d1 / p;
-    let b22 = d2 / p;
-    let b01 = a01 / p;
-    let b02 = a02 / p;
-    let b12 = a12 / p;
+    let b00 = d0 * inverse_p;
+    let b11 = d1 * inverse_p;
+    let b22 = d2 * inverse_p;
+    let b01 = a01 * inverse_p;
+    let b02 = a02 * inverse_p;
+    let b12 = a12 * inverse_p;
 
-    let determinant = b00 * (b11 * b22 - b12 * b12)
+    let det_b = b00 * (b11 * b22 - b12 * b12)
         - b01 * (b01 * b22 - b12 * b02)
         + b02 * (b01 * b12 - b11 * b02);
 
-    // clamped because rounding can push it a hair outside acos's domain, where the whole
-    // computation would otherwise come back NaN for a perfectly ordinary matrix
-    let phi = acos(clamp(determinant * 0.5, -1.0, 1.0)) / 3.0;
+    // the root apart from the other two: the largest when det(B) >= 0, the smallest when it is negative
+    let phi = acos(clamp(det_b * 0.5, -1.0, 1.0)) * (1.0 / 3.0);
+    let root = 2.0 * cos(phi + select(2.0 * PI / 3.0, 0.0, det_b >= 0.0));
+
+    // one Newton step on beta^3 - 3 beta - det(B), whose slope 3 (beta^2 - 1) is at least 6 there
+    let beta = root - (root * root * root - 3.0 * root - det_b) / (3.0 * (root * root - 1.0));
+
+    // B - beta I has rank two, so its eigenvector is normal to its rows; the longest cross product
+    // of two of them is that normal at its most accurate
+    let r0 = vec3<f32>(b00 - beta, b01, b02);
+    let r1 = vec3<f32>(b01, b11 - beta, b12);
+    let r2 = vec3<f32>(b02, b12, b22 - beta);
+
+    let c01 = cross(r0, r1);
+    let c02 = cross(r0, r2);
+    let c12 = cross(r1, r2);
+
+    let l01 = dot(c01, c01);
+    let l02 = dot(c02, c02);
+    let l12 = dot(c12, c12);
+
+    let c0 = select(c01, c02, l02 > l01);
+    let l0 = max(l01, l02);
+
+    let v = select(c0, c12, l12 > l0) * inverseSqrt(max(l0, l12));
+
+    /*
+     v's complement from v's own components: v crossed with e_y when v leans more on x than on y,
+     with e_x otherwise, so the square being normalised is at least 1/2 and u.v vanishes but for
+     the rounding of v's smaller components.
+     */
+    let across = select(vec3<f32>(0.0, v.z, -v.y), vec3<f32>(-v.z, 0.0, v.x), abs(v.x) > abs(v.y));
+    let u = across * inverseSqrt(dot(across, across));
+    let w = cross(v, u);
+
+    let image_v = m * v;
+    let image_u = m * u;
+    let image_w = m * w;
+
+    // the 3x2 [Mu Mw]: its larger squared singular value from the 2x2 Gram, where the root adds to the mean
+    let g00 = dot(image_u, image_u);
+    let g11 = dot(image_w, image_w);
+    let g01 = dot(image_u, image_w);
+
+    let plane_largest_squared = 0.5 * (g00 + g11) + length(vec2<f32>(0.5 * (g00 - g11), g01));
+    let plane_normal = cross(image_u, image_w);
+
+    let along_v_squared = dot(image_v, image_v);
+
+    /*
+     v is the eigenvector of the largest or of the smallest singular value, and the plane holds
+     the other two. Either way the larger of along_v and plane_largest is sigma_max, and the larger
+     of along_v * plane_largest and the plane's area is sigma_max * sigma_mid.
+     */
+    let largest = sqrt(max(max(along_v_squared, plane_largest_squared), column_longest_squared));
+    let largest_two_squared = max(along_v_squared * plane_largest_squared, dot(plane_normal, plane_normal));
+
+    let determinant_m = abs(mat3_determinant(m));
 
-    let high = q + 2.0 * p * cos(phi);
-    let low = q + 2.0 * p * cos(phi + 2.0 * 3.14159265358979 / 3.0);
+    let smallest = select(0.0, determinant_m * inverseSqrt(largest_two_squared), largest_two_squared > 0.0);
 
-    return vec2<f32>(sqrt(max(high, 0.0)), sqrt(max(low, 0.0)));
+    return vec2<f32>(largest, min(smallest, sqrt(column_shortest_squared))) * unit;
 }
-`, []);
+`, [PI_DECLARATION, chunk_mat3_determinant]);

package/src/shade/renderer/shader/chunk/geometry/mat4/chunk_mat4_linear_determinant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_mat4_linear_determinant.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/mat4/chunk_mat4_linear_determinant.js"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,4CAFU,SAAS,CAQb;0BAjBoB,gCAAgC"}
+{"version":3,"file":"chunk_mat4_linear_determinant.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/mat4/chunk_mat4_linear_determinant.js"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,4CAFU,SAAS,CAQS;0BAlBF,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/mat4/chunk_mat4_linear_determinant.js

@@ -1,18 +1,19 @@
-import { CodeChunk } from "../../../compiler/CodeChunk.js";
-
-/**
- * Determinant of the linear (upper-left 3x3) part of a 4x4 transform. WGSL twin of
- * {@link m4_linear_determinant} — keep the two in step.
- *
- * Negative exactly when the transform reflects, which is what reverses triangle winding and
- * tangent-frame handedness under it.
- *
- * @type {CodeChunk}
- */
-export const chunk_mat4_linear_determinant = CodeChunk.from(
-    //language=WGSL
-    `
-fn mat4_linear_determinant( m: mat4x4<f32> ) -> f32{
-    return dot( m[0].xyz, cross( m[1].xyz, m[2].xyz ) );
-}
-`, [])
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { chunk_mat3_determinant } from "../mat3/chunk_mat3_determinant.js";
+
+/**
+ * Determinant of the linear (upper-left 3x3) part of a 4x4 transform. WGSL twin of
+ * {@link m4_linear_determinant} — keep the two in step.
+ *
+ * Negative exactly when the transform reflects, which is what reverses triangle winding and
+ * tangent-frame handedness under it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_mat4_linear_determinant = CodeChunk.from(
+    //language=WGSL
+    `
+fn mat4_linear_determinant( m: mat4x4<f32> ) -> f32{
+    return mat3_determinant(mat3x3<f32>(m[0].xyz, m[1].xyz, m[2].xyz));
+}
+`, [chunk_mat3_determinant])

package/src/shade/renderer/shader/chunk/geometry/normal/chunk_decode_g_buffer_face_normal.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The face normal from a texel of the G-buffer's PBR target, which holds it in `ba` as
+ * {@link chunk_encode_g_buffer_face_normal} writes it.
+ *
+ * ```wgsl
+ * fn decode_g_buffer_face_normal(pbr_texel: vec4<f32>) -> vec3<f32>
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_decode_g_buffer_face_normal: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_decode_g_buffer_face_normal.d.ts.map

package/src/shade/renderer/shader/chunk/geometry/normal/chunk_decode_g_buffer_face_normal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_decode_g_buffer_face_normal.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/normal/chunk_decode_g_buffer_face_normal.js"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,gDAFU,SAAS,CAUZ;0BArBmB,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/normal/chunk_decode_g_buffer_face_normal.js

@@ -0,0 +1,22 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { chunk_uv_octahedral_unit_decode } from "../octahedron/chunk_uv_octahedral_unit_decode.js";
+
+/**
+ * The face normal from a texel of the G-buffer's PBR target, which holds it in `ba` as
+ * {@link chunk_encode_g_buffer_face_normal} writes it.
+ *
+ * ```wgsl
+ * fn decode_g_buffer_face_normal(pbr_texel: vec4<f32>) -> vec3<f32>
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_decode_g_buffer_face_normal = CodeChunk.from(
+    //language=WGSL
+    `
+fn decode_g_buffer_face_normal(pbr_texel: vec4<f32>) -> vec3<f32> {
+    return uv_octahedral_unit_decode(pbr_texel.zw * (255.0 / 254.0));
+}
+`, [
+        chunk_uv_octahedral_unit_decode,
+    ]);

package/src/shade/renderer/shader/chunk/geometry/normal/chunk_decode_g_buffer_normal.d.ts

@@ -1,5 +1,12 @@
 /**
- * Input is assumed to be a vec2<u16>
+ * A shading normal from the `u32` {@link chunk_encode_g_buffer_normal} packs: octahedral, 16 bits per
+ * axis, u in the low half and v in the high half (`unpack2x16unorm`).
+ *
+ * ```wgsl
+ * fn decode_g_buffer_normal(encoded: u32) -> vec3<f32>
+ * ```
+ *
+ * @type {CodeChunk}
  */
 export const chunk_decode_g_buffer_normal: CodeChunk;
 import { CodeChunk } from "../../../compiler/CodeChunk.js";

package/src/shade/renderer/shader/chunk/geometry/normal/chunk_decode_g_buffer_normal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_decode_g_buffer_normal.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/normal/chunk_decode_g_buffer_normal.js"],"names":[],"mappings":"AAGA;;GAEG;AACH,qDAYO;0BAlBmB,gCAAgC"}
+{"version":3,"file":"chunk_decode_g_buffer_normal.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/normal/chunk_decode_g_buffer_normal.js"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,2CAFU,SAAS,CAUZ;0BArBmB,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/normal/chunk_decode_g_buffer_normal.js

@@ -2,19 +2,21 @@ import { CodeChunk } from "../../../compiler/CodeChunk.js";
 import { chunk_uv_octahedral_unit_decode } from "../octahedron/chunk_uv_octahedral_unit_decode.js";
 
 /**
- * Input is assumed to be a vec2<u16>
+ * A shading normal from the `u32` {@link chunk_encode_g_buffer_normal} packs: octahedral, 16 bits per
+ * axis, u in the low half and v in the high half (`unpack2x16unorm`).
+ *
+ * ```wgsl
+ * fn decode_g_buffer_normal(encoded: u32) -> vec3<f32>
+ * ```
+ *
+ * @type {CodeChunk}
  */
 export const chunk_decode_g_buffer_normal = CodeChunk.from(
     //language=WGSL
     `
-fn decode_g_buffer_normal(encoded_normal: vec2<u32>) -> vec3<f32>{
-    const normalization_constant = 1.0 / 65535.0;
-    
-    let scaled = vec2f(encoded_normal) * normalization_constant;
-
-    return uv_octahedral_unit_decode(scaled.xy);
+fn decode_g_buffer_normal(encoded: u32) -> vec3<f32> {
+    return uv_octahedral_unit_decode(unpack2x16unorm(encoded));
 }
 `, [
         chunk_uv_octahedral_unit_decode,
     ]);
-

package/src/shade/renderer/shader/chunk/geometry/normal/chunk_encode_g_buffer_face_normal.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The G-buffer's face normal as its PBR target stores it in `ba`: octahedral, eight bits per axis. The
+ * `unorm8` channels round to the nearest of their 256 codes as they are written; the coordinates are
+ * scaled by 254 / 255 first, so a channel holds round(uv × 254) and 254 intervals span the octahedron.
+ * An even count puts its centre and its edges on codes, which makes every axis-aligned direction — the
+ * floors and walls of built geometry — exact. Any direction comes back within 3√2 / 254 rad (0.957°).
+ *
+ * The face normal sets directions and thresholds — ray origins, shadow normal offsets, back-face and
+ * same-surface tests, the tangent plane a screen-space ray refines on — none of which needs the shading
+ * normal's precision.
+ *
+ * ```wgsl
+ * fn encode_g_buffer_face_normal(normal: vec3<f32>) -> vec2<f32>
+ * ```
+ *
+ * Input must be normalized.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_encode_g_buffer_face_normal: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_encode_g_buffer_face_normal.d.ts.map

package/src/shade/renderer/shader/chunk/geometry/normal/chunk_encode_g_buffer_face_normal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_encode_g_buffer_face_normal.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/normal/chunk_encode_g_buffer_face_normal.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH,gDAFU,SAAS,CAWjB;0BA/BwB,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/normal/chunk_encode_g_buffer_face_normal.js

@@ -0,0 +1,32 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { chunk_uv_octahedral_unit_encode } from "../octahedron/chunk_uv_octahedral_unit_encode.js";
+
+/**
+ * The G-buffer's face normal as its PBR target stores it in `ba`: octahedral, eight bits per axis. The
+ * `unorm8` channels round to the nearest of their 256 codes as they are written; the coordinates are
+ * scaled by 254 / 255 first, so a channel holds round(uv × 254) and 254 intervals span the octahedron.
+ * An even count puts its centre and its edges on codes, which makes every axis-aligned direction — the
+ * floors and walls of built geometry — exact. Any direction comes back within 3√2 / 254 rad (0.957°).
+ *
+ * The face normal sets directions and thresholds — ray origins, shadow normal offsets, back-face and
+ * same-surface tests, the tangent plane a screen-space ray refines on — none of which needs the shading
+ * normal's precision.
+ *
+ * ```wgsl
+ * fn encode_g_buffer_face_normal(normal: vec3<f32>) -> vec2<f32>
+ * ```
+ *
+ * Input must be normalized.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_encode_g_buffer_face_normal = CodeChunk.from(
+    //language=WGSL
+    `
+fn encode_g_buffer_face_normal(normal: vec3<f32>) -> vec2<f32> {
+    return uv_octahedral_unit_encode(normal) * (254.0 / 255.0);
+}
+    `, [
+        chunk_uv_octahedral_unit_encode
+    ]
+);

package/src/shade/renderer/shader/chunk/geometry/normal/chunk_encode_g_buffer_normal.d.ts

@@ -1,5 +1,15 @@
 /**
- * Input must be normalized
+ * A unit normal as one `u32`: octahedral UV through `pack2x16unorm`, each component the nearest 16-bit
+ * code, u in the low half and v in the high half — the format of a mesh's vertex normals
+ * (`encode_vertex_normal`). What the G-buffer's `r32uint` normal target holds, and every other texture
+ * that stores a normal the same way (GTAO's bent normal).
+ *
+ * ```wgsl
+ * fn encode_g_buffer_normal(normal: vec3<f32>) -> u32
+ * ```
+ *
+ * Input must be normalized.
+ *
  * @type {CodeChunk}
  */
 export const chunk_encode_g_buffer_normal: CodeChunk;