implements PLN-0026

This commit is contained in:
2026-04-18 09:51:30 +01:00
parent b0b8bb9028
commit 4f52a65169
4 changed files with 61 additions and 24 deletions
+37 -7
View File
@@ -48,10 +48,12 @@ The GFX maintains two buffers:
Per-frame flow:
1. The system draws to the back buffer
2. Calls `present()`
3. Buffers are swapped
4. The host displays the front buffer
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
This guarantees:
@@ -183,7 +185,7 @@ Access:
---
## 10. Projection to the Back Buffer
## 10. Canonical Game Projection to the Back Buffer
For each frame:
@@ -198,6 +200,10 @@ For each frame:
3. Draw HUD layer last
This section describes only the canonical game composition path.
`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.
---
## 11. Drawing Order and Priority
@@ -214,6 +220,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
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.
---
@@ -258,8 +273,9 @@ Everything is:
## 14. Where Blend is Applied
- Blending occurs during drawing
- The result goes directly to the back buffer
- There is no automatic post-composition
- 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
- There is no automatic GPU-style post-processing pipeline
---
@@ -296,6 +312,8 @@ controls:
- **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 is implemented without continuous per-pixel alpha and without floats.
It uses a **discrete integer level** (0..31), which in practice produces an
"almost continuous" visual result in 320×180 pixel art.
@@ -566,6 +584,18 @@ Fault boundary:
| `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.*`
The public `gfx.*` primitive family remains valid in v1, but its stable operational meaning is:
- 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`.
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.
### 19.2 `composer.emit_sprite`
`composer.emit_sprite` returns `status:int`.