docs(A.5 T27): spec + plan amendments for T22.5 + ship
Spec (2026-05-09-phase-a5-two-tier-streaming-design.md): - §2 acceptance metrics reshaped from absolute 240 FPS to refresh-rate-relative + per-preset (95th-pct ≤ 1000ms/refresh standstill; ≤ 1.5× walking) to match the Quality Preset reality. - New §4.10 Quality Preset System (T22.5): enum Low/Medium/High/Ultra, QualitySettings schema, canonical preset values table, env-var override table, wiring notes (GameWindow.OnLoad + ReapplyQualityPreset), MSAA mid-session unsupported caveat, file list, test count (12). - New §11 What was deferred: 8 items (Tier 1 cache, lifestone, JobKind plumbing, Tier 2/3, ToEntries alloc, InvalidateEntity wiring, High preset retest). Former §11 References renumbered to §12. Plan (2026-05-09-phase-a5-two-tier-streaming.md): - New Task 22.5 section inserted between T22 and T23: full inline spec with schema, preset table, env-var list, wiring steps, acceptance criteria, deferred items, commit SHAs. Includes file-name corrections (SettingsState → DisplaySettings, DisplayTab → SettingsPanel). - Self-review cross-check table: new §4.10 row pointing at T22.5. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erik
parent
9b49009dd5
commit
a28a5b7583
2 changed files with 224 additions and 12 deletions
|
|
@ -2046,6 +2046,75 @@ git commit -m "feat(A.5 T22): fog params wired from N₁/N₂ + ACDREAM_FOG_*_MU
|
|||
|
||||
---
|
||||
|
||||
## Task 22.5 (NEW — Quality Preset System)
|
||||
|
||||
**Inserted between T22 (fog wiring) and T23 (DIAG budgets). Added mid-execution at user's direction. Estimate: ~1 day.**
|
||||
|
||||
**Background:** User added this task between T22 and T23 with a complete inline spec. Shipped as commits `afa4200` (schema + tests) and `28d2c60` (wiring). Design spec at §4.10 of the A.5 spec doc.
|
||||
|
||||
**Files:**
|
||||
- Create: `src/AcDream.UI.Abstractions/Settings/QualityPreset.cs`
|
||||
- Modify: `src/AcDream.UI.Abstractions/Settings/DisplaySettings.cs` (add `Quality` field)
|
||||
- NOTE: `SettingsState.cs` (from the original inline spec) did not exist; `Quality` went onto `DisplaySettings` instead — the natural home for display-related settings.
|
||||
- Modify: `src/AcDream.UI.Abstractions/Panels/Settings/SettingsPanel.cs` (Display tab Quality dropdown)
|
||||
- NOTE: the original inline spec named `DisplayTab.cs`; the actual file is `SettingsPanel.cs` with a `RenderDisplayTab` method. Same intent, different file name.
|
||||
- Modify: `src/AcDream.App/Rendering/GameWindow.cs` (apply preset on launch + on mid-session change via `ReapplyQualityPreset`)
|
||||
- Create: `tests/AcDream.UI.Abstractions.Tests/Settings/QualityPresetTests.cs`
|
||||
|
||||
**Schema:**
|
||||
|
||||
```csharp
|
||||
public enum QualityPreset { Low, Medium, High, Ultra }
|
||||
|
||||
public readonly record struct QualitySettings(
|
||||
int NearRadius, int FarRadius,
|
||||
int MsaaSamples, int AnisotropicLevel,
|
||||
bool AlphaToCoverage,
|
||||
int MaxCompletionsPerFrame);
|
||||
```
|
||||
|
||||
`QualitySettings.From(preset)` returns canonical values per preset:
|
||||
|
||||
| Preset | NearRadius | FarRadius | MsaaSamples | AnisotropicLevel | AlphaToCoverage | MaxCompletionsPerFrame |
|
||||
|---|---|---|---|---|---|---|
|
||||
| Low | 2 | 5 | 0 | 4 | false | 2 |
|
||||
| Medium | 3 | 8 | 2 | 8 | false | 3 |
|
||||
| High | 4 | 12 | 4 | 16 | true | 4 |
|
||||
| Ultra | 5 | 15 | 4 | 16 | true | 6 |
|
||||
|
||||
`QualitySettings.WithEnvOverrides(baseSettings)` applies per-field env-var overrides:
|
||||
`ACDREAM_NEAR_RADIUS`, `ACDREAM_FAR_RADIUS`, `ACDREAM_MSAA_SAMPLES`,
|
||||
`ACDREAM_ANISOTROPIC`, `ACDREAM_A2C`, `ACDREAM_MAX_COMPLETIONS_PER_FRAME`.
|
||||
|
||||
**Wiring:**
|
||||
|
||||
1. `DisplaySettings.Quality` persists via the existing `settings.json` infrastructure (Phase L.0).
|
||||
2. `SettingsPanel.RenderDisplayTab` Combo widget for Quality dropdown.
|
||||
3. `GameWindow.OnLoad` applies preset: streamer + controller built with preset's
|
||||
`NearRadius`/`FarRadius`; `TerrainAtlas.SetAnisotropic` from preset; `WindowOptions.Samples`
|
||||
from preset (window creation time only); `WbDrawDispatcher.AlphaToCoverage` from preset;
|
||||
`StreamingController.MaxCompletionsPerFrame` from preset.
|
||||
4. Env-var overrides applied per field via `WithEnvOverrides`; logged at startup.
|
||||
5. Mid-session change via F11 → Quality dropdown → `ReapplyQualityPreset` rebuilds the
|
||||
streaming pipeline. MSAA samples mid-session change is structurally unsupported
|
||||
(OpenGL requires window recreation); logs a warning.
|
||||
|
||||
**Acceptance criteria (as shipped):**
|
||||
|
||||
- Standstill: at user's selected preset, 95% of frames hit ≤ (1000ms / monitor refresh).
|
||||
- Walking: 95% ≤ 1.5× (1000ms / monitor refresh).
|
||||
- Visual gate: same on all presets.
|
||||
|
||||
**Out of scope (deferred):**
|
||||
|
||||
- Auto-detect first-launch preset (Phase A.6 / N.6.5).
|
||||
- Adaptive runtime preset drop on budget miss.
|
||||
- Per-feature toggles below preset level.
|
||||
|
||||
**Commits:** `afa4200` (schema + tests), `28d2c60` (wiring).
|
||||
|
||||
---
|
||||
|
||||
## Task 23: Per-subsystem regression budget logging in DIAG output
|
||||
|
||||
**Files:**
|
||||
|
|
@ -2429,6 +2498,7 @@ Spec coverage cross-check:
|
|||
| §4.6 Bucketing Change #3 (sub-LB cull) | conditional — added as T18.5 only if Tasks 17+18 don't hit 2.0ms budget |
|
||||
| §4.7 TerrainModernRenderer | T15 (AddLandblockWithMesh entry); no structural change |
|
||||
| §4.8 Fog tuning | T22 |
|
||||
| §4.10 Quality Preset System (NEW — mid-execution addition) | T22.5 |
|
||||
| §4.9.1 Mipmaps | T19 |
|
||||
| §4.9.2 A2C with MSAA | T20 |
|
||||
| §4.9.3 Depth-write audit | T21 |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue