primitives pipeline adjustments
This commit is contained in:
@@ -0,0 +1,140 @@
|
||||
---
|
||||
id: AGD-0028
|
||||
ticket: deferred-overlay-and-primitive-composition
|
||||
title: Deferred Overlay and Primitive Composition over FrameComposer
|
||||
status: accepted
|
||||
created: 2026-04-18
|
||||
updated: 2026-04-18
|
||||
resolved: 2026-04-18
|
||||
decision: DEC-0016
|
||||
tags: [gfx, runtime, render, frame-composer, overlay, primitives, hud]
|
||||
---
|
||||
|
||||
## Contexto
|
||||
|
||||
`FrameComposer.render_frame()` hoje recompõe o `back` no fim da logical frame. Quando há scene bound, o caminho `render_scene_from_cache(...)` limpa o buffer e desenha scene + sprites, o que apaga qualquer primitive ou `draw_text(...)` emitido antes via `gfx`.
|
||||
|
||||
Isso expôs um conflito de modelo:
|
||||
|
||||
- `composer.*` já é o caminho canônico de orquestração de frame;
|
||||
- `gfx.draw_text(...)` e demais primitives ainda escrevem diretamente no `back`;
|
||||
- o runtime só chama `render_frame()` no final do frame, então a escrita imediata em `back` deixou de ser semanticamente estável.
|
||||
- As primitives de `gfx` não são o mecanismo desejado para composição de jogos com scene/tile/sprite; elas existem principalmente como debug, instrumentação visual e artefatos rápidos.
|
||||
|
||||
Conteúdo relevante migrado de [AGD-0010](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/discussion/workflow/agendas/AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md):
|
||||
|
||||
- a arquitetura aceita continua sendo de framebuffer destrutivo em memória, não scene graph ou renderer tipo GPU;
|
||||
- otimizações em primitives devem preservar a semântica observável, mesmo quando ganharem fast paths internos;
|
||||
- existe preocupação explícita com custo por classe de primitive e com orçamento de memória no alvo handheld;
|
||||
- caminhos de spans/linhas/clears são desejáveis como aceleração interna, mas sem reabrir o modelo operacional do pipeline do jogo.
|
||||
|
||||
## Problema
|
||||
|
||||
Precisamos decidir qual é o modelo canônico para primitives e texto no pipeline pós-`FrameComposer`.
|
||||
|
||||
Sem isso:
|
||||
|
||||
- texto e primitives continuam com comportamento dependente da ordem interna do renderer;
|
||||
- o stress test e qualquer cartridge que combine `composer.*` com `gfx.*` terão resultado inconsistente;
|
||||
- fica indefinido se primitives pertencem ao mundo, ao HUD, ou a um overlay final.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
- `draw_text(...)` e primitives screen-space não podem depender de escrita imediata em `back`.
|
||||
- Para esta thread, primitives de `gfx` devem permanecer agnósticas ao pipeline canônico de render do jogo e não devem ser mescladas semanticamente com tiles/sprites.
|
||||
- A ordem de composição precisa ser explícita e estável: `scene -> sprites -> HUD -> primitives/debug overlay`, ou outra ordem formal equivalente.
|
||||
- Precisamos decidir se o contrato público de `gfx.*` muda semanticamente sem mudar ABI, ou se parte dessa superfície migra para `composer.*`.
|
||||
- A solução deve preservar o caminho sem scene bound.
|
||||
- A implementação deve evitar contaminar a infraestrutura de `gfx` responsável por scene, sprites e HUD com estado misto de overlay/debug; se necessário, o overlay deve ter fila/fase própria.
|
||||
- melhorias internas de primitive path devem continuar permitidas, desde que não mudem a semântica de overlay final e não exijam buffers extras incompatíveis com o orçamento de memória aceito.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao 1 - Manter escrita direta em `back`
|
||||
|
||||
- **Abordagem:** manter `gfx.draw_text(...)` e primitives rasterizando imediatamente.
|
||||
- **Pro:** zero mudança estrutural agora.
|
||||
- **Contra:** o modelo continua quebrado sempre que `render_frame()` recompõe o buffer depois.
|
||||
- **Tradeoff:** só funciona de forma confiável fora do caminho canônico do `FrameComposer`.
|
||||
|
||||
### Opcao 2 - Fila única de draw commands pós-scene/pós-sprite
|
||||
|
||||
- **Abordagem:** transformar texto e primitives em comandos diferidos, drenados depois de `scene + sprites`.
|
||||
- **Pro:** resolve o problema imediato de overlay/HUD e estabiliza o stress test.
|
||||
- **Contra:** mistura HUD e primitives/debug sob o mesmo conceito, reduzindo clareza contratual mesmo quando a ordem prática for a mesma.
|
||||
- **Tradeoff:** simples para V1, mas semanticamente mais fraco do que separar overlay de jogo e overlay de debug.
|
||||
|
||||
### Opcao 3 - Separar HUD diferido de primitives/debug overlay final
|
||||
|
||||
- **Abordagem:** tratar `gfx.draw_text(...)` e demais primitives de `gfx` como overlay/debug final, separado da composição canônica de jogo (`scene + sprites + HUD`).
|
||||
- **Pro:** casa com a intenção declarada para `gfx.*`: debug, artefato rápido e instrumentação visual acima do frame do jogo.
|
||||
- **Contra:** exige modelar explicitamente uma fase extra no pipeline.
|
||||
- **Tradeoff:** aumenta a clareza contratual e evita mesclar primitives com o domínio de jogo.
|
||||
|
||||
### Opcao 4 - Manter HUD e primitives no mesmo estágio final, mas com categorias separadas
|
||||
|
||||
- **Abordagem:** drenar HUD e primitives ambos no fim do frame, porém com filas/categorias distintas e ordem formal `HUD -> primitives`.
|
||||
- **Pro:** preserva implementação próxima entre caminhos similares, mantendo contrato separado.
|
||||
- **Contra:** é mais custoso que a opção 3 sem entregar muito valor adicional imediato.
|
||||
- **Tradeoff:** bom se já houver expectativa de HUD canônico separado no curtíssimo prazo.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Seguir com a **Opcao 3**.
|
||||
|
||||
Minha recomendação é:
|
||||
|
||||
- retirar a escrita direta em `back` como contrato operacional para `gfx.draw_text(...)` e demais primitives de `gfx`;
|
||||
- introduzir uma fila diferida canônica de primitives/debug overlay drenada no fim do frame;
|
||||
- tratar `gfx.*` primitive/text como superfície agnóstica ao pipeline de jogo e explicitamente acima da composição canônica;
|
||||
- não misturar semanticamente primitives com scene/tile/sprite/HUD.
|
||||
- evitar compartilhar indevidamente o mesmo mecanismo operacional de composição entre overlay/debug e os caminhos de scene/sprite/HUD, mesmo quando o backend de rasterização reutilizado for o mesmo.
|
||||
|
||||
Ordem recomendada para o frame canônico:
|
||||
|
||||
1. limpar/compor scene;
|
||||
2. compor sprites;
|
||||
3. compor HUD canônico, se existir;
|
||||
4. aplicar `scene_fade`;
|
||||
5. aplicar `hud_fade`;
|
||||
6. drenar primitives/debug overlay de `gfx.*`.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- `draw_text(...)` e as demais primitives de `gfx` entram todas na mesma família de overlay final já na V1, ou começamos só com `draw_text(...)`?
|
||||
- `render_no_scene_frame()` deve usar a mesma fila diferida para manter semântica idêntica com e sem scene?
|
||||
- HUD canônico precisa existir explicitamente nesta mesma thread, ou pode continuar implícito/externo enquanto as primitives já migram para overlay final?
|
||||
- quais fast paths internos de primitives continuam desejáveis nessa nova fase, por exemplo spans horizontais/verticais, fills e clears, sem misturar isso com a composição do jogo?
|
||||
- o overlay/debug final precisa de dirtying próprio por classe de primitive ou isso pode ficar fora da primeira migração?
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
Esta agenda pode ser encerrada quando tivermos uma resposta explícita para:
|
||||
|
||||
- o destino semântico de `draw_text(...)`;
|
||||
- se haverá uma fila própria para primitives/debug overlay e qual a relação dela com HUD;
|
||||
- a ordem canônica de composição do frame;
|
||||
- o escopo exato da primeira migração implementável sem reabrir o restante do pipeline.
|
||||
|
||||
## Resolucao Parcial
|
||||
|
||||
Direção já aceita nesta agenda:
|
||||
|
||||
- primitives e `draw_text(...)` de `gfx.*` devem ser tratadas como overlay/debug final;
|
||||
- esse overlay deve ser drenado **depois** de `hud_fade`;
|
||||
- scene, sprites e HUD canônico não devem ser semanticamente misturados com o overlay/debug;
|
||||
- a implementação deve preservar separação operacional suficiente para que o `gfx` usado pelo pipeline do jogo não passe a depender do estado transitório de primitives/debug;
|
||||
- otimizações de primitive path discutidas na `AGD-0010` continuam válidas, mas passam a operar dentro do domínio de overlay/debug final, não como parte da composição canônica de scene/sprite/HUD.
|
||||
|
||||
## Resolucao
|
||||
|
||||
Esta agenda fica aceita com os seguintes pontos fechados:
|
||||
|
||||
- `gfx.draw_text(...)` e as demais primitives públicas de `gfx.*` pertencem à mesma família V1 de overlay/debug final;
|
||||
- esse overlay/debug fica **fora** do `FrameComposer`;
|
||||
- `FrameComposer` continua restrito à composição canônica do jogo (`scene`, `sprites` e HUD canônico quando existir);
|
||||
- o overlay/debug deve ser drenado depois de `hud_fade`;
|
||||
- o caminho sem scene bound deve observar a mesma semântica final de overlay/debug;
|
||||
- HUD canônico explícito não faz parte desta thread e pode permanecer implícito/externo por enquanto;
|
||||
- fast paths internos de primitives continuam permitidos, desde que preservem a semântica observável do overlay/debug final;
|
||||
- dirtying granular ou otimizações finas por classe de primitive não fazem parte da primeira migração normativa desta thread.
|
||||
+150
@@ -0,0 +1,150 @@
|
||||
---
|
||||
id: DEC-0016
|
||||
ticket: deferred-overlay-and-primitive-composition
|
||||
title: Deferred GFX Overlay Outside FrameComposer
|
||||
status: accepted
|
||||
created: 2026-04-18
|
||||
accepted: 2026-04-18
|
||||
agenda: AGD-0028
|
||||
plans: [PLN-0026, PLN-0027, PLN-0028, PLN-0029]
|
||||
tags: [gfx, runtime, render, frame-composer, overlay, primitives, hud]
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
Accepted.
|
||||
|
||||
## Contexto
|
||||
|
||||
`DEC-0014` and `DEC-0015` established `FrameComposer` as the canonical orchestration path for game-frame composition and exposed that orchestration publicly through `composer.*`.
|
||||
|
||||
That migration left `gfx.draw_text(...)` and other `gfx` primitives with their historical immediate-write behavior against the working framebuffer. Once the runtime moved to end-of-frame composition through `FrameComposer.render_frame()`, those immediate writes became unstable: scene-backed frame composition can rebuild the backbuffer after primitive calls have already touched it.
|
||||
|
||||
The resulting conflict is not about whether primitives should remain available. It is about their semantic place in the pipeline. The accepted direction of this thread is that `gfx` primitives are not part of the canonical game composition model. They are primarily for debug, quick visual instrumentation, and rapid artifacts, and they must remain agnostic to scene/tile/sprite/HUD composition.
|
||||
|
||||
Relevant performance context migrated from `AGD-0010` also remains in force:
|
||||
|
||||
- the renderer continues to be a destructive software framebuffer model, not a retained scene graph or GPU-style renderer;
|
||||
- internal primitive fast paths remain desirable;
|
||||
- memory growth must remain constrained for the handheld target;
|
||||
- optimization of primitive execution must not alter observable semantics.
|
||||
|
||||
## Decisao
|
||||
|
||||
`gfx.*` primitives and text SHALL move to a deferred final overlay model that lives outside `FrameComposer`.
|
||||
|
||||
Normatively:
|
||||
|
||||
- `FrameComposer` SHALL remain responsible only for canonical game-frame composition:
|
||||
- scene composition;
|
||||
- sprite composition;
|
||||
- canonical HUD composition when such a HUD stage exists.
|
||||
- `FrameComposer` MUST NOT become the owner of debug/primitive overlay state.
|
||||
- Public `gfx.*` primitives, including `gfx.draw_text(...)`, SHALL belong to a V1 `gfx` overlay/debug family.
|
||||
- That overlay/debug family SHALL be deferred rather than written immediately as the stable operational contract.
|
||||
- The deferred overlay/debug stage SHALL be drained after `hud_fade`.
|
||||
- The deferred overlay/debug stage SHALL be above scene, sprites, and canonical HUD in final visual order.
|
||||
- The no-scene path MUST preserve the same final overlay/debug semantics.
|
||||
- `gfx.*` primitives MUST remain semantically separate from scene/tile/sprite/HUD composition.
|
||||
- The implementation MUST preserve operational separation sufficient to prevent the canonical game pipeline from depending on transient primitive/debug state.
|
||||
|
||||
## Rationale
|
||||
|
||||
This decision keeps the architectural boundary clean.
|
||||
|
||||
`FrameComposer` exists to own the canonical game frame. Debug primitives do not belong to that contract. Pulling them into `FrameComposer` would make the orchestration service responsible for a second semantic domain with different goals:
|
||||
|
||||
- game composition must be deterministic and canonical;
|
||||
- primitive/text overlay must be opportunistic, screen-space, and pipeline-agnostic.
|
||||
|
||||
Keeping overlay/debug outside `FrameComposer` also aligns with the stated product intent: these primitives are useful helpers, but they are not meant to become a second composition language for games.
|
||||
|
||||
Draining them after `hud_fade` preserves the user-visible requirement that debug/overlay content stay truly on top and legible. This is more faithful to the accepted intent than treating primitives as part of HUD or world composition.
|
||||
|
||||
Finally, separating semantic ownership still leaves room for implementation reuse. Raster backends, span paths, and buffer-writing helpers may still be shared internally, provided the public operational model remains separate.
|
||||
|
||||
## Invariantes / Contrato
|
||||
|
||||
### 1. Ownership Boundary
|
||||
|
||||
- `FrameComposer` MUST own only canonical game-frame composition.
|
||||
- Primitive/debug overlay state MUST live outside `FrameComposer`.
|
||||
- The canonical game pipeline MUST NOT depend on primitive/debug overlay state for correctness.
|
||||
|
||||
### 2. Overlay Semantics
|
||||
|
||||
- `gfx.draw_text(...)` and sibling `gfx` primitives SHALL be treated as deferred final overlay/debug operations.
|
||||
- Immediate direct writes to `back` MUST NOT remain the stable operational contract for these primitives.
|
||||
- Final overlay/debug output MUST appear after:
|
||||
- scene composition;
|
||||
- sprite composition;
|
||||
- canonical HUD composition, if present;
|
||||
- `scene_fade`;
|
||||
- `hud_fade`.
|
||||
|
||||
### 3. Separation from Game Composition
|
||||
|
||||
- Primitive/debug overlay MUST NOT be reinterpreted as scene content.
|
||||
- Primitive/debug overlay MUST NOT be reinterpreted as sprite content.
|
||||
- Primitive/debug overlay MUST NOT be the vehicle for canonical HUD composition.
|
||||
- The public `gfx.*` primitive surface SHALL remain pipeline-agnostic relative to `composer.*`.
|
||||
|
||||
### 4. Consistency Across Frame Paths
|
||||
|
||||
- The scene-bound path and no-scene path MUST expose the same final overlay/debug behavior.
|
||||
- Users MUST NOT need to know whether a scene is bound for `gfx.*` primitives to appear as final overlay/debug content.
|
||||
|
||||
### 5. Internal Optimization Contract
|
||||
|
||||
- Internal fast paths for lines, spans, fills, clears, or similar primitive operations MAY be introduced.
|
||||
- Such fast paths MUST preserve the observable deferred overlay/debug semantics.
|
||||
- This decision DOES NOT require fine-grained dirtying or per-primitive-class invalidation in the first migration.
|
||||
|
||||
## Impactos
|
||||
|
||||
### Runtime / Drivers
|
||||
|
||||
- The runtime frame-end sequence must gain a distinct overlay/debug drain stage outside `FrameComposer`.
|
||||
- `gfx.draw_text(...)` and peer primitives can no longer rely on stable immediate framebuffer writes once this migration lands.
|
||||
|
||||
### GFX Backend
|
||||
|
||||
- `Gfx` will need an explicit deferred overlay/debug command path or equivalent subsystem boundary.
|
||||
- Shared raster helpers remain allowed, but the overlay/debug phase must stay semantically distinct from scene/sprite/HUD composition.
|
||||
|
||||
### FrameComposer
|
||||
|
||||
- `FrameComposer` must remain free of primitive/debug overlay ownership.
|
||||
- Any future HUD integration must not collapse that boundary.
|
||||
|
||||
### Spec / Docs
|
||||
|
||||
- The canonical graphics/runtime spec must describe `gfx.*` primitives as deferred final overlay/debug operations rather than stable immediate backbuffer writes.
|
||||
- Documentation that describes frame ordering must show overlay/debug after `hud_fade`.
|
||||
|
||||
### Performance Follow-up
|
||||
|
||||
- `AGD-0010` remains the home for broader renderer performance work, dirtying strategy, and low-level primitive optimization policy.
|
||||
- Primitive optimization carried out under that thread must respect the normative separation established here.
|
||||
|
||||
## Referencias
|
||||
|
||||
- [AGD-0028-deferred-overlay-and-primitive-composition.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/discussion/workflow/agendas/AGD-0028-deferred-overlay-and-primitive-composition.md)
|
||||
- [AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/discussion/workflow/agendas/AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md)
|
||||
- [DEC-0014-frame-composer-render-integration.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/discussion/workflow/decisions/DEC-0014-frame-composer-render-integration.md)
|
||||
- [DEC-0015-frame-composer-public-syscall-surface.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/discussion/workflow/decisions/DEC-0015-frame-composer-public-syscall-surface.md)
|
||||
|
||||
## Propagacao Necessaria
|
||||
|
||||
- A new implementation plan MUST be created before code changes.
|
||||
- That plan MUST cover:
|
||||
- deferred overlay/debug ownership outside `FrameComposer`;
|
||||
- runtime frame-end ordering changes;
|
||||
- no-scene path parity;
|
||||
- spec/documentation updates for `gfx.*` primitive semantics.
|
||||
- The implementation plan MUST NOT reopen the ownership boundary accepted here.
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-04-18: Initial accepted decision from `AGD-0028`.
|
||||
- 2026-04-18: Linked implementation plan family `PLN-0026` through `PLN-0029`.
|
||||
@@ -0,0 +1,93 @@
|
||||
---
|
||||
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`.
|
||||
@@ -0,0 +1,104 @@
|
||||
---
|
||||
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.*`.
|
||||
+106
@@ -0,0 +1,106 @@
|
||||
---
|
||||
id: PLN-0028
|
||||
ticket: deferred-overlay-and-primitive-composition
|
||||
title: Plan - Runtime Frame-End Overlay Integration and Parity
|
||||
status: accepted
|
||||
created: 2026-04-18
|
||||
completed:
|
||||
tags: [runtime, overlay, frame-composer, no-scene, regression, stress]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Integrate deferred overlay/debug draining into the runtime frame-end sequence so scene-bound and no-scene frames both present the same final `gfx.*` primitive behavior after `hud_fade`.
|
||||
|
||||
## Background
|
||||
|
||||
After `PLN-0027`, the overlay/debug subsystem will exist but still needs to be drained in the correct place relative to `FrameComposer.render_frame()`, fades, and present/present-adjacent behavior. This plan closes the observable runtime semantics required by `DEC-0016`.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- runtime frame-end ordering changes
|
||||
- scene-bound and no-scene parity
|
||||
- regression coverage for overlay visibility above the canonical game frame
|
||||
- stress-cartridge adjustments if needed to prove text/primitives now survive frame composition
|
||||
|
||||
### Excluded
|
||||
- broad renderer optimization work
|
||||
- final repository-wide CI
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Insert overlay/debug drain into the frame-end path
|
||||
|
||||
**What:**
|
||||
Drain deferred overlay/debug after canonical game composition is complete.
|
||||
|
||||
**How:**
|
||||
- Update the runtime frame-end path so overlay/debug drain occurs after:
|
||||
- `FrameComposer.render_frame()`
|
||||
- `scene_fade`
|
||||
- `hud_fade`
|
||||
- Ensure the same ordering is respected in the no-scene path.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs`
|
||||
- `crates/console/prometeu-drivers/src/hardware.rs`
|
||||
- `crates/console/prometeu-drivers/src/gfx.rs`
|
||||
- any bridge traits needed by the runtime/hardware path
|
||||
|
||||
### Step 2 - Add runtime and driver regressions for final visual ordering
|
||||
|
||||
**What:**
|
||||
Lock the new visible behavior.
|
||||
|
||||
**How:**
|
||||
- Add tests proving `gfx.draw_text(...)` remains visible after scene-backed frame composition.
|
||||
- Add tests proving the same behavior with no scene bound.
|
||||
- Add tests proving overlay/debug sits above the canonical game frame rather than being erased by it.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-system/src/virtual_machine_runtime/tests.rs`
|
||||
- driver-level render tests where helpful
|
||||
|
||||
### Step 3 - Update stress/integration fixtures if needed
|
||||
|
||||
**What:**
|
||||
Restore or improve stress scenarios that rely on visible text/primitives.
|
||||
|
||||
**How:**
|
||||
- Update `pbxgen-stress` or related stress fixtures so text/primitives are once again a valid visible overlay signal.
|
||||
- Keep the stress focused on the new model rather than reintroducing obsolete immediate-write assumptions.
|
||||
|
||||
**File(s):**
|
||||
- `crates/tools/pbxgen-stress/src/lib.rs`
|
||||
- `test-cartridges/stress-console/*`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- local ordering tests where runtime integration depends on helper sequencing
|
||||
|
||||
### Integration Tests
|
||||
- runtime tests for scene-bound overlay/debug visibility
|
||||
- runtime tests for no-scene parity
|
||||
- stress/tooling validation that text or primitives are visible again as final overlay/debug
|
||||
|
||||
### Manual Verification
|
||||
- run the stress path and visually confirm overlay/debug survives on top of scene/sprites after frame composition
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] The runtime drains deferred overlay/debug after canonical game composition and after `hud_fade`.
|
||||
- [ ] Scene-bound and no-scene paths expose the same overlay/debug semantics.
|
||||
- [ ] Regression tests prove `draw_text(...)` is no longer erased by scene-backed frame composition.
|
||||
- [ ] Stress/integration fixtures reflect the new final-overlay semantics where applicable.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: `DEC-0016`
|
||||
- Depends on `PLN-0027`
|
||||
|
||||
## Risks
|
||||
|
||||
- If fades are still applied after overlay/debug drain, the visible contract will contradict `DEC-0016`.
|
||||
- Incomplete parity between scene-bound and no-scene paths would leave runtime behavior mode-dependent.
|
||||
@@ -0,0 +1,82 @@
|
||||
---
|
||||
id: PLN-0029
|
||||
ticket: deferred-overlay-and-primitive-composition
|
||||
title: Plan - Final Overlay CI Validation and Polish
|
||||
status: accepted
|
||||
created: 2026-04-18
|
||||
completed:
|
||||
tags: [ci, overlay, runtime, gfx, validation]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Run the final repository validation path for the deferred overlay/debug migration and perform the last compatibility, formatting, lint, and regression fixes required to close the thread cleanly.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0016` changes visible runtime semantics and touches both specs and code paths around frame composition. A dedicated final-validation plan is needed so the implementation family can close on a clean CI signal rather than leaving integration fallout for later.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- full-tree formatting, lint, and test validation
|
||||
- stress-path smoke validation after overlay integration
|
||||
- final cleanup fixes required to satisfy CI
|
||||
|
||||
### Excluded
|
||||
- new feature work outside the accepted overlay/debug migration
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Run focused validation before full CI
|
||||
|
||||
**What:**
|
||||
Catch local fallout in the touched areas before the full repository pass.
|
||||
|
||||
**How:**
|
||||
- Run targeted tests for drivers, runtime, and `pbxgen-stress`.
|
||||
- Inspect touched files for stale immediate-write assumptions or missed contract updates.
|
||||
|
||||
**File(s):**
|
||||
- touched files from `PLN-0026` through `PLN-0028`
|
||||
|
||||
### Step 2 - Run final repository CI
|
||||
|
||||
**What:**
|
||||
Validate the migration end to end.
|
||||
|
||||
**How:**
|
||||
- Run the repository validation path, including `make ci`.
|
||||
- Fix any final formatting, lint, test, or generated-fixture fallout caused by the overlay/debug migration.
|
||||
- Do not widen scope beyond the accepted thread.
|
||||
|
||||
**File(s):**
|
||||
- repository-wide
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- all relevant crate unit tests pass after the migration
|
||||
|
||||
### Integration Tests
|
||||
- runtime and stress/integration tests pass after the migration
|
||||
- `make ci` passes
|
||||
|
||||
### Manual Verification
|
||||
- inspect the tree for residual direct-write assumptions or incomplete overlay propagation
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Targeted validation passes for the touched drivers/runtime/stress areas.
|
||||
- [ ] `make ci` passes after the deferred overlay/debug migration family lands.
|
||||
- [ ] No residual contract mismatch remains between spec text and code behavior in the touched thread.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: `DEC-0016`
|
||||
- Depends on `PLN-0026`, `PLN-0027`, and `PLN-0028`
|
||||
|
||||
## Risks
|
||||
|
||||
- Final CI may surface unrelated renderer assumptions that still expect immediate-write semantics.
|
||||
- Generated cartridge fixtures may drift if regeneration is forgotten during earlier plans.
|
||||
Reference in New Issue
Block a user