implements PLN-0073 render contract specs

This commit is contained in:
2026-05-25 11:35:49 +01:00
parent 2b69be0f11
commit 96a23e5419
5 changed files with 165 additions and 149 deletions
+67 -11
View File
@@ -220,29 +220,78 @@ For `asset.load`:
- JSON-on-the-wire bank inspection payloads are not valid public ABI;
- `bank.info` returns stack values, not textual structured payloads.
### GFX surface (`gfx`, v1)
### Render surfaces (`composer`, `gfx2d`, `gfxui`, v1)
The public GFX ABI uses format-neutral operation names. API and syscall names
MUST NOT encode RGB565 or any other pixel format suffix.
`DEC-0030` splits logical render production from render implementation. Public
render syscalls mutate app-mode-specific domain buffers. They do not directly
publish a framebuffer and do not call host presentation APIs.
The canonical flow is:
```text
domain buffers during logical frame
-> RenderManager closes buffers
-> RenderSubmission snapshot
-> render surface / implementation consumes submission
-> RGBA8888 surface publication
```
`RenderSubmission` is a typed closed snapshot containing `frame_id`, `app_mode`,
and exactly one packet: `Game2DFramePacket` for `AppMode::Game` or
`ShellUiFramePacket` for `AppMode::Shell`. Producers may mutate domain buffers
before closure only. Once `RenderManager` closes a submission, producers MUST
NOT mutate it. Backpressure is latest-complete-submission-wins; the runtime
MUST NOT expose an unbounded submission queue as part of the ABI.
Render API and syscall names MUST NOT encode RGB565 or any other pixel format
suffix.
#### Game 2D primitive surface (`gfx2d`, v1)
The `gfx2d` module is a Game profile primitive surface. It is limited to Game
2D primitive commands and does not own scene, camera, sprites, HUD, or frame
orchestration.
Canonical operations in v1 include:
- `gfx.clear(color) -> void`
- `gfx.fill_rect(x, y, w, h, color) -> void`
- `gfx.draw_line(x0, y0, x1, y1, color) -> void`
- `gfx.draw_circle(x, y, radius, color) -> void`
- `gfx.draw_disc(x, y, radius, color) -> void`
- `gfx.draw_square(x, y, size, color) -> void`
- `gfx.draw_text(x, y, text, color) -> void`
- `gfx2d.clear(color) -> void`
- `gfx2d.fill_rect(x, y, w, h, color) -> void`
- `gfx2d.draw_line(x0, y0, x1, y1, color) -> void`
- `gfx2d.draw_circle(x, y, radius, color) -> void`
- `gfx2d.draw_disc(x, y, radius, color) -> void`
- `gfx2d.draw_square(x, y, size, color) -> void`
- `gfx2d.draw_text(x, y, text, color) -> void`
#### Shell UI primitive surface (`gfxui`, v1)
The `gfxui` module is a Shell profile primitive surface. It contains Shell UI
primitive commands only. Widget and layout policy belongs in Shell/UI code or
stdlib code, not in the host/render-surface implementation.
Canonical operations in v1 include primitive shapes equivalent to the subset
needed by Shell UI:
- `gfxui.clear(color) -> void`
- `gfxui.fill_rect(x, y, w, h, color) -> void`
- `gfxui.draw_line(x0, y0, x1, y1, color) -> void`
- `gfxui.draw_circle(x, y, radius, color) -> void`
- `gfxui.draw_disc(x, y, radius, color) -> void`
- `gfxui.draw_square(x, y, size, color) -> void`
- `gfxui.draw_text(x, y, text, color) -> void`
Rules:
- `color` arguments are packed RGBA8888 values using RGBA channel order.
- RGB565 raw values are not a public ABI contract.
- `Gfx*565` syscall names and `gfx.*_565` canonical identities are not valid
- `Gfx*565` syscall names and `gfx*.*_565` canonical identities are not valid
current ABI.
- The runtime framebuffer exposed across the host boundary is RGBA8888, not
`u16` RGB565.
- The old primitive `gfx.*` ABI is not the canonical render domain. PBS stdlibs
may expose ergonomic high-level names, but generated host bindings must map
to `gfx2d.*` in Game mode or `gfxui.*` in Shell mode.
- Render packets and public render syscalls MUST NOT expose fade fields or fade
controls.
### Composition surface (`composer`, v1)
@@ -251,6 +300,11 @@ The canonical frame-orchestration public ABI uses module `composer`.
The `composer` module is a game profile surface. It is not inherited by
`System` profile apps as their public UI/composition API.
`composer` owns Game 2D high-level frame composition: scene binding, camera,
sprites, HUD, and Game 2D frame orchestration. It closes into a
`Game2DFramePacket` through `RenderManager`; it does not publish or present a
framebuffer directly.
Canonical operations in v1 are:
- `composer.bind_scene(bank_id) -> (status)`
@@ -264,6 +318,8 @@ For mutating composer operations:
- `bind_scene`, `unbind_scene`, and `emit_sprite` are status-returning;
- `set_camera` remains `void` in v1;
- no caller-provided sprite index or `active` flag is part of the canonical contract.
- no fade level, fade color, or transition control is part of the canonical
composer ABI.
Fatal boundary clarification for `bind_scene`: