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.
This commit is contained in:
litruv
2026-11-03 18:14:07 +11:00
parent e95d7795ae
commit 4eb583b5f3
10 changed files with 1913 additions and 2 deletions
+143
View File
@@ -0,0 +1,143 @@
# 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.