---
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.