Files
aevolution/docs/engineering/ENVIRONMENT_RENDERING.md
T
dingoandClaude Opus 5.5 feca07f791 Implement M9.4 revision-tagged microscopic environment rendering
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>
2026-10-01 17:45:53 -04:00

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.