Files
litruv 0894e762f9 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.
2026-11-03 21:04:53 +11:00

8.8 KiB

Seam changes the reference layer forces

These are the parts of module/render/src/commonMain/.../device/ that cannot support a 3D reference layer as they stand. Each is shown as it is today, then as proposed.

1. PrimitiveTopology

Today the seam assumes triangles everywhere. PipelinePurpose.WorldAxisLine is already a line draw ("attribute-less; two endpoints from the vertex index"), so lines exist in spirit but are hardcoded into one purpose. A wireframe overlay needs lines as a general topology, which means the pipeline spec has to say it.

public enum class PrimitiveTopology {
	/** Triangles. Every existing pipeline. */
	Triangles,

	/** Line pairs from an index buffer. The wireframe overlay and the world axis lines. */
	Lines,
}

Wireframe by barycentric attribute was considered and rejected: it needs a per-vertex attribute and a shader branch, and it cannot draw a silhouette edge shared by one triangle. GL_LINES from an edge index buffer built at upload is simpler and matches the axis-line path that already exists.

2. DepthState

No pipeline can depth-test today, and no target can hold a depth attachment. Both are needed.

public enum class DepthFunc {
	/** Standard: nearer wins. */
	Less,

	/** Always pass. Used when the layer draws over everything with no depth buffer. */
	Always,
}

public data class DepthState(
	val enabled: Boolean,
	val func: DepthFunc = DepthFunc.Less,
)

RenderPipelineSpec becomes:

public data class RenderPipelineSpec(
	val purpose: PipelinePurpose,
	val blend: PipelineBlend,
	val cullBackFaces: Boolean = false,
	val topology: PrimitiveTopology = PrimitiveTopology.Triangles,
	val depth: DepthState = DepthState.Disabled,
)

Both defaults keep every existing call site compiling unchanged. That is deliberate: the depth work must not require touching the puppet path.

RenderTargetSpec gains depthAttachment: Boolean = false. Only the reference pass needs one.

Two rules that have to be stated, because they are not obvious from the API:

  • resolve and resolveUsed copy color only. A depth attachment is never copied, so a pass that reads a resolved target has no depth to read.
  • The composite path samples screen-space textures and has no depth input. A depth-tested draw 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

public enum class PipelinePurpose {
	// ... existing six ...

	/** Flat-shaded or vertex-normal-shaded reference triangles. */
	ReferenceMesh,

	/** Reference wireframe, line pairs. */
	ReferenceWireframe,
}

The enum is closed on purpose — adding a value forces every backend to answer for it rather than silently lacking one. That cost is real here: GlesRenderDevice and MetalRenderDevice are stubs, so this feature is desktop-only until the GLES device exists. The stubs must answer explicitly, not throw.

4. A 3D camera on the pass encoder

WorldToNdc is a 2D affine and cannot carry depth. The reference pass needs a full matrix.

public data class WorldToClip(val matrix: FloatArray)   // 16 floats, row-major
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 UVs, no glue attributes, and no deform inputs.

public class ReferenceMeshSpec(
	val positions: FloatArray,          // interleaved x, y, z
	val indices: IntArray,
	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

fun drawReferenceMesh(mesh: GpuMesh, fragment: FragmentUniforms)

fun drawReferenceWireframe(mesh: GpuMesh, fragment: FragmentUniforms)

FragmentUniforms already carries colorRed/Green/Blue/Alpha and opacity, which is all the 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.
  • The read-back contract is untouched: RGBA8888, top row first. A depth-tested frame reads back the same way, which is what makes the GL-gated test possible at all.
  • FrameEncoder.barrier is untouched. The reference pass has no cross-pass dependency.