Add SDL-free owned EnvironmentPresentation copied from M6.3 views (no store pointers or validation tokens), a single-slot EnvironmentLayer that rejects foreign/regressed updates and reports none/current/stale against observed authority watermarks, and a bounded camera projection with explicit missing, not-requested, present-zero, undefined-moisture and stale encodings (at most 2313 clipped rectangles, reused buffer). The engineering app renders a local in-memory fixture authority with configurable refresh cadence and layer selection. ADR-0080 records the decision; validation evidence and limits are in VALIDATION.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
80 lines
4.8 KiB
Markdown
80 lines
4.8 KiB
Markdown
# M9.3 camera and input contract
|
|
|
|
Decision: [ADR-0079](../adr/0079-camera-and-input-intentions.md).
|
|
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 capture indicator, an intention dot and (since M9.4) the environment
|
|
fixture. 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. Input never
|
|
sends network messages, modifies the world or acts for an organism; the M9.4
|
|
fixture authority's own water moves are independent of input. M9.6 must bind intention ticks
|
|
and counters to secure sessions; the server independently validates all requests.
|