# 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. ## 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 public data class DepthRange(val near: Float, val far: Float) ``` ```kotlin fun setClipCamera(worldToClip: WorldToClip, depthRange: DepthRange, screenTexWidth: Int, screenTexHeight: Int) ``` `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. ## 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 normals: FloatArray?, // interleaved x, y, z, or null for flat shading 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. ## 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. ## 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.