# 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.