--- 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`.