prometeu-runtime/discussion/workflow/plans/PLN-0069-rgba8888-cpu-renderer-and-composition.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0069	rgba8888-framebuffer-and-pixel-format-direction	RGBA8888 CPU Renderer and Composition	done	2026-05-23	DEC-0029	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.