Housekeeping

This commit is contained in:
2026-06-05 08:06:04 +01:00
parent 261d9561a4
commit 38a3edc0fd
17 changed files with 54 additions and 1614 deletions
@@ -0,0 +1,54 @@
---
id: LSN-0047
ticket: render-frame-packet-boundary
title: Typed Render Submissions Preserve Domain Boundaries
created: 2026-06-04
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
---
# LSN-0047: Typed Render Submissions Preserve Domain Boundaries
## Context
The RGBA8888 migration made the framebuffer format explicit, but the runtime still needed a cleaner boundary between logical frame production and surface publication. The important follow-up was not a GPU backend, a render thread, or a universal display list. It was the separation between domain-owned logical buffers, closed render submissions, and the surface implementation that turns those submissions into pixels.
`DSC-0038` closed that boundary across specs, runtime types, mode routing, PBS declarations, shell migration, host overlay removal, and validation. The resulting model treats rendering as a runtime contract above the final desktop surface rather than as direct mutable access to `Gfx` or a framebuffer.
## Key Decisions
### Logical Render Pipeline Command Boundary
**What:** Prometeu introduced a runtime-level `RenderManager` that closes mode-appropriate domain buffers into immutable `RenderSubmission` snapshots. A submission carries `frame_id`, `app_mode`, and a typed packet such as `Game2DFramePacket` or `UiFramePacket`.
**Why:** Game rendering and shell UI have different domain meanings. Game 2D owns scene, camera, sprites, HUD, and game primitives. Shell UI owns system-facing UI primitives. A weak universal command list would hide those differences and make future pipelines fit an accidental 2D/UI shape.
**Trade-offs:** The typed packet model creates more explicit types and routing work up front. In return, it keeps ABI domains honest, lets each pipeline evolve independently, and gives host/render-surface code a closed snapshot that can later be consumed off the VM hot path.
## Patterns and Algorithms
Keep three concepts separate:
1. Domain buffers are mutable while a logical frame is being built.
2. `RenderSubmission` is the immutable snapshot produced at the frame boundary.
3. Render-surface implementations consume submissions and publish RGBA8888 pixels.
Use `RenderManager` for coordination, not drawing. It owns active app mode, submission closure, transition policy, capabilities, and publication flow. It must not become the desktop renderer, the shell UI implementation, or the game composer.
Prefer typed top-level packets over a universal command list when pipelines carry different semantic contracts. Shared rasterization helpers are acceptable below the submission boundary, but shared implementation machinery must not collapse public ABI domains.
Treat publication as latest-complete-submission-wins. This keeps the v1 model simple while leaving room for VM/render parallelism without introducing an unbounded queue.
## Pitfalls
Do not preserve immediate rendering through trait-shaped abstractions that still require `&mut Gfx`, `&mut Hardware`, or live VM state during rasterization. That keeps the old coupling under a new name.
Do not move `composer` responsibilities into `gfx2d`. `composer` owns high-level Game 2D composition. `gfx2d` owns Game 2D primitives. `gfxui` owns Shell UI primitives. Similar local drawing operations below the surface adapter are implementation details.
Do not keep inherited framebuffer features, such as fade fields or host debug overlays, just because they existed before the boundary. Once the canonical render contract moves to typed submissions, legacy visual behavior either belongs in `RenderManager`, in a proper product UI, or nowhere.
## Takeaways
- Rendering architecture should name the producer boundary before introducing backend variety.
- A closed submission is the useful concurrency primitive, even when v1 consumes it synchronously.
- App mode is part of the render contract because it determines which ABI domains and packets are valid.
- Shared rendering code below the adapter is fine; shared public command shapes across unrelated domains are usually a design leak.