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
+90 -130
View File
@@ -9,7 +9,29 @@ Didactic companion: [`../learn/mental-model-gfx.md`](../runtime/learn/mental-mod
The **GFX** peripheral is responsible for generating images in PROMETEU.
It is an explicit 2D graphics device based on:
`DEC-0030` defines the current logical render boundary. PROMETEU render
production is split from render implementation:
```text
domain buffers during logical frame
-> RenderManager closes buffers
-> RenderSubmission snapshot
-> render surface / implementation consumes submission
-> RGBA8888 surface publication
```
The GFX peripheral remains the classic local raster implementation for
PROMETEU's 2D output. Logical render APIs do not target `Gfx` or the
framebuffer directly.
`RenderSubmission` is the closed snapshot passed across the render boundary. It
MUST contain a frame id, the active app mode, and one typed packet:
`Game2DFramePacket` for `AppMode::Game` or `ShellUiFramePacket` for
`AppMode::Shell`. Once closed, producers MUST treat the submission as
immutable. The runtime backpressure policy is latest-complete-submission-wins;
it MUST NOT accumulate an unbounded frame queue.
The current 2D graphics model is based on:
- framebuffer
- tilemaps
@@ -48,19 +70,19 @@ palette, host presentation, or compatibility contract.
## 3. Double Buffering
The GFX maintains two buffers:
The render surface implementation maintains the concrete buffers needed to
publish a frame. The classic software implementation uses:
- **Back Buffer** — where the frame is built
- **Front Buffer** — where the frame is displayed
Per-frame flow:
1. The system prepares the logical frame
2. Canonical game composition is rendered into the back buffer
3. Deferred final overlay/debug primitives are drained on top of the completed game frame
4. Calls `present()`
5. Buffers are swapped
6. The host displays the front buffer
1. Game or Shell code mutates mode-specific domain buffers during the logical frame.
2. `RenderManager` closes the active buffers into an immutable `RenderSubmission`.
3. The render surface implementation consumes the submission and rasterizes to its back buffer.
4. The render surface publishes the completed RGBA8888 surface.
5. The host displays the published surface.
This guarantees:
@@ -192,14 +214,20 @@ Access:
---
## 10. Canonical Game Projection to the Back Buffer
## 10. Canonical Game Projection
For each frame:
Game mode uses a typed Game 2D submission. `composer.*` owns high-level Game 2D
frame composition: scene binding, camera, sprites, HUD, and frame orchestration.
`gfx2d.*` owns Game 2D primitives only. Both domains are mutable while the
logical frame is being produced and are closed by `RenderManager` into a
`Game2DFramePacket`.
For each Game 2D packet:
1. For each Tile Layer, in order:
- Rasterize visible tiles from the cache
- Apply scroll, flip, and transparency
- Write to the back buffer
- Write to the render surface's working buffer
2. Draw sprites:
- With priority between layers
@@ -207,9 +235,11 @@ For each frame:
3. Draw HUD layer last
This section describes only the canonical game composition path.
4. Draw buffered `gfx2d.*` primitives according to the Game 2D packet contract.
`gfx.*` primitives such as `draw_text`, `draw_line`, and `draw_disc` are not part of this canonical game projection order. In v1 they belong to a deferred final overlay/debug stage that is drained after canonical game composition is complete.
This section describes only the Game 2D packet rendering path. Shell/system UI
uses `gfxui.*` and `ShellUiFramePacket`; it is never part of Game HUD or
`composer.*`.
---
@@ -227,15 +257,15 @@ Base order:
4. Tile Layer 3
5. Sprites (by priority between layers)
6. HUD Layer
7. Scene Fade
8. HUD Fade
9. Deferred `gfx.*` overlay/debug primitives
7. Buffered `gfx2d.*` Game primitives
Normative boundary:
- Items 1 through 8 belong to canonical game-frame composition.
- Item 9 is a separate overlay/debug stage.
- Deferred `gfx.*` primitives MUST NOT be interpreted as scene, sprite, or canonical HUD content.
- Items 1 through 6 belong to `composer.*` Game-frame composition.
- Item 7 belongs to `gfx2d.*`.
- `gfx2d.*` primitives MUST NOT be interpreted as scene, sprite, camera, HUD,
or frame orchestration.
- Shell/system UI belongs to `gfxui.*` and `ShellUiFramePacket`, not Game HUD.
---
@@ -287,7 +317,8 @@ Everything is:
- Blending occurs during drawing
- For canonical game composition, the result goes to the back buffer during composition
- For deferred `gfx.*` overlay/debug primitives, the result is applied during the final overlay/debug drain stage
- For `gfx2d.*` and `gfxui.*` primitives, the result is applied when the render
surface consumes the closed packet for the active app mode
- There is no automatic GPU-style post-processing pipeline
---
@@ -301,6 +332,7 @@ By design:
- HDR
- Gamma correction
- RGB565 compatibility framebuffers
- fade fields, fade syscalls, or fade packet members
- multi-format backend selection
- render-thread ownership as part of this contract
@@ -318,104 +350,24 @@ By design:
---
## 17. Special PostFX — Fade (Scene and HUD)
## 17. Transitions and Removed Fade Contract
PROMETEU supports **gradual fade** as a special PostFX, with two independent
controls:
The previous special fade model is not part of the canonical render contract.
Current render packets, syscalls, and ABI domains MUST NOT expose scene fade,
HUD fade, fade levels, fade colors, or equivalent inherited fade state.
- **Scene Fade**: affects the entire scene (Tile Layers 0–3 + Sprites)
- **HUD Fade**: affects only the HUD Layer (always composed last)
In v1, deferred `gfx.*` overlay/debug primitives are drained after both fades and therefore are not themselves part of scene or HUD fade application.
The fade uses a **discrete integer level** (0..31), which in practice produces an
"almost continuous" visual result in Prometeu's `480x270` pixel-art framebuffer.
---
### 17.1 Fade Representation
Each fade is represented by:
- `fade_level: u8` in the range **[0..31]**
- `0` → fully replaced by the fade color
- `31` → fully visible (no fade)
- `fade_color: RGBA8888`
- color the image will be blended into
Registers:
- `SCENE_FADE_LEVEL` (0..31)
- `SCENE_FADE_COLOR` (RGBA8888)
- `HUD_FADE_LEVEL` (0..31)
- `HUD_FADE_COLOR` (RGBA8888)
Common cases:
- Fade-out: `fade_color = BLACK`
- Flash/teleport: `fade_color = WHITE`
- Special effects: any RGBA8888 color
---
### 17.2 Fade Operation (Blending with Arbitrary Color)
For each RGBA8888 pixel `src` and fade color `fc`, the final pixel `dst` is calculated per channel.
1) Extract components:
- `src_r8`, `src_g8`, `src_b8`, `src_a8`
- `fc_r8`, `fc_g8`, `fc_b8`, `fc_a8`
2) Apply integer blending:
```
src_weight = fade_level // 0..31
fc_weight = 31 - fade_level
r8 = (src_r8 * src_weight + fc_r8 * fc_weight) / 31
g8 = (src_g8 * src_weight + fc_g8 * fc_weight) / 31
b8 = (src_b8 * src_weight + fc_b8 * fc_weight) / 31
a8 = (src_a8 * src_weight + fc_a8 * fc_weight) / 31
```
- `src_r8`, `src_g8`, `src_b8`, `src_a8`
- `fc_r8`, `fc_g8`, `fc_b8`, `fc_a8`
3) Repack:
```
dst = pack_rgba8888_rgba(r8, g8, b8, a8)
```
Notes:
- Deterministic operation
- Integers only
- Can be optimized via LUT
---
### 17.3 Order of Application in the Frame
The frame composition follows this order:
1. Rasterize **Tile Layers 0–3** → Back Buffer
2. Rasterize **Sprites** according to priority
3. (Optional) Extra pipeline (Emission/Light/Glow etc.)
4. Apply **Scene Fade** using:
- `SCENE_FADE_LEVEL`
- `SCENE_FADE_COLOR`
5. Rasterize **HUD Layer**
6. Apply **HUD Fade** using:
- `HUD_FADE_LEVEL`
- `HUD_FADE_COLOR`
7. `present()`
Future visual transitions between Shell and Game belong to `RenderManager`.
They are not owned by `composer.*`, `gfx2d.*`, `gfxui.*`, `Game2DFramePacket`,
or `ShellUiFramePacket`.
Rules:
- Scene Fade never affects the HUD
- HUD Fade never affects the scene
- render domain packets MUST NOT contain fade fields;
- public render syscalls MUST NOT expose fade controls;
- render implementations MUST NOT treat fade as an inherited post-processing
habit;
- transition work requires an explicit `RenderManager` contract or a later
decision.
---
@@ -570,8 +522,13 @@ The system can measure:
Graphics-related public ABI in v1 is split between:
- `gfx.*` for direct drawing/backend-oriented operations;
- `composer.*` for frame orchestration operations.
- `composer.*` for Game 2D high-level frame composition;
- `gfx2d.*` for Game 2D primitives only;
- `gfxui.*` for Shell UI primitives only.
`composer.*` and `gfx2d.*` are available to `AppMode::Game`.
`gfxui.*` is available to `AppMode::Shell`. Renderers and capabilities may
differ by app mode.
Only operations with real operational rejection paths return explicit status values.
@@ -585,29 +542,32 @@ Fault boundary:
| Syscall | Return | Policy basis |
| ----------------------- | ------------- | --------------------------------------------------- |
| `gfx.clear` | `void` | no real operational failure path in v1 |
| `gfx.fill_rect` | `void` | no real operational failure path in v1 |
| `gfx.draw_line` | `void` | no real operational failure path in v1 |
| `gfx.draw_circle` | `void` | no real operational failure path in v1 |
| `gfx.draw_disc` | `void` | no real operational failure path in v1 |
| `gfx.draw_square` | `void` | no real operational failure path in v1 |
| `gfx.draw_text` | `void` | no real operational failure path in v1 |
| `gfx2d.clear` | `void` | no real operational failure path in v1 |
| `gfx2d.fill_rect` | `void` | no real operational failure path in v1 |
| `gfx2d.draw_line` | `void` | no real operational failure path in v1 |
| `gfx2d.draw_circle` | `void` | no real operational failure path in v1 |
| `gfx2d.draw_disc` | `void` | no real operational failure path in v1 |
| `gfx2d.draw_square` | `void` | no real operational failure path in v1 |
| `gfx2d.draw_text` | `void` | no real operational failure path in v1 |
| `gfxui.*` primitives | `void` | no real operational failure path in v1 |
| `composer.bind_scene` | `status:int` | status-returning API, but missing scene glyph dependencies are fatal runtime errors |
| `composer.unbind_scene` | `status:int` | explicit orchestration-domain operational result |
| `composer.set_camera` | `void` | no real operational failure path in v1 |
| `composer.emit_sprite` | `status:int` | explicit orchestration-domain operational rejection |
### 19.1.a Deferred overlay/debug semantics for `gfx.*`
### 19.1.a Primitive domain semantics
The public `gfx.*` primitive family remains valid in v1, but its stable operational meaning is:
The primitive domains have stable operational meaning:
- deferred final overlay/debug composition;
- screen-space and pipeline-agnostic relative to `composer.*`;
- outside `FrameComposer`;
- above scene, sprites, and canonical HUD;
- drained after `hud_fade`.
- `gfx2d.*` is Game 2D primitive command buffering;
- `gfx2d.*` is screen-space and primitive-only relative to `composer.*`;
- `gfx2d.*` is outside scene, camera, sprites, HUD, and Game 2D frame orchestration;
- `gfxui.*` is Shell UI primitive command buffering;
- `gfxui.*` does not contain widget or layout policy.
This means callers MUST NOT rely on stable immediate writes to the working back buffer as the public contract for `gfx.draw_text(...)` or sibling primitives.
Callers MUST NOT rely on stable immediate writes to the working back buffer as
the public contract for primitive drawing. Primitive calls mutate domain command
buffers that close into the active typed submission.
### 19.1.b Scene dependency fatal boundary