Logical Render Pipelines and Command Packets
This commit is contained in:
@@ -0,0 +1,236 @@
|
||||
---
|
||||
id: DEC-0030
|
||||
ticket: render-frame-packet-boundary
|
||||
title: Logical Render Pipeline Command Boundary
|
||||
status: accepted
|
||||
created: 2026-05-25
|
||||
ref_agenda: AGD-0038
|
||||
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
||||
---
|
||||
|
||||
# Decision - Logical Render Pipeline Command Boundary
|
||||
|
||||
## Status
|
||||
|
||||
Accepted.
|
||||
|
||||
## Contexto
|
||||
|
||||
Prometeu ja concluiu a migracao do framebuffer/runtime para RGBA8888. O proximo passo do renderer nao e introduzir GPU, 3D, multiplos backends, troca dinamica complexa de pipeline ou render thread. O objetivo imediato e criar uma fronteira arquitetural limpa entre:
|
||||
|
||||
- producao logica de comandos de render;
|
||||
- fechamento/publicacao de frame;
|
||||
- coordenacao entre `AppMode::Game` e `AppMode::Shell`;
|
||||
- rasterizacao/publicacao em uma superficie real.
|
||||
|
||||
O estado atual ainda acopla codigo logico ao `Gfx`/framebuffer. `FrameComposer` ja centraliza parte da orquestracao do frame de jogo, mas ainda desenha por `GfxBridge`. Prometeu Hub, shell/system UI, splash/crash e primitivas `gfx.*` tambem acessam desenho imperativo direto. Essa decisao normatiza a nova fronteira de comandos e o papel de cada dominio.
|
||||
|
||||
## Decisao
|
||||
|
||||
Prometeu MUST separar render pipeline logico de render implementation.
|
||||
|
||||
O runtime SHALL introduce a `RenderManager` as the runtime-level render coordination abstraction. `RenderManager` MUST NOT be a host-specific renderer and MUST NOT contain desktop presentation details. Host/render-surface implementations SHALL adapt `RenderManager` submissions to the local hardware or host surface.
|
||||
|
||||
The canonical render flow SHALL be:
|
||||
|
||||
```text
|
||||
domain buffers during logical frame
|
||||
-> RenderManager closes buffers
|
||||
-> RenderSubmission snapshot
|
||||
-> render surface / implementation consumes submission
|
||||
-> RGBA8888 surface publication
|
||||
```
|
||||
|
||||
The v1 logical render domains are:
|
||||
|
||||
- `composer.*` for Game 2D high-level frame composition: scene, camera, sprites, HUD, and Game 2D frame orchestration.
|
||||
- `gfx2d.*` for Game 2D primitives only.
|
||||
- `gfxui.*` for Shell UI primitives.
|
||||
|
||||
The v1 app modes are:
|
||||
|
||||
- `AppMode::Game`, which SHALL route to Game 2D submissions.
|
||||
- `AppMode::Shell`, which SHALL route to Shell UI submissions.
|
||||
|
||||
No `AppMode::System` rename is accepted by this decision.
|
||||
|
||||
`RenderSubmission` MUST be coherent with `AppMode`. The initial submission model SHOULD be a typed envelope rather than a generic universal command list:
|
||||
|
||||
```text
|
||||
RenderSubmission
|
||||
- frame_id
|
||||
- app_mode
|
||||
- packet:
|
||||
- Game2D(Game2DFramePacket)
|
||||
- ShellUi(UiFramePacket)
|
||||
```
|
||||
|
||||
The exact Rust layout may evolve during planning, but the contract MUST preserve typed per-pipeline command sets.
|
||||
|
||||
## Rationale
|
||||
|
||||
Typed command sets preserve domain meaning. Game 2D and Shell UI have different responsibilities and should not be forced into a weak universal command list. A future 3D or custom 2D pipeline should add its own packet rather than reinterpret a 2D/UI command model.
|
||||
|
||||
`RenderManager` is required because mode transitions do not belong completely to either Shell UI or Game 2D. Shell can render an exit transition before launching a game, but once Game mode owns the frame, Shell UI is no longer available to render the entry transition. Therefore transition coordination, surface maintenance, active render capabilities, and frame publication need a manager above individual pipelines.
|
||||
|
||||
Command buffers and submissions must be distinct. Domain buffers are mutable while the logical frame is being built. A `RenderSubmission` is a closed snapshot. This makes future VM/render parallelism possible without requiring a render thread in v1.
|
||||
|
||||
The current fade model is rejected. Fade was a hardware-direction idea that no longer belongs in the Prometeu render contract after RGBA8888. Fade MUST NOT remain as a packet field, syscall, or implementation habit. Future visual transitions belong to `RenderManager`.
|
||||
|
||||
## Invariantes / Contrato
|
||||
|
||||
### Pipeline and Implementation Boundary
|
||||
|
||||
- Pipelines MUST produce logical commands or state.
|
||||
- Render implementations MUST consume submissions and write/publish to a surface.
|
||||
- Pipeline code MUST NOT require direct mutable access to the framebuffer.
|
||||
- Pipeline code MUST NOT depend on host-specific presentation details.
|
||||
|
||||
### RenderManager
|
||||
|
||||
- `RenderManager` MUST coordinate active `AppMode`, submission closure, mode transitions, capabilities, and publication policy.
|
||||
- `RenderManager` MUST be a runtime abstraction, not a host renderer.
|
||||
- Host/render-surface implementations MUST be separate adapters.
|
||||
- `RenderManager` MUST own transition coordination between Game and Shell.
|
||||
- `RenderManager` MUST own the policy for surface publication/present through the render surface.
|
||||
|
||||
### Command Buffers and Submissions
|
||||
|
||||
- Each render domain/pipeline MUST own its own mutable command/state buffer during a logical frame.
|
||||
- `RenderManager` MUST close the active buffers into a `RenderSubmission` at frame boundary.
|
||||
- Once closed, `RenderSubmission` MUST be treated as immutable by producers.
|
||||
- `RenderSubmission` MUST include `frame_id` and `app_mode`.
|
||||
- Future parallel render MUST be supported by the contract: consuming a submission MUST NOT require `&mut Hardware`, `&mut Gfx`, or live mutable VM state.
|
||||
- Backpressure policy MUST be latest-complete-submission-wins. The system MUST NOT accumulate an unbounded frame queue.
|
||||
|
||||
### AppMode Routing
|
||||
|
||||
- `AppMode::Game` SHALL expose and route Game render domains.
|
||||
- `AppMode::Shell` SHALL expose and route Shell UI render domains.
|
||||
- Renderers/capabilities MAY differ by app mode.
|
||||
- PBS stdlibs MAY expose similar high-level names, including `gfx`, but they MUST map to mode-appropriate ABI domains.
|
||||
|
||||
### ABI Domains
|
||||
|
||||
- `composer.*` MUST remain the high-level Game 2D composition domain.
|
||||
- `composer.*` MUST own scene, camera, sprites, HUD, and Game 2D frame orchestration.
|
||||
- `gfx2d.*` MUST contain Game 2D primitives only.
|
||||
- `gfx2d.*` MUST NOT own scene, camera, sprites, HUD, or frame orchestration.
|
||||
- `gfxui.*` MUST contain Shell UI primitives.
|
||||
- `gfxui.*` MUST NOT contain widget/layout policy. Widget/layout belongs in Shell/UI code or stdlib, not the host implementation.
|
||||
- Capabilities MUST be separated for `composer`, `gfx2d`, and `gfxui`.
|
||||
|
||||
### Game 2D Composition
|
||||
|
||||
- Game 2D scene and sprites MUST compose by integer `layer`.
|
||||
- The v1 Game 2D model has four available layers.
|
||||
- Scene and sprite composition MAY interleave by layer, normally as sprite/scene ordering across the four layers.
|
||||
- HUD MUST render above scene/sprite composition.
|
||||
- HUD belongs to `composer` in v1 and remains a minimal, evolvable contract.
|
||||
- HUD in this decision means Game HUD only. Shell/system UI is always part of the Shell UI pipeline.
|
||||
- Game 2D publish happens after scene/sprite/HUD composition.
|
||||
|
||||
### Shell UI Composition
|
||||
|
||||
- Shell UI MUST use its own `gfxui.*` primitive command set.
|
||||
- Shell UI commands MAY reduce to the same local drawing directives as Game 2D primitives inside a host/render-surface implementation.
|
||||
- That reduction MUST remain an implementation detail and MUST NOT collapse the ABI domains.
|
||||
|
||||
### Fade and Transitions
|
||||
|
||||
- Fade MUST be removed completely from canonical pipeline contracts.
|
||||
- Fade MUST NOT appear as a `Game2DFramePacket`, `UiFramePacket`, `RenderSubmission`, `composer`, `gfx2d`, or `gfxui` field or syscall.
|
||||
- Future visual transitions MUST be coordinated by `RenderManager`.
|
||||
|
||||
### Debug Overlay
|
||||
|
||||
- The current host-owned debug overlay is not part of the new render architecture.
|
||||
- It MAY be removed during execution.
|
||||
- A future console/debug UI MUST be discussed as a separate product/domain, not preserved as inherited host overlay behavior.
|
||||
|
||||
## Impactos
|
||||
|
||||
### Spec
|
||||
|
||||
Specs must define the logical render pipeline model, `RenderManager`, `RenderSubmission`, app-mode routing, domain buffers, and publication boundary in English.
|
||||
|
||||
The public syscall/ABI specs must replace the old primitive `gfx.*` surface with mode-appropriate `gfx2d.*` and `gfxui.*` primitive domains while preserving `composer.*` as the high-level Game 2D composition domain.
|
||||
|
||||
### Runtime
|
||||
|
||||
Runtime frame execution must stop treating `Gfx`/framebuffer as the direct target of logical render calls. It must accumulate domain state/commands and let `RenderManager` close submissions.
|
||||
|
||||
`VirtualMachineRuntime` and firmware flow must route frame closure through `RenderManager`.
|
||||
|
||||
### HAL
|
||||
|
||||
HAL must expose distinct contracts for:
|
||||
|
||||
- `composer`;
|
||||
- `gfx2d`;
|
||||
- `gfxui`;
|
||||
- render submissions;
|
||||
- render manager/surface boundary.
|
||||
|
||||
Capability flags must be split accordingly.
|
||||
|
||||
### Host
|
||||
|
||||
The desktop host remains a concrete render-surface implementation. It may continue publishing RGBA8888 to `pixels`, but that behavior must sit below the render-surface adapter, not inside logical pipeline APIs.
|
||||
|
||||
Host debug overlay may be removed.
|
||||
|
||||
### Firmware / Shell
|
||||
|
||||
Shell UI must migrate away from direct `gfx_mut()` drawing toward `gfxui.*`/Shell UI command buffers.
|
||||
|
||||
Game mode must migrate toward `composer.*` plus `gfx2d.*` buffers closed by `RenderManager`.
|
||||
|
||||
### PBS / Stdlibs
|
||||
|
||||
PBS Game and Shell stdlibs may present similar high-level APIs to authors. They must map to different ABI domains according to `AppMode`.
|
||||
|
||||
Game stdlib should map scene/camera/sprites/HUD to `composer.*` and primitive Game drawing to `gfx2d.*`.
|
||||
|
||||
Shell stdlib should map UI primitives to `gfxui.*`.
|
||||
|
||||
## Alternativas Descartadas
|
||||
|
||||
### Universal RenderCommand
|
||||
|
||||
A single `RenderCommand` display list for Game, Shell, and future pipelines is rejected. It collapses domain meaning and would likely force future 3D or custom pipelines into a 2D/UI-shaped contract.
|
||||
|
||||
### Trait-Only RenderPipeline
|
||||
|
||||
A trait that calls `render(&mut Surface)` without a closed packet is rejected as the primary boundary. It preserves immediate rendering and does not prepare VM/render parallelism.
|
||||
|
||||
### Backend Registry Now
|
||||
|
||||
A full backend registry, GPU/CPU backend abstraction, dynamic pipeline switching, render thread, or 3D implementation is out of scope. Those may come later after the command boundary is stable.
|
||||
|
||||
### Moving Composer into Gfx2D
|
||||
|
||||
Moving scene, camera, sprites, HUD, or frame orchestration into `gfx2d.*` is rejected. `gfx2d.*` is primitives only.
|
||||
|
||||
## Referencias
|
||||
|
||||
- Agenda: `AGD-0038`
|
||||
- Related dependency: `DSC-0011` dirty regions must wait until this boundary exists.
|
||||
- Related prior lessons: frame composition belongs above the render backend; public ABI must follow canonical service boundaries; RGBA8888 is the canonical framebuffer contract.
|
||||
|
||||
## Propagacao Necessaria
|
||||
|
||||
- Create a plan before any spec or code changes.
|
||||
- Update canonical specs in English.
|
||||
- Update HAL syscall registry, capability definitions, and resolver tests.
|
||||
- Update PBS/stdlib syscall declarations for Game and Shell.
|
||||
- Update runtime dispatch so render syscalls mutate domain buffers instead of drawing directly.
|
||||
- Introduce `RenderManager`, domain buffers, `RenderSubmission`, and render-surface implementation boundary.
|
||||
- Migrate Game 2D first, then Shell UI, unless the plan proves both can be safely migrated together.
|
||||
- Remove fade surfaces from render contracts.
|
||||
- Remove or explicitly retire the host debug overlay.
|
||||
- Add packet/submission tests, app-mode capability tests, and pixel-equivalence tests for unchanged visible behavior.
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-05-25: Initial decision draft from `AGD-0038`.
|
||||
Reference in New Issue
Block a user