Files
umamo-reference-layer/sketch/render/ReferenceCamera.kt
T
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

119 lines
4.8 KiB
Kotlin

package org.umamo.render
import kotlin.math.cos
import kotlin.math.sin
/**
* An orbit orthographic camera over the reference layer.
*
* World axes: X right, Y depth, Z up - Umamo's existing convention, the one
* `PuppetModel.worldOriginX` / `worldOriginZ` and the world axis lines already use. At
* yaw == pitch == 0 the basis is forward +Y, right +X, up +Z, and the projection agrees
* exactly with `ViewportCamera.worldToNdc`. That agreement is the anchor of the design: an
* unrotated reference layer sits in the drawing plane, and rotation is the only thing that
* separates it from the puppet.
*
* Pure, like `ViewportCamera`: every helper returns a new camera and touches no GL, so the
* maths unit-tests without a context.
*
* The pitch clamp is not cosmetic. At pitch == ±90 the camera looks along the world up axis,
* the screen-right basis vector becomes a zero vector, and the projection still returns a
* number - the model collapses to a line and nothing reports it. The clamp therefore belongs
* in the pure model, not in the drag handler. Verified in verify/verify.py.
*
* @property Float targetX World X the camera looks at.
* @property Float targetY World Y (depth) the camera looks at.
* @property Float targetZ World Z (up) the camera looks at.
* @property Float yaw Rotation about the world up axis, degrees.
* @property Float pitch Elevation above the target, degrees, clamped to ±MAX_PITCH_DEG.
* @property Float zoom Screen pixels per world unit, shared with the viewport camera.
*/
data class ReferenceCamera(
val targetX: Float,
val targetY: Float,
val targetZ: Float,
val yaw: Float,
val pitch: Float,
val zoom: Float,
) {
/** The camera's orthonormal basis: forward is the view direction, right is screen right, up is screen up. */
data class Basis(val forwardX: Float, val forwardY: Float, val forwardZ: Float, val rightX: Float, val rightY: Float, val rightZ: Float, val upX: Float, val upY: Float, val upZ: Float)
/**
* The basis at the camera's current angles, with pitch clamped.
*
* @return Basis The basis.
*/
fun basis(): Basis {
val y = yaw * DEG
val p = clampedPitch() * DEG
return Basis(
-cos(p) * sin(y), cos(p) * cos(y), -sin(p),
cos(p) * cos(y), cos(p) * sin(y), 0f,
-sin(p) * sin(y), sin(p) * cos(y), cos(p),
)
}
/**
* The row-major 4x4 world-to-clip matrix the vertex shader applies.
*
* x and y are the orthographic NDC scales, the same scales `ViewportCamera.worldToNdc`
* produces. z is the depth, mapped from [near, far] to [0, 1] so a nearer fragment has the
* smaller value and `DepthFunc.Less` picks it.
*
* @param Int viewportWidth Viewport width in pixels.
* @param Int viewportHeight Viewport height in pixels.
* @param Float near Near depth, relative to the target.
* @param Float far Far depth, relative to the target.
* @return FloatArray 16 floats, row-major.
*/
fun worldToClip(viewportWidth: Int, viewportHeight: Int, near: Float, far: Float): FloatArray {
val b = basis()
val scaleX = 2f * zoom / viewportWidth
val scaleY = 2f * zoom / viewportHeight
val scaleZ = 1f / (far - near)
val out = FloatArray(16)
// One row per basis axis. The translation term is -(axis · target) * scale, which is what
// puts the target at the NDC origin; the depth row additionally shifts by -near so the near
// plane lands on 0 rather than on a negative value the depth test cannot represent.
val axes = arrayOf(
floatArrayOf(b.rightX, b.rightY, b.rightZ, scaleX),
floatArrayOf(b.upX, b.upY, b.upZ, scaleY),
floatArrayOf(b.forwardX, b.forwardY, b.forwardZ, scaleZ),
)
for (r in 0 until 3) {
val axis = axes[r]
val scale = axis[3]
val dot = axis[0] * targetX + axis[1] * targetY + axis[2] * targetZ
out[r * 4] = axis[0] * scale
out[r * 4 + 1] = axis[1] * scale
out[r * 4 + 2] = axis[2] * scale
out[r * 4 + 3] = -dot * scale
}
out[2 * 4 + 3] -= near * scaleZ
out[15] = 1f
return out
}
/** Pans by a screen-pixel drag delta, grab style, Y carrying the screen-down sign flip. */
fun panByScreen(deltaXpx: Float, deltaYpx: Float): ReferenceCamera =
copy(targetX = targetX - deltaXpx / zoom, targetZ = targetZ + deltaYpx / zoom)
/** Orbits by a drag delta. Pitch is clamped here, at the model, not in the caller. */
fun orbitBy(deltaYawDeg: Float, deltaPitchDeg: Float): ReferenceCamera =
copy(yaw = yaw + deltaYawDeg, pitch = clampedPitch() + deltaPitchDeg)
private fun clampedPitch(): Float = pitch.coerceIn(-MAX_PITCH_DEG, MAX_PITCH_DEG)
companion object {
/** Pitch is clamped to the open interval; ±90 collapses the screen-right axis. */
const val MAX_PITCH_DEG: Float = 89.9f
/** Shared with ViewportCamera so a linked camera cannot disagree about the limits. */
const val MIN_ZOOM: Float = 0.02f
const val MAX_ZOOM: Float = 64f
private const val DEG = 0.017453292519943295f
}
}