94 lines
3.4 KiB
Markdown
94 lines
3.4 KiB
Markdown
---
|
|
id: PLN-0026
|
|
ticket: deferred-overlay-and-primitive-composition
|
|
title: Plan - GFX Overlay Contract and Spec Propagation
|
|
status: accepted
|
|
created: 2026-04-18
|
|
completed:
|
|
tags: [gfx, runtime, spec, overlay, primitives, hud]
|
|
---
|
|
|
|
## Objective
|
|
|
|
Propagate `DEC-0016` into the canonical specs and internal contracts so `gfx.*` primitives are defined as deferred final overlay/debug operations outside `FrameComposer`.
|
|
|
|
## Background
|
|
|
|
`DEC-0016` locks a new semantic boundary:
|
|
|
|
- `FrameComposer` remains the owner of canonical game-frame composition;
|
|
- `gfx.*` primitives and `draw_text(...)` become deferred final overlay/debug operations;
|
|
- that overlay lives outside `FrameComposer` and is drained after `hud_fade`.
|
|
|
|
Execution must start by updating the normative contract before implementation changes spread through runtime and drivers.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- update canonical runtime/gfx spec text to describe deferred overlay semantics
|
|
- update any ABI-facing or developer-facing docs that still imply direct stable writes to `back`
|
|
- align local contract comments and module docs where they currently imply immediate-write semantics as the stable model
|
|
|
|
### Excluded
|
|
- implementation of the overlay subsystem
|
|
- runtime frame-end integration
|
|
- final repository-wide CI
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Update canonical graphics/runtime documentation
|
|
|
|
**What:**
|
|
Publish the new semantic contract for `gfx.*` primitives.
|
|
|
|
**How:**
|
|
- Update the canonical runtime/gfx spec so `gfx.draw_text(...)` and peer primitives are described as deferred final overlay/debug operations.
|
|
- State explicitly that primitives are not part of canonical scene/sprite/HUD composition.
|
|
- State the ordering rule that overlay/debug is drained after `hud_fade`.
|
|
- Ensure the no-scene and scene-bound paths are described consistently.
|
|
|
|
**File(s):**
|
|
- canonical runtime/gfx spec files under `docs/specs/runtime/`
|
|
|
|
### Step 2 - Align implementation-facing contract text
|
|
|
|
**What:**
|
|
Remove stale implementation comments that imply immediate stable writes to the framebuffer.
|
|
|
|
**How:**
|
|
- Inspect module-level comments and trait docs in `hal`, `drivers`, and runtime code for language that now contradicts `DEC-0016`.
|
|
- Update only the contract-bearing comments and docs that materially affect maintenance and implementation clarity.
|
|
|
|
**File(s):**
|
|
- `crates/console/prometeu-hal/src/gfx_bridge.rs`
|
|
- `crates/console/prometeu-drivers/src/gfx.rs`
|
|
- `crates/console/prometeu-drivers/src/frame_composer.rs`
|
|
- runtime-adjacent modules where frame ordering is described
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
- none required for pure doc propagation
|
|
|
|
### Integration Tests
|
|
- none required for pure doc propagation
|
|
|
|
### Manual Verification
|
|
- inspect the updated spec and local contract comments to confirm they no longer describe primitives as stable direct writes to `back`
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] Canonical spec text describes `gfx.*` primitives as deferred final overlay/debug operations.
|
|
- [ ] The spec states that overlay/debug is outside `FrameComposer`.
|
|
- [ ] The spec states that overlay/debug is drained after `hud_fade`.
|
|
- [ ] Local implementation-facing contract comments no longer imply immediate-write semantics as the stable model.
|
|
|
|
## Dependencies
|
|
|
|
- Source decision: `DEC-0016`
|
|
|
|
## Risks
|
|
|
|
- Missing a normative doc location would leave code and published contract divergent.
|
|
- Over-editing local comments could unintentionally restate design choices outside the scope of `DEC-0016`.
|