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

90 lines
4.3 KiB
Markdown

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