Module tier 

Quality tiers: the engine’s capacity constants, resolved once (ADR-0045).

NFR §1 specifies two quality levels — a reduced tier holding 60 fps at 1080p on the ~2015-iGPU baseline, and a richer presentation on capable hardware. This module is where both live.

What a tier is

A TierConfig is a plain struct of capacity values: how many particles, how many segments, how large an internal grid may get. Nothing here changes what the engine draws, only how much of it — which is what makes Tier::Floor byte-identical to the pre-tier engine and what lets captures pin it (see below). A value that changes the content of a frame — the reaction-diffusion simulation grid, whose pattern scale moves with its resolution (ADR-0034) — deliberately does not live here.

That separation is a property of the consuming scene, not of this struct. The attractor draws its particles with an additive blend into a linear accumulation, so attractor_particles sets the total light in the frame as directly as it sets the sample count — Rich rendered every attractor preset three stops hot behind a green suite, because no capture pins Rich. What holds the claim up is deposit_scale dividing the deposit by the count (ADR-0065). The lesson generalizes: a count feeding an accumulating pass is a look value until something normalizes it. If a future field lands here for such a pass, that normalization is part of adding it.

Where the numbers come from

TierConfig::FLOOR is the pre-tier engine, constant for constant: each value’s former definition site now reads this struct, so no number exists twice. Its justifications came with it and are on the fields. TierConfig::RICH is calibrated against a midrange discrete GPU (RTX 3060 / RX 6600 class) on device — Plan 0044 Phase 4 — rather than asserted from a multiplier.

Resolution and the governor

The tier resolves once, at renderer construction, from an optional pin (RendererOptions); unpinned resolves Tier::Rich. An unpinned renderer may then be demoted to Tier::Floor by the frame-time governor — one way, once per session, never silently. A pinned tier never moves.

Headless capture is Tier::Floor by construction: Renderer::new_headless cannot produce any other tier, so every golden baseline stays byte-reproducible on the WARP software adapter and the suite’s cost does not scale with the rich tier. Renderer::new_headless_tiered is the deliberate opt-in the shot CLI’s --tier reaches.

Pure and GPU-free throughout — a tier is a set of numbers, so it is decided without a device and tested without one.

Structs

TierConfig

The capacity values a tier sets. Resolved once at renderer construction and read at construction/reconfigure time only — never branched on per frame.

Enums

Tier

Which quality tier a renderer is running (ADR-0045).

Constants

DEFAULT_DISPLAY_HZ

The display budget assumed when the frontend has not named a refresh rate — 60 Hz, the rate NFR §1’s floor is quoted at.

MIN_SAMPLES

Frames of history required before the governor will demote at all.

MISS_FACTOR

How far past the display budget a single frame must run to count as a miss.

MISS_FRACTION

What fraction of the observed frames must be misses before the governor demotes. Three quarters: high enough that an intermittently-heavy passage rides through, low enough that a genuine overload does not have to be unanimous (a demotion is triggered by sustained pressure, and a real overload still has fast frames in it — a cheap preset in the rotation, a dissolve that ended).

REFERENCE_PX

The render target the attractor’s sample density is anchored to: 640x360, 230 400 pixels.

Functions

attractor_budget

The attractor’s drawn sample budget for a target of target_px pixels, before a preset’s [particles] density narrows it further (ADR-0140).

budget_secs

The frame budget for a display running at hz, in seconds. Falls back to DEFAULT_DISPLAY_HZ for a value that is not a usable rate, so a frontend that cannot read its monitor still gets a governed session rather than an ungoverned one.

should_demote

The governor’s whole decision: whether to demote tier right now.

sustained_miss

Whether a frame-time series shows a sustained miss of the display budget, which is the one condition that demotes Tier::Rich to Tier::Floor (ADR-0045).

tier_change_permitted

Whether a runtime tier change is allowed at all (ADR-0054): only on a context that has a surface.