Files
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

4.3 KiB

PR stack

Six PRs, each reviewable and mergeable on its own, following the stack convention in umamo/README.md § Contributors. Each one has a reason to exist before the next one uses it.

PR 1 — :format: glTF/GLB reader

Read-only. Container rules, buffer views, accessors, scene graph, skins. No rendering, no UI.

Why first: the container rules are the part most likely to be wrong, and they are testable without a GPU or an asset. Alignment rejection, chunk padding, truncation, and the more-than-one-chunk case are all pure.

Depends on nothing. kotlinx-serialization-json is already a :format dependency.

Reuse UmaManifest.kt's JSON depth guard (UMA_MAXIMUM_JSON_DEPTH) for the glTF JSON chunk. An accessor that reads past its buffer view's byteLength is an error, not a zero fill.

Tests: GlbContainerTest, GltfAccessorTest. Corpus gate under test/corpus/gltf/, skipped when empty, like every other corpus test.

PR 2 — :render: seam additions

PrimitiveTopology, DepthState, depthAttachment, WorldToClip, ReferenceMeshSpec, the two draw calls, and the GL implementation. Nothing uses them yet.

Why it must be its own PR: it touches every backend, including the GLES and Metal stubs, which have to answer for the new PipelinePurpose values explicitly. A seam change that arrives attached to a feature cannot be bisected when a backend breaks.

Defaults on RenderPipelineSpec keep every existing call site compiling unchanged, so this PR has no behavioural diff for the puppet path. That is the test that it is honest.

Tests: ReferenceDepthGateTest, GL-gated, shaped like WorldAxisLinesTest.kt — a flat-shaded triangle at a known camera must rasterize the expected pixels, and the depth test must reject a triangle behind it. Skips via a JUnit assumption in a display-less environment.

PR 3 — :runtime + :edit: the reference layer model and the pose

ReferenceLayer, the joint set with per-joint clamps, forward kinematics, CPU skinning. Pure data and pure functions, no GL, no UI.

Why before the renderer: the pose is the part a test can pin. Bone length invariance, joint origin invariance, orthonormality, and a weighted blend between two poses are all facts about the model, not about the GPU.

Tests: MannequinFkTest, ReferenceLayerTest, SkinningTest.

PR 4 — :render: the reference renderer

Consumes PR 1's scene and PR 3's pose. Builds the camera matrix, uploads the mesh, draws the flat fill and the wireframe, resolves the pose on pose-change frames only.

Draw order Above and Below only. Depth-sorted occlusion against the puppet is not in this PR: it needs the puppet to write depth from drawable Z, and the puppet path has no depth today.

Tests: ReferenceDrawPlanTest (pure), ReferenceRenderGateTest (GL-gated).

PR 5 — :ui: the overlay

Overlays toggle in the viewport header, the Properties section, the commands through CommandRegistry, keymap entries, strings.xml entries.

Why last of the functional ones: it is the only PR that changes what a user sees, and it depends on everything above existing.

Commands: reference.import, reference.reset-pose, reference.fit, reference.toggle-visibility, reference.link-camera, reference.clear.

Tests: CommandTableOrderTest and CommandRoutingTest cases for the new commands, plus the area-scoped routing — the reference commands belong to the viewport area, not the UV editor.

PR 6 — :format + :ui: UMA persistence

The reference entry, the bridge type, the writer and loader wiring.

Why last: persistence is only worth designing once the shape of the object is settled by PR 3, and the entry must be additive and ignorable — a reader that does not know reference skips it and the document still opens.

Tests: UmaEntrySchemaTest case, UmaReferenceRoundTripTest, and the export-contamination gate: a document with a reference layer present must still produce a byte-identical CMO3 for the puppet. That gate is the one that catches the layer leaking into the format.

Out of order on purpose

PR 2 could be folded into PR 4 and PR 6 into PR 3. They are separate because a seam change and a persistence change are the two things most likely to break something that does not use them, and a stack that can be bisected is the point of the convention.