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