237 lines
11 KiB
Markdown
237 lines
11 KiB
Markdown
---
|
|
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`.
|