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.
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:
resolveandresolveUsedcopy 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
loadActionand 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. drawReferenceMeshanddrawReferenceWireframecheck the pipeline's topology against the draw, so a spec and a draw call cannot disagree.DepthFunc.Alwaysis what the wireframe uses, so edges show over the mesh. A coplanar wireframe loses to strictLessand 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:
Mat4is 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 ofcos(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.
MAT4is an accessor type.countis the number of elements, not the number of floats, so a skin's inverse bind matrices are oneMAT4Float32 accessor whose count is the number of joints, and the format allows the count to exceed the joints. The reader requiredSCALARand rejected the file.node.matrixis column-major.Mat4is 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 namedZ_UPand 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_0isVEC4UNSIGNED_SHORT, so skinning reads components, not floats.readFloatsrefuses it, which is whyreadComponentsis 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.barrieris untouched. The reference pass has no cross-pass dependency.