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