105 lines
3.9 KiB
Markdown
105 lines
3.9 KiB
Markdown
---
|
|
id: PLN-0027
|
|
ticket: deferred-overlay-and-primitive-composition
|
|
title: Plan - Deferred GFX Overlay Subsystem
|
|
status: accepted
|
|
created: 2026-04-18
|
|
completed:
|
|
tags: [gfx, runtime, overlay, primitives, text, drivers]
|
|
---
|
|
|
|
## Objective
|
|
|
|
Introduce a dedicated deferred overlay/debug subsystem for `gfx.*` primitives outside `FrameComposer`, with command capture for `draw_text(...)` and the primitive family selected for the first migration.
|
|
|
|
## Background
|
|
|
|
`DEC-0016` requires primitive/text overlay ownership to remain outside `FrameComposer` while still allowing shared raster helpers and low-level optimizations internally. The new subsystem must preserve semantic separation from scene/sprite/HUD composition.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- introduce an overlay/debug command queue or equivalent subsystem outside `FrameComposer`
|
|
- route `gfx.draw_text(...)` into deferred command capture instead of stable direct framebuffer writes
|
|
- route the chosen V1 primitive family into the same deferred overlay/debug path
|
|
- keep raster helper reuse allowed without merging semantic ownership
|
|
|
|
### Excluded
|
|
- runtime frame-end sequencing
|
|
- no-scene/scene parity tests at the runtime level
|
|
- final repository-wide CI
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Define overlay/debug state ownership in drivers
|
|
|
|
**What:**
|
|
Create the subsystem that owns deferred `gfx.*` overlay/debug commands.
|
|
|
|
**How:**
|
|
- Add a dedicated owner adjacent to `Gfx`/`Hardware`, but not inside `FrameComposer`.
|
|
- Define the minimal command model required for V1 operations.
|
|
- Keep the subsystem screen-space and explicitly pipeline-agnostic relative to `composer.*`.
|
|
|
|
**File(s):**
|
|
- `crates/console/prometeu-drivers/src/*`
|
|
- `crates/console/prometeu-hal/src/*` if bridge traits need extension
|
|
|
|
### Step 2 - Route text and selected primitives into deferred capture
|
|
|
|
**What:**
|
|
Stop treating text/primitives as stable direct writes.
|
|
|
|
**How:**
|
|
- Change `gfx.draw_text(...)` to enqueue deferred overlay/debug work.
|
|
- Migrate the selected V1 primitive set into the same deferred path.
|
|
- Keep any remaining unmigrated primitives either explicitly out of scope or routed consistently if they are already part of the accepted V1 set.
|
|
- Preserve internal raster helper reuse where useful.
|
|
|
|
**File(s):**
|
|
- `crates/console/prometeu-drivers/src/gfx.rs`
|
|
- runtime dispatch call sites that submit `gfx.*` primitives
|
|
|
|
### Step 3 - Add local driver-level tests for deferred capture semantics
|
|
|
|
**What:**
|
|
Prove that overlay/debug commands are captured separately from game composition state.
|
|
|
|
**How:**
|
|
- Add tests that assert text/primitives do not need direct stable writes to `back` to survive until overlay drain.
|
|
- Add tests that assert the overlay owner is independent from `FrameComposer` state.
|
|
|
|
**File(s):**
|
|
- `crates/console/prometeu-drivers/src/gfx.rs`
|
|
- new or existing driver test modules
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
- command capture tests for `draw_text(...)`
|
|
- tests for each migrated V1 primitive class
|
|
- tests proving overlay/debug state is owned outside `FrameComposer`
|
|
|
|
### Integration Tests
|
|
- none in this plan; runtime-level ordering is covered by the next plan
|
|
|
|
### Manual Verification
|
|
- inspect driver ownership boundaries to confirm `FrameComposer` does not gain overlay/debug state
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] A dedicated deferred overlay/debug subsystem exists outside `FrameComposer`.
|
|
- [ ] `gfx.draw_text(...)` is captured as deferred overlay/debug work.
|
|
- [ ] The selected V1 primitive family is captured through the same subsystem.
|
|
- [ ] Driver-level tests prove overlay/debug state is operationally separate from canonical game composition state.
|
|
|
|
## Dependencies
|
|
|
|
- Source decision: `DEC-0016`
|
|
- Prefer to execute after `PLN-0026`
|
|
|
|
## Risks
|
|
|
|
- Accidentally reusing `FrameComposer` storage or state would violate the accepted ownership boundary.
|
|
- Migrating only part of the primitive family without explicit scoping could create inconsistent semantics across `gfx.*`.
|