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>
93 lines
5.0 KiB
Markdown
93 lines
5.0 KiB
Markdown
# M9.4 microscopic environment rendering
|
|
|
|
Decision: [ADR-0080](../adr/0080-environment-presentation.md). Headers:
|
|
`include/evo/client/environment_view.hpp` (presentation values, freshness) and
|
|
`include/evo/render/environment.hpp` (rectangle projection). Neither includes SDL.
|
|
Dependency direction: world (read-only views) -> client views -> render
|
|
environment -> immutable `Frame` -> private SDL renderer. Nothing flows back.
|
|
|
|
```cpp
|
|
auto view = world::query_environment(fields, terrain, tick, footprint, mask);
|
|
auto presentation = client::present_environment(*view, slice_z); // owned copy
|
|
layer.accept(std::move(*presentation)); // rejects foreign/regressed
|
|
layer.observe({identity, authority_tick, field_watermark}); // later: stale?
|
|
render::build_environment(rects, layer.current(), layer.freshness(), camera, display);
|
|
```
|
|
|
|
## Presentation values
|
|
|
|
A presentation is one Z slice of 1..256 cells, strictly ordered by voxel (x, y),
|
|
with the source revision (world/frame, tick, field watermark) and request mask.
|
|
Cells copy chunk revision, the habitat box and volume, substrate, terrain material
|
|
and fill, per-field presence/quantity and moisture status. Validation rejects
|
|
inconsistent presence vs mask, quantities on non-present fields, habitat boxes
|
|
outside their voxel, volume mismatch, out-of-range voxels, mixed slices,
|
|
duplicates/unsorted cells and invalid saturation. No store pointer, ChunkView
|
|
token, native handle or authority capability is retained. A presentation stays
|
|
valid after its source stores are destroyed.
|
|
|
|
## Freshness and update ordering
|
|
|
|
`EnvironmentLayer` keeps at most one presentation (no history or queue) and the
|
|
newest observed authority revision. `accept` rejects another world/frame
|
|
(`foreign_world`) or any regression of tick, field watermark or a shared voxel's
|
|
chunk revision (`regressed`) without mutation. Equal revisions are accepted so a
|
|
camera-driven footprint change can replace the cells. `observe` records the
|
|
authority's latest revision (also before the first presentation); a regressed or
|
|
foreign watermark rejects. Freshness is:
|
|
|
|
| State | Meaning | Presentation |
|
|
|---|---|---|
|
|
| none | nothing accepted (or reset) | red chip, no cells |
|
|
| current | presentation equals newest observed revision | green chip |
|
|
| stale | authority advanced, or host validation failed (`mark_stale`) | amber chip, dimmed fills, amber voxel outlines |
|
|
|
|
A late presentation newer than the displayed one but older than the observed
|
|
watermark is accepted and shown stale. Restore/reconnect requires `reset`;
|
|
ADR-0052 restored stores are different owners, so their revisions need not continue.
|
|
|
|
## Encodings
|
|
|
|
Each visible cell emits: terrain square (material colour blended from void by fill;
|
|
unknown material IDs are cyan), habitat encoding, then a voxel outline when the voxel
|
|
is at least 8 logical units wide. Habitat encodings:
|
|
|
|
| Data | Encoding |
|
|
|---|---|
|
|
| present, nonzero | ramp(log2(quantity / habitat um^3) mapped from [-30, 12]) |
|
|
| present zero | black fill |
|
|
| requested but missing | 2x2 magenta/dark checker |
|
|
| not requested | hollow grey outline |
|
|
| moisture with zero water capacity | rust "undefined" fill |
|
|
| moisture available | ramp(saturation) linear in [0, 1] |
|
|
|
|
Mass is fg, energy pJ; both use density per cubic micrometre of the habitat's
|
|
effective volume. Values outside the ramp clamp to its ends; the eight-step legend
|
|
(bottom-left) shows the ramp, not physical units. Habitats under 4 logical units
|
|
collapse to one rectangle in the encoding's primary colour, so missing remains
|
|
magenta and not-requested grey. Nothing is interpolated between habitats and no
|
|
value is inferred from material IDs.
|
|
|
|
## Geometry and resource bounds
|
|
|
|
Projection uses the CAMERA_INPUT formula on voxel edges, so shared edges between
|
|
neighbouring voxels (including signed chunk seams) are computed from identical
|
|
world coordinates. Edges may lie on the exclusive world bound. Cells fully outside
|
|
the viewport emit nothing; others clip to `[0, width] x [0, height]` before float
|
|
conversion. Output is at most `256 * 9 + 9 = 2313` rectangles, within the 4096
|
|
frame limit including host UI. `build_environment` clears and reserves the
|
|
caller's buffer once; reuse keeps capacity constant. No textures or caches exist.
|
|
|
|
## Engineering app
|
|
|
|
`evo-client` hosts a local in-memory fixture authority: 16x8 habitats at z=-16000
|
|
with varied boxes, varying water and organic energy, present-zero phosphorus and
|
|
never-opened nitrogen/incident energy. Every 60 frames it advances its tick and
|
|
moves 1/8 of one site's water to a neighbour through `FieldStore::transfer`.
|
|
`--refresh-every N` (1..1000, default 1) refreshes the view every N authority ticks;
|
|
between refreshes the observed watermark shows the stale state. `--layer` selects
|
|
`water`, `nitrogen`, `phosphorus`, `organic-carbon`, `organic-nitrogen`,
|
|
`organic-phosphorus`, `organic-other`, `organic-energy`, `incident-energy`, `heat`
|
|
or `moisture`. The fixture is never persisted or published; M9.7 replaces it with
|
|
server views. It is not biology, an ecosystem or a world-generation rule.
|