4.7 KiB
M9.3 camera and input contract
Decision: ADR-0079.
Headers: include/evo/client/camera.hpp, input.hpp, application.hpp.
No SDL types enter the camera/input contracts. Neither library mutates or links
the simulation. The world coordinate header supplies numeric bounds only.
Coordinates and camera
WorldPoint stores presentation doubles in millimetres in a caller-selected
region-local XY plane, +Y up. Its half-open range matches M5/M6 voxel bounds
times the 1000 mm pitch: [-1048576000, 1048576000) on both axes. Do not mix
frames/worlds or silently map the old periodic particle fixture into this plane.
M6 micrometre habitat offsets require explicit conversion to mm at M9.4 projection.
ScreenPoint is logical window space, top-left origin and +Y down. PixelPoint
is drawable space. Viewport dimensions must be 1..32768; zero/minimized surfaces
are not a camera viewport. Application skips viewport updates while zero-area.
units_per_mm is logical units per mm, bounded [0.0001, 10000]. Screen/pixel
conversions validate finite values within +/-1e15; world projection may be
offscreen. Clip to the viewport before converting to renderer float primitives.
The projection is screen_x = (world_x - centre_x) * scale + width/2 and
screen_y = (centre_y - world_y) * scale + height/2. Pixel conversions apply
pixel_width/width and pixel_height/height independently. Display content scale
is not a further multiplier. Round trips are approximate; tests use 1e-6 mm
tolerance for their bounded fixtures, not a global deterministic-state promise.
Resize retains centre/zoom. Pan moves the camera in screen-axis directions by at most 32768 logical units per component per call. Positive X moves the camera right; positive Y moves it down. Zoom requires a positive finite factor and an anchor inside the logical viewport. It preserves the world point under that anchor; requests beyond zoom/world bounds reject without mutation. These are engineering numeric limits, not biological movement or world-size rules.
Input and host ordering
InputState has eight held-key slots, one cursor and bounded accumulated wheel
steps ([-8,8], individual inputs must be finite and within [-128,128]). Navigation
consumes wheel steps once; held pan directions persist until release/admission
loss. Pointer events require finite coordinates within +/-32768 logical units.
Invalid values reject rather than entering camera math.
Intention carries sequence, tick and a signed movement vector. Cardinal
components are +/-1000, diagonals +/-707 (norm <=1000); opposite keys cancel.
This is direction/demand, never velocity, distance, energy or accepted position.
Sequences start at 1 by default; the host can seed a local stream counter but
that is not an authenticated resume grant. Successful samples require strictly
increasing ticks. Exhaustion/stale tick rejection consumes neither tick nor
sequence. Inactive input still samples a neutral intention, allowing later
session adapters to express stopped input. No pending command queue exists.
Use poll_events() -> read current window/navigation -> update camera ->
sample_intention(tick) -> build immutable frame -> present(frame).
step(frame) retains the combined poll/present convenience for lifecycle tests.
Focus loss, hidden/minimized/closed/failed/zero-area state, or UI capture clears
held state. A fresh non-repeat keydown is needed to re-arm; releases always
clear keys. UI code calls set_ui_capture before world polling. Tab toggles an
engineering capture mode in the adapter; repeats do not retoggle it. Window
close remains available while captured.
A 256-event saturated batch clears admission. Remaining queued keydowns are ignored until a later poll drains the backlog; the drained state remains neutral until a fresh keydown. This prevents delayed releases from sustaining movement. All window-specific input filters the owned SDL window ID.
Releasing capture through the external UI API also drains the pending SDL batch before re-admission, preventing keys queued while captured from becoming world presses. Poll once after release, then fresh presses are admitted. The engineering Tab toggle is processed in event order, so subsequent presses after that toggle belong to its new capture state.
The standalone host uses an increasing local fixture tick, not server time. It draws a world-anchored rectangle, a capture indicator and an intention dot. Camera panning uses 400 logical units/second with elapsed time clamped to 0.1 s; wheel zoom uses 2^(steps/4). These are presentation controls. No network messages, world modifications or organism actions occur. M9.6 must bind intention ticks and counters to secure sessions; the server independently validates all requests.