104 lines
3.5 KiB
Markdown
104 lines
3.5 KiB
Markdown
---
|
|
id: PLN-0071
|
|
ticket: rgba8888-framebuffer-and-pixel-format-direction
|
|
title: RGBA8888 Host Presentation Path
|
|
status: open
|
|
created: 2026-05-23
|
|
ref_decisions: [DEC-0029]
|
|
tags: [gfx, framebuffer, rgb565, rgba8888, renderer, assets, host, backend]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Move the desktop host presentation path from RGB565 conversion to direct
|
|
RGBA8888 presentation. This plan removes the normal `draw_rgb565_to_rgba8`
|
|
path after the runtime publishes RGBA8888 frames.
|
|
|
|
## Source Decisions
|
|
|
|
- DEC-0029 - RGBA8888 Runtime Pixel Format Contract.
|
|
|
|
## Dependencies
|
|
|
|
- PLN-0067 for host/spec contract wording.
|
|
- PLN-0068 for public framebuffer type and ABI naming.
|
|
- PLN-0069 for renderer front-buffer RGBA8888 storage.
|
|
|
|
## Target
|
|
|
|
The host must consume RGBA8888 frames directly in the normal presentation path
|
|
and must not convert RGB565 frames on every redraw.
|
|
|
|
## Scope
|
|
|
|
Included:
|
|
|
|
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`.
|
|
- `crates/host/prometeu-host-desktop-winit/src/utilities.rs`.
|
|
- Host tests or utility tests for frame copy/channel order.
|
|
- Host overlay integration where it assumes RGBA8 frame bytes.
|
|
|
|
## Out of Scope
|
|
|
|
- Changing the windowing library.
|
|
- Introducing wgpu/OpenGL/SDL backend abstractions.
|
|
- Changing host frame pacing.
|
|
- Changing render thread ownership.
|
|
- Performance optimization beyond removing RGB565 conversion from the normal
|
|
path.
|
|
|
|
## Execution Plan
|
|
|
|
1. Replace host frame conversion.
|
|
- Remove use of `draw_rgb565_to_rgba8` from `runner.rs`.
|
|
- Copy or expose RGBA8888 runtime pixels into the `pixels` frame using the
|
|
documented RGBA channel order.
|
|
- Preserve meaningful alpha unless the presentation library explicitly
|
|
requires conversion; if conversion is required, document it as host
|
|
presentation behavior, not runtime framebuffer semantics.
|
|
|
|
2. Remove RGB565 utilities from the normal path.
|
|
- Delete `draw_rgb565_to_rgba8` and `rgb565_to_rgb888` if no tests or
|
|
temporary migration tools need them.
|
|
- If temporary conversion helpers remain for fixture regeneration, move them
|
|
out of host presentation utilities and mark them non-runtime.
|
|
|
|
3. Verify overlay compatibility.
|
|
- Ensure host overlay writes still target RGBA8 bytes in the `pixels` frame.
|
|
- Ensure overlay composition does not assume the emulated framebuffer itself
|
|
is opaque.
|
|
|
|
4. Update host tests.
|
|
- Add or update tests for RGBA channel order.
|
|
- Include a source pixel with non-`255` alpha.
|
|
- Remove tests that only prove RGB565 expansion.
|
|
|
|
5. Run residue scan.
|
|
- Search host crate for `rgb565`, `RGB565`, `draw_rgb565`, and `u16`
|
|
framebuffer assumptions.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] The desktop host normal redraw path consumes RGBA8888 frames.
|
|
- [ ] `draw_rgb565_to_rgba8` is not used by host presentation.
|
|
- [ ] Host channel order matches canonical RGBA.
|
|
- [ ] Host presentation does not force runtime front-buffer alpha to `255` as a
|
|
runtime contract.
|
|
- [ ] Host tests are RGBA8888-first.
|
|
|
|
## Tests / Validation
|
|
|
|
- Run `cargo test -p prometeu-host-desktop-winit`.
|
|
- Run a targeted host scan for `rgb565`, `RGB565`, and `draw_rgb565`.
|
|
- Run an interactive smoke test only if the repo already has a standard host
|
|
smoke command; otherwise record that manual visual validation remains for the
|
|
final validation plan.
|
|
- Run `discussion validate`.
|
|
|
|
## Risks
|
|
|
|
- The `pixels` frame is byte-oriented; byte order mistakes are easy. Tests must
|
|
use non-symmetric color values and non-opaque alpha.
|
|
- If runtime publishes `u32`, host code must explicitly define how the `u32`
|
|
maps to RGBA bytes instead of relying on native endian layout.
|