implements PLN-0073 render contract specs
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user