110 lines
4.0 KiB
Markdown
110 lines
4.0 KiB
Markdown
---
|
|
id: PLN-0069
|
|
ticket: rgba8888-framebuffer-and-pixel-format-direction
|
|
title: RGBA8888 CPU Renderer and Composition
|
|
status: done
|
|
created: 2026-05-23
|
|
ref_decisions: [DEC-0029]
|
|
tags: [gfx, framebuffer, rgb565, rgba8888, renderer, assets, host, backend]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Migrate the existing CPU renderer and frame composition path from RGB565
|
|
storage to RGBA8888 storage. This plan keeps the current destructive renderer
|
|
model and does not introduce a render thread or backend abstraction.
|
|
|
|
## Source Decisions
|
|
|
|
- DEC-0029 - RGBA8888 Runtime Pixel Format Contract.
|
|
|
|
## Dependencies
|
|
|
|
- PLN-0067 for published contract wording.
|
|
- PLN-0068 for `Color`, HAL, and syscall boundary semantics.
|
|
|
|
## Target
|
|
|
|
The renderer front/back buffers, render target writes, fades, blends, text,
|
|
tiles, sprites, and frame composer tests must operate on RGBA8888 pixels.
|
|
|
|
## Scope
|
|
|
|
Included:
|
|
|
|
- `crates/console/prometeu-drivers/src/gfx.rs`.
|
|
- `crates/console/prometeu-drivers/src/frame_composer.rs`.
|
|
- `crates/console/prometeu-drivers/src/hardware.rs` where framebuffer/color
|
|
assumptions are tested or documented.
|
|
- HAL bridge implementation in drivers if it still returns `&[u16]`.
|
|
- Renderer unit tests and frame-composer tests that assert raw pixel values.
|
|
|
|
## Out of Scope
|
|
|
|
- Asset package palette serialization changes; covered by PLN-0070.
|
|
- Host presentation conversion removal; covered by PLN-0071.
|
|
- GPU backend, render thread, dirty-region optimization, span optimization, or
|
|
multi-format backend abstraction.
|
|
- Alpha-only commands.
|
|
|
|
## Execution Plan
|
|
|
|
1. Change renderer storage to RGBA8888.
|
|
- Replace `front: Vec<u16>` and `back: Vec<u16>` with RGBA8888 storage.
|
|
- Update `RenderTarget` and all buffer accessors to the new pixel type.
|
|
- Ensure `present()` keeps its swap semantics.
|
|
|
|
2. Update primitive writes.
|
|
- `clear`, `draw_pixel`, `fill_rect`, `draw_text`, hardware font drawing,
|
|
and overlay primitives must write RGBA8888 values.
|
|
- Opaque calls may write direct RGBA8888 pixels.
|
|
- Alpha values must be preserved according to the operation semantics.
|
|
|
|
3. Replace RGB565 blending/fade.
|
|
- Replace `blend_rgb565` with RGBA8888 blend logic.
|
|
- Update `apply_fade_to_buffer` to operate on RGBA channels.
|
|
- Do not force final alpha to `255`; preserve or compute alpha according to
|
|
the operation.
|
|
|
|
4. Update tile and sprite composition.
|
|
- Resolve palette entries as RGBA8888 colors.
|
|
- Do not treat palette index `0` as automatically transparent.
|
|
- Skip or blend based on resolved alpha and operation semantics.
|
|
- Allow alpha across tile, sprite, primitive, UI/effect, and fade paths.
|
|
|
|
5. Update frame composer expectations.
|
|
- Tests must assert RGBA8888 raw values.
|
|
- Any old RGB565 expected values must be regenerated from RGBA source colors,
|
|
not converted as compatibility behavior.
|
|
|
|
6. Isolate temporary compile seams.
|
|
- If asset decode still supplies RGBA8888 `Color` through old fixture bytes,
|
|
keep the fixture problem contained for PLN-0070 and do not add runtime
|
|
RGB565 compatibility to the renderer.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] Renderer front/back buffers materialize RGBA8888 pixels.
|
|
- [ ] `front_buffer()` no longer exposes `&[u16]` in the driver/HAL
|
|
implementation path.
|
|
- [ ] RGB565 blend/fade helpers are removed from renderer normal paths.
|
|
- [ ] Tile/sprite transparency is based on RGBA alpha, not palette index `0`.
|
|
- [ ] Renderer and frame-composer tests assert RGBA8888 values.
|
|
- [ ] No render thread, GPU backend, RGB565 backend, or multi-format backend is
|
|
introduced.
|
|
|
|
## Tests / Validation
|
|
|
|
- Run renderer unit tests in `prometeu-drivers`.
|
|
- Run frame composer tests in `prometeu-drivers`.
|
|
- Run targeted scans for `blend_rgb565`, `Vec<u16>`, `&[u16]`, and `RGB565` in
|
|
renderer files.
|
|
- Run `discussion validate`.
|
|
|
|
## Risks
|
|
|
|
- This plan will likely touch many assertions. Keep each assertion update tied
|
|
to a known RGBA value.
|
|
- Alpha behavior can expose previously hidden assumptions in tests. Preserve the
|
|
decision rule: alpha is allowed broadly and optimization comes later.
|