# 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. ```kotlin 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. ```kotlin 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: ```kotlin 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 ```kotlin 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. ```kotlin public data class WorldToClip(val matrix: FloatArray) // 16 floats, row-major ``` ```kotlin 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. ```kotlin 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 ```kotlin 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.