prometeu-runtime/discussion/workflow/plans/PLN-0071-rgba8888-host-presentation-path.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0071	rgba8888-framebuffer-and-pixel-format-direction	RGBA8888 Host Presentation Path	open	2026-05-23	DEC-0029	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.