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.
119 lines
4.8 KiB
Kotlin
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
|
|
}
|
|
} |