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