implements PLN-0067

This commit is contained in:
2026-05-23 19:15:14 +01:00
parent 4d5818c244
commit 1256d33a72
7 changed files with 103 additions and 52 deletions
+56 -43
View File
@@ -29,13 +29,20 @@ It is an explicit 2D graphics device based on:
### Pixel format
- **RGB565**
- 5 bits Red
- 6 bits Green
- 5 bits Blue
- no alpha channel
- **RGBA8888**
- 8 bits Red
- 8 bits Green
- 8 bits Blue
- 8 bits Alpha
- canonical raw channel order: **RGBA**
Transparency is handled via **color key**.
The framebuffer alpha channel may carry meaningful runtime output. The runtime
MUST NOT force the published front buffer alpha channel to `255` as a blanket
contract.
Color values in the runtime, HAL, host-facing framebuffer, and GFX ABI are
logical RGBA8888 values. RGB565 is not a supported runtime framebuffer,
palette, host presentation, or compatibility contract.
---
@@ -232,16 +239,21 @@ Normative boundary:
---
## 12. Transparency (Color Key)
## 12. Transparency
- One RGB565 value is reserved as TRANSPARENT_KEY
- Pixels with this color are not drawn
Transparency is represented by the alpha channel of the resolved RGBA8888
color.
Palette indices are ordinary indices. The runtime MUST NOT reserve palette
index `0` as a special transparent index. A palette entry may still be authored
as transparent by setting its alpha channel to `0`, but that is ordinary palette
data rather than a special index rule.
```
if src == TRANSPARENT_KEY:
if resolved_color.alpha == 0:
skip
else:
draw
draw_or_blend(resolved_color)
```
@@ -259,8 +271,9 @@ Official modes:
- `BLEND_HALF_MINUS`
- `BLEND_FULL`
No continuous alpha.
No arbitrary blending.
Alpha is available through RGBA8888 colors. Discrete blend modes remain part of
the classic GFX contract, and later optimization work may specialize opaque,
masked, and alpha paths.
Everything is:
@@ -283,12 +296,13 @@ Everything is:
By design:
- Continuous alpha
- RGBA framebuffer
- Shaders
- Modern GPU pipeline
- HDR
- Gamma correction
- RGB565 compatibility framebuffers
- multi-format backend selection
- render-thread ownership as part of this contract
---
@@ -314,8 +328,7 @@ controls:
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
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.
---
@@ -327,32 +340,32 @@ 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: RGB565`
- `fade_color: RGBA8888`
- color the image will be blended into
Registers:
- `SCENE_FADE_LEVEL` (0..31)
- `SCENE_FADE_COLOR` (RGB565)
- `SCENE_FADE_COLOR` (RGBA8888)
- `HUD_FADE_LEVEL` (0..31)
- `HUD_FADE_COLOR` (RGB565)
- `HUD_FADE_COLOR` (RGBA8888)
Common cases:
- Fade-out: `fade_color = BLACK`
- Flash/teleport: `fade_color = WHITE`
- Special effects: any RGB565 color
- Special effects: any RGBA8888 color
---
### 17.2 Fade Operation (Blending with Arbitrary Color)
For each RGB565 pixel `src` and fade color `fc`, the final pixel `dst` is calculated per channel.
For each RGBA8888 pixel `src` and fade color `fc`, the final pixel `dst` is calculated per channel.
1) Extract components:
- `src_r5`, `src_g6`, `src_b5`
- `fc_r5`, `fc_g6`, `fc_b5`
- `src_r8`, `src_g8`, `src_b8`, `src_a8`
- `fc_r8`, `fc_g8`, `fc_b8`, `fc_a8`
2) Apply integer blending:
@@ -360,17 +373,18 @@ For each RGB565 pixel `src` and fade color `fc`, the final pixel `dst` is calcul
src_weight = fade_level // 0..31
fc_weight = 31 - fade_level
r5 = (src_r5 * src_weight + fc_r5 * fc_weight) / 31
g6 = (src_g6 * src_weight + fc_g6 * fc_weight) / 31
b5 = (src_b5 * src_weight + fc_b5 * fc_weight) / 31
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_r5`, `src_g6`, `src_b5`
- `fc_r5`, `fc_g6`, `fc_b5`
- `src_r8`, `src_g8`, `src_b8`, `src_a8`
- `fc_r8`, `fc_g8`, `fc_b8`, `fc_a8`
3) Repack:
```
dst = pack_rgb565(r5, g6, b5)
dst = pack_rgba8888_rgba(r8, g8, b8, a8)
```
@@ -425,8 +439,8 @@ Each pixel of a tile or sprite is:
Fixed rule:
- Index `0` = TRANSPARENT
- Indices `1..15` = valid palette colors
- Indices `0..15` are ordinary valid palette indices
- Transparency comes from the alpha channel of the resolved palette entry
---
@@ -437,13 +451,13 @@ Each **Tile Bank** contains:
- **64 palettes** in runtime-facing v1
- Each palette has:
- **16 colors**
- each color in **RGB565 (`u16`, little-endian in serialized assets)**
- each color in **RGBA8888** with canonical RGBA channel order
Size:
- 1 palette = 16 × 2 bytes = **32 bytes**
- 64 palettes = **2 KB per bank**
- 16 banks = **32 KB maximum palettes**
- 1 palette = 16 × 4 bytes = **64 bytes**
- 64 palettes = **4 KB per bank**
- 16 banks = **64 KB maximum palettes**
---
@@ -496,22 +510,22 @@ Runtime-facing validity rule for v1:
The pipeline works like this:
1. Read indexed pixel from tile (value 0..15)
2. If index == 0 → transparent pixel
3. Otherwise:
2. Resolve:
- real_color = palette[palette_id][index]
4. Apply:
3. Apply:
- flip
- discrete blend
- alpha/skip behavior from the resolved RGBA8888 color
- writing to back buffer
In other words:
```
pixel_index = tile_pixel(x,y)
if pixel_index == 0:
color = bank.palettes[palette_id][pixel_index]
if color.alpha == 0:
skip
else:
color = bank.palettes[palette_id][pixel_index]
draw(color)
draw_or_blend(color)
```
---
@@ -578,7 +592,6 @@ Fault boundary:
| `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 |
| `gfx.clear_565` | `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 |