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.
5.0 KiB
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.
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.
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:
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:
resolveandresolveUsedcopy 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
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.
public data class WorldToClip(val matrix: FloatArray) // 16 floats, row-major
public data class DepthRange(val near: Float, val far: Float)
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.
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
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.barrieris untouched. The reference pass has no cross-pass dependency.