Camera and reader rules corrected against a real file

The depth row maps the slab to the full clip range, not half of it, so the CPU sort and the GPU
depth test agree on which fragment is nearer. The screen-right axis is the unit horizontal: built
as forward x worldUp it carries a factor of cos(pitch) and compresses screen X as the camera tilts,
so the pitch clamp is the edge-on guard rather than a fix for a zero vector.

MAT4 is an accessor type and count is the number of elements, not floats, which is the shape a
skin's inverse bind matrices actually have. node.matrix is column-major while Mat4 is row-major.
A skin's joints must be resolved by node index, because CesiumMan.glb keeps its skeleton outside
the scene root.
This commit is contained in:
litruv
2026-11-03 21:04:53 +11:00
parent 4eb583b5f3
commit 0894e762f9
2 changed files with 95 additions and 18 deletions
+63 -5
View File
@@ -69,6 +69,17 @@ Two rules that have to be stated, because they are not obvious from the API:
must not be composited through a blend-mode layer; the blend would run against pixels the
depth test should have rejected. The reference layer draws directly.
Three more rules the implementation settled:
- The depth clear follows the pass's `loadAction` and only runs when the target has a depth
attachment. Depth state is bound with the program, like blend and cull, and the write mask stays at
its default.
- `drawReferenceMesh` and `drawReferenceWireframe` check the pipeline's topology against the draw, so
a spec and a draw call cannot disagree.
- `DepthFunc.Always` is what the wireframe uses, so edges show over the mesh. A coplanar wireframe
loses to strict `Less` and proves nothing, which is why the depth proof in the GL test uses two
screen-overlapping squares at different depths instead of a wireframe-versus-mesh comparison.
## 3. `PipelinePurpose` additions
```kotlin
@@ -94,18 +105,36 @@ explicitly, not throw.
```kotlin
public data class WorldToClip(val matrix: FloatArray) // 16 floats, row-major
public data class DepthRange(val near: Float, val far: Float)
```
```kotlin
fun setClipCamera(worldToClip: WorldToClip, depthRange: DepthRange, screenTexWidth: Int, screenTexHeight: Int)
fun setClipCamera(worldToClip: WorldToClip)
```
`DepthRange` was in this proposal and is gone: the near/far mapping is baked into the matrix, so a
separate depth uniform would be dead state sent to a program that does not declare it. The screen
size is gone too — the orthographic scales are already in the matrix.
The depth row maps the slab to the full clip range `[-1, 1]`, not to `[0, 1]`. Mapping to `[0, 1]`
throws away half the depth precision for nothing, and it makes the CPU sort and the GPU test
disagree about which fragment is nearer. `ReferenceCamera.project` reports window depth
`(clipZ + 1) / 2` in `[0, 1]`, so a smaller value is nearer in both paths. Geometry outside the
slab is clipped, so `near` has to cover the model's extent along the view direction.
`setCamera(worldToNdc, ...)` stays. `WorldToNdc` is its Z = 0 slice, and the two must agree
exactly at yaw = pitch = 0 — that agreement is verified in `verify/verify.py` and is what keeps
the reference layer aligned with the drawing plane when nothing is rotated.
Two traps the implementation hit:
- `Mat4` is row-major because commonMain supplies values and the layout is the backend's, so the GL
marshaller transposes on upload. Applying the columns instead of the rows is the transpose, and it
is invisible at zero angles where the matrix is diagonal.
- The screen-right axis must be the unit horizontal, not `forward x worldUp`. That cross product
carries a factor of `cos(pitch)` and compresses screen X as the camera tilts, reaching exactly zero
at pitch 90. The pitch clamp is a usability guard — at pitch 90 the drawing plane is edge-on — not
a fix for a zero vector.
## 5. A 3D mesh upload
`MeshSpec.restPositions` is interleaved x,y. A reference mesh needs three components and has no
@@ -115,14 +144,23 @@ UVs, no glue attributes, and no deform inputs.
public class ReferenceMeshSpec(
val positions: FloatArray, // interleaved x, y, z
val indices: IntArray,
val normals: FloatArray?, // interleaved x, y, z, or null for flat shading
val wireframeIndices: IntArray?, // triangle edges as line pairs, built at upload
val wireframeIndices: IntArray, // triangle edges as line pairs, built at upload
)
```
Building `wireframeIndices` at upload rather than per frame is the point: the edge set is
static, and a per-frame rebuild would be the most expensive thing in the frame.
As implemented, `normals` is gone and `wireframeIndices` is non-null. The flat program reads no
attribute 1, so uploading normals would allocate a buffer nothing reads; and a mesh drawn as a
wireframe has to have edges. Shading is a later PR.
A VAO owns its element-array binding, so the triangle index buffer and the edge index buffer cannot
share one VAO. The reference mesh gets a second VAO sharing the position VBO.
Per-pose position upload reuses `updateMeshPositions` — same buffer kind, only the component count
differs.
## 6. Draw calls
```kotlin
@@ -135,6 +173,26 @@ fun drawReferenceWireframe(mesh: GpuMesh, fragment: FragmentUniforms)
reference layer needs. It does not need `useTexture`, `useMask`, or the multiply/screen colors.
Reusing the struct is fine; the marshaller reads what it reads.
## 7. What a real file taught the reader
The fixtures stayed green while `CesiumMan.glb` failed. Each of these is a rule the fixtures asserted
in the wrong direction.
- `MAT4` is an accessor type. `count` is the number of elements, not the number of floats, so a skin's
inverse bind matrices are one `MAT4` Float32 accessor whose count is the number of joints, and the
format allows the count to exceed the joints. The reader required `SCALAR` and rejected the file.
- `node.matrix` is column-major. `Mat4` is row-major. Applying the sixteen values as stored applies the
transpose, and a transpose is invisible whenever the matrix is diagonal.
- glTF is Y-up, Umamo is Z-up. `CesiumMan.glb`'s root node is named `Z_UP` and carries the conversion
matrix. The reader does not convert axes; the caller decides which axes an imported model arrives in.
- Joints have to be resolved by node index. In that file the scene root holds only the mesh node, and the
nineteen joints hang off a skeleton node the scene does not reach. A reader that walked the scene graph
would find no joints and draw the mesh in its bind pose with nothing saying so.
- A primitive's mode can be a line mode — that file declares `LINE_LOOP`. The reader reports the mode; the
render side has to say what a non-triangle primitive means.
- `JOINTS_0` is `VEC4` `UNSIGNED_SHORT`, so skinning reads components, not floats. `readFloats` refuses it,
which is why `readComponents` is public.
## What does not change
- The deform eval, pose resolution, glue, and render order are untouched.