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.
90 lines
4.3 KiB
Markdown
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.
|