Files
umamo-reference-layer/docs/seams.md
T
litruv 4eb583b5f3 Design doc and reference implementation sketch for the reference layer
Design for a poseable mannequin plus glTF/GLB import overlay in Umamo:
world axes, orbit camera, draw path, UMA persistence, UI, risks.

docs/seams.md lists the RenderDevice additions the feature needs:
PrimitiveTopology, DepthState, depthAttachment, WorldToClip,
ReferenceMeshSpec.

sketch/ mirrors the algorithms in Kotlin. verify/verify.py proves them:
30 checks, all passing. Two findings: accessor byteOffset must be a
multiple of the component size, and the screen-right basis collapses to a
zero vector at pitch +/-90 degrees, so pitch is clamped to an open
interval.
2026-11-03 18:14:07 +11:00

5.0 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.

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

public data class DepthRange(val near: Float, val far: Float)
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.

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

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.