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