implements PLN-0026
This commit is contained in:
@@ -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`.
|
||||
|
||||
Reference in New Issue
Block a user