@woosh/meep-engine 3.14.0 → 3.14.2

package/src/shade/renderer/shader/chunk/geometry/triangle/chunk_barycentric_full.js

@@ -1,61 +1,94 @@
-import { BARYCENTRIC_STRUCT } from "./BARYCENTRIC_STRUCT.js";
-import { CodeChunk } from "../../../compiler/CodeChunk.js";
-
-/*
- references:
-  http://filmicworlds.com/blog/visibility-buffer-rendering-with-material-graphs/
-  https://github.com/ssloy/tinyrenderer/wiki/Lesson-2:-Triangle-rasterization-and-back-face-culling
-
-*/
-
-
-export const chunk_barycentric_full = CodeChunk.from(
-    // language=WGSL
-    `
-fn barycentric_full(
-    pt0: vec4<f32>,
-    pt1: vec4<f32>,
-    pt2: vec4<f32>,
-    pixel: vec2<f32>
-) -> ${BARYCENTRIC_STRUCT.wgsl_ref} {
-    let invW:vec3<f32> = 1.0 / vec3<f32>(pt0.w, pt1.w, pt2.w);
-
-    let ndc0:vec2<f32> = pt0.xy * invW.x;
-    let ndc1:vec2<f32> = pt1.xy * invW.y;
-    let ndc2:vec2<f32> = pt2.xy * invW.z;
-
-    let det_multiplier:vec3<f32> = invW / (determinant(mat2x2(ndc2 - ndc1, ndc0 - ndc1)));
-
-    let m_ddx = vec3<f32>(ndc1.y - ndc2.y, ndc2.y - ndc0.y, ndc0.y - ndc1.y) * det_multiplier;
-    let m_ddy = vec3<f32>(ndc2.x - ndc1.x, ndc0.x - ndc2.x, ndc1.x - ndc0.x) * det_multiplier;
-
-    let ddxSum:f32 = dot(m_ddx, vec3<f32>(1,1,1));
-    let ddySum:f32 = dot(m_ddy, vec3<f32>(1,1,1));
-
-    let deltaVec:vec2<f32> = pixel - ndc0;
-
-    let interpInvW:f32 = invW.x + deltaVec.x * ddxSum + deltaVec.y * ddySum;
-    let interpW:f32 = 1.0 / interpInvW;
-
-    let m_lambda = vec3<f32>(
-        interpW * (invW.x  + deltaVec.x * m_ddx.x + deltaVec.y * m_ddy.x),
-        interpW * (0.0f    + deltaVec.x * m_ddx.y + deltaVec.y * m_ddy.y),
-        interpW * (0.0f    + deltaVec.x * m_ddx.z + deltaVec.y * m_ddy.z)
-    );
-
-    let interpW_ddx:f32 = 1.0f / (interpInvW + ddxSum);
-    let interpW_ddy:f32 = 1.0f / (interpInvW + ddySum);
-
-    let liw = m_lambda * interpInvW;
-
-    return ${BARYCENTRIC_STRUCT.wgsl_ref}(
-        m_lambda,
-        interpW_ddx * (liw + m_ddx) - m_lambda,
-        interpW_ddy * (liw + m_ddy) - m_lambda
-    );
-}
-`,
-    [
-        BARYCENTRIC_STRUCT.declaration_chunk
-    ]
-);
+import { BARYCENTRIC_STRUCT } from "./BARYCENTRIC_STRUCT.js";
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { chunk_barycentric_solve } from "./chunk_barycentric_solve.js";
+
+/*
+ references:
+  http://filmicworlds.com/blog/visibility-buffer-rendering-with-material-graphs/
+  https://github.com/ssloy/tinyrenderer/wiki/Lesson-2:-Triangle-rasterization-and-back-face-culling
+  Olano & Greer 1997, "Triangle Scan Conversion using 2D Homogeneous Coordinates"
+*/
+
+/**
+ * Perspective-correct barycentric coordinates for a pixel inside a triangle, with the per-pixel
+ * derivatives the texture gradients are built from.
+ *
+ * ## What it solves
+ *
+ * A point of the triangle with barycentric `l` sits at clip position `sum(l_i * P_i)` and therefore
+ * at screen position `sum(l_i * P_i.xy) / sum(l_i * P_i.w)`. Asking for the `l` whose screen
+ * position is this pixel gives two linear equations, and `sum(l) == 1` gives the third:
+ *
+ * ```
+ *   sum_i  l_i * (x_i - pixel.x * w_i) = 0
+ *   sum_i  l_i * (y_i - pixel.y * w_i) = 0
+ *   sum_i  l_i                         = 1
+ * ```
+ *
+ * This function forms the two pixel-relative coordinate vectors that system is written in;
+ * {@link chunk_barycentric_solve} solves it.
+ *
+ * ## Why it is written this way
+ *
+ * **It never divides by w.** A vertex on the eye plane has `w == 0` and one behind it has `w < 0`;
+ * projecting either to NDC first yields an infinity or a sign-flipped coordinate hundreds of
+ * thousands of pixels outside the viewport, and every later term then has to cancel that magnitude
+ * back down. Here `w` only ever multiplies, so a triangle straddling the eye plane is an ordinary
+ * case rather than a near-singular one.
+ *
+ * **It has no anchor, and that is the point.** The previous formulation measured every pixel from
+ * `pixel - ndc0` and scaled by a determinant taken about vertex 1, so vertex 0 was the origin of
+ * the whole reconstruction and the three corners were not interchangeable. In exact arithmetic that
+ * is irrelevant. In f32, on a triangle whose corners project far outside the viewport, it is not:
+ * the rounding depended on which corner was first, so two coplanar triangles meeting along an edge
+ * reconstructed measurably different UVs on either side of it — and the difference moved with the
+ * TAA jitter, which turned it into a temporally unstable seam along the shared edge. Invisible in a
+ * still frame, plainly visible in a multi-frame difference. `src/shade/playground/ground_seam`
+ * measures it, and measured this rewrite: the seam goes from a 2.1x step in per-pixel temporal
+ * spread to none, and a two-triangle quad now behaves like the same quad subdivided 8x8.
+ *
+ * **The derivatives are evaluations, not a differentiation.** `ddx` is defined as
+ * `lambda(pixel + (1,0)) - lambda(pixel)`, a whole-pixel forward difference, which is what mip
+ * selection wants; it is computed by solving the same system one pixel over. Stepping the pixel by
+ * one in x subtracts `w` from `u`, so the second and third solves share every input with the first.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_barycentric_full = CodeChunk.from(
+    // language=WGSL
+    `
+fn barycentric_full(
+    pt0: vec4<f32>,
+    pt1: vec4<f32>,
+    pt2: vec4<f32>,
+    pixel: vec2<f32>
+) -> ${BARYCENTRIC_STRUCT.wgsl_ref} {
+    let w = vec3<f32>(pt0.w, pt1.w, pt2.w);
+
+    /*
+     Each vertex's offset from the pixel's ray, in homogeneous coordinates. This is where the
+     triangle's size is cancelled against the pixel's position, and it is deliberately the only
+     place that happens: one multiply-subtract per component, which a driver may contract into a
+     single fused operation, rather than a chain of large intermediates left to cancel each other
+     several steps later.
+    */
+    let u = fma(vec3<f32>(-pixel.x), w, vec3<f32>(pt0.x, pt1.x, pt2.x));
+    let v = fma(vec3<f32>(-pixel.y), w, vec3<f32>(pt0.y, pt1.y, pt2.y));
+
+    // one pixel along x subtracts w from u; one along y subtracts w from v
+    let lambda = barycentric_solve(u, v);
+    let lambda_x = barycentric_solve(u - w, v);
+    let lambda_y = barycentric_solve(u, v - w);
+
+    return ${BARYCENTRIC_STRUCT.wgsl_ref}(
+        lambda,
+        lambda_x - lambda,
+        lambda_y - lambda
+    );
+}
+`,
+    [
+        BARYCENTRIC_STRUCT.declaration_chunk,
+        chunk_barycentric_solve
+    ]
+);

package/src/shade/renderer/shader/chunk/geometry/triangle/chunk_barycentric_solve.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Barycentric weights of a point inside a triangle, by Cramer's rule, from coordinates already
+ * expressed relative to that point.
+ *
+ * The caller supplies `u` and `v`: for each corner `i`, `u[i] = x_i - point.x * w_i` and
+ * `v[i] = y_i - point.y * w_i`, in homogeneous clip coordinates. Those are the two equations that
+ * say "the corners, weighted, project to this point"; together with the weights summing to one they
+ * make a 3x3 system, and the three 2x2 determinants below are its Cramer solution.
+ *
+ * Separated from {@link chunk_barycentric_full} because it is the whole of the arithmetic and none
+ * of the setup, so it can be read, tested and reused on its own — {@link chunk_barycentric_full}
+ * calls it three times per pixel, once for the pixel and once for each of its two neighbours.
+ *
+ * **Cyclically symmetric, deliberately.** Each weight is the same expression in the other two
+ * corners, so rotating which corner is first permutes the result and changes nothing else. That is
+ * not an aesthetic property: a formulation that measures from one distinguished corner rounds
+ * differently depending on which corner that is, and two coplanar triangles then disagree about the
+ * surface they share. See `src/shade/playground/ground_seam`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_barycentric_solve: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_barycentric_solve.d.ts.map

package/src/shade/renderer/shader/chunk/geometry/triangle/chunk_barycentric_solve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_barycentric_solve.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/triangle/chunk_barycentric_solve.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,sCAFU,SAAS,CAqBjB;0BA1CwB,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/triangle/chunk_barycentric_solve.js

@@ -0,0 +1,43 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+
+/**
+ * Barycentric weights of a point inside a triangle, by Cramer's rule, from coordinates already
+ * expressed relative to that point.
+ *
+ * The caller supplies `u` and `v`: for each corner `i`, `u[i] = x_i - point.x * w_i` and
+ * `v[i] = y_i - point.y * w_i`, in homogeneous clip coordinates. Those are the two equations that
+ * say "the corners, weighted, project to this point"; together with the weights summing to one they
+ * make a 3x3 system, and the three 2x2 determinants below are its Cramer solution.
+ *
+ * Separated from {@link chunk_barycentric_full} because it is the whole of the arithmetic and none
+ * of the setup, so it can be read, tested and reused on its own — {@link chunk_barycentric_full}
+ * calls it three times per pixel, once for the pixel and once for each of its two neighbours.
+ *
+ * **Cyclically symmetric, deliberately.** Each weight is the same expression in the other two
+ * corners, so rotating which corner is first permutes the result and changes nothing else. That is
+ * not an aesthetic property: a formulation that measures from one distinguished corner rounds
+ * differently depending on which corner that is, and two coplanar triangles then disagree about the
+ * surface they share. See `src/shade/playground/ground_seam`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_barycentric_solve = CodeChunk.from(
+    // language=WGSL
+    `
+fn barycentric_solve(u: vec3<f32>, v: vec3<f32>) -> vec3<f32> {
+    let cofactor = vec3<f32>(
+        u.y * v.z - u.z * v.y,
+        u.z * v.x - u.x * v.z,
+        u.x * v.y - u.y * v.x,
+    );
+
+    /*
+     The cofactors carry a common factor of the triangle's homogeneous area, which this divides out
+     — so it is never formed, and a sliver divides by its own signed area rather than by anything
+     larger. For a point inside the triangle all three share a sign, making this sum the one place
+     in the function where nothing cancels.
+    */
+    return cofactor / (cofactor.x + cofactor.y + cofactor.z);
+}
+`
+);