---
id: PLN-0070
ticket: rgba8888-framebuffer-and-pixel-format-direction
title: RGBA8888 Asset Palettes Tooling and Fixtures
status: open
created: 2026-05-23
ref_decisions: [DEC-0029]
tags: [gfx, framebuffer, rgb565, rgba8888, renderer, assets, host, backend]
---

## Briefing

Migrate asset palette serialization, decode, generators, and fixtures to
RGBA8888. This plan intentionally breaks RGB565 palette compatibility rather
than preserving it through runtime fallback.

## Source Decisions

- DEC-0029 - RGBA8888 Runtime Pixel Format Contract.

## Dependencies

- PLN-0067 for asset spec wording.
- PLN-0068 for RGBA8888 `Color`.
- PLN-0069 may run before or alongside this plan, but renderer normal paths must
  not require RGB565 palette compatibility.

## Target

`assets.pa` glyph-bank palette payloads, runtime decode, generators, and tests
must use RGBA8888 palette entries with RGBA channel order.

## Scope

Included:

- `crates/console/prometeu-hal/src/glyph_bank.rs`.
- `crates/console/prometeu-hal/src/asset.rs`.
- `crates/console/prometeu-hal/src/cartridge_loader.rs`.
- `crates/console/prometeu-drivers/src/asset.rs`.
- `crates/tools/pbxgen-stress/src/lib.rs` and related generator code.
- Runtime and system tests that compute glyph-bank payload sizes.
- Test fixtures and generated `assets.pa` payload builders in the repository.

## Out of Scope

- Supporting legacy RGB565 assets at runtime.
- Adding a general asset package v2 negotiation layer unless the existing format
  requires an explicit version bump to avoid ambiguous decode.
- Changing tile/sprite index packing beyond what RGBA8888 palettes require.
- Changing palette count or colors-per-palette limits.

## Execution Plan

1. Change palette byte accounting.
   - Replace palette entry size from `size_of::<u16>()` / `2` bytes to `4`
     bytes.
   - Update decoded-size calculations in asset decode, cartridge loader tests,
     VM runtime tests, and pbxgen-stress.

2. Decode palettes as RGBA8888.
   - Read each palette entry as four bytes in RGBA order.
   - Construct `Color` through RGBA8888 APIs, not `Color(raw_u16)`.
   - Reject payloads whose palette byte size matches old RGB565 layout when the
     format can identify the mismatch.

3. Update glyph-bank semantics.
   - Keep `pixel_indices: Vec<u8>` and 4bpp authored payloads where currently
     specified.
   - Keep palette count and colors-per-palette constants unless the spec says
     otherwise.
   - Remove comments that say runtime palettes are RGB565.
   - Ensure palette index `0` is not treated as transparent by decode or data
     model.

4. Update generators and fixtures.
   - Make `pbxgen-stress` emit RGBA8888 palette bytes.
   - Regenerate inline fixture builders to append four-byte RGBA palette
     entries.
   - Do not keep RGB565 fixture decode as runtime compatibility.

5. Update asset tests.
   - Assert RGBA channel order.
   - Include at least one non-opaque alpha value in a palette entry.
   - Assert payload size failures for old two-byte palette layout where
     practical.

## Acceptance Criteria

- [ ] Glyph-bank palette payloads are RGBA8888 and use four bytes per entry.
- [ ] Asset decode constructs RGBA8888 `Color` values in RGBA order.
- [ ] Existing RGB565 palette payloads are not accepted as compatible runtime
  input.
- [ ] `pbxgen-stress` emits RGBA8888 palettes.
- [ ] Tests include meaningful alpha in palette entries.
- [ ] Palette index `0` has no special transparency semantics in asset decode.

## Tests / Validation

- Run asset decode tests in `prometeu-drivers`.
- Run cartridge loader tests in `prometeu-hal`.
- Run VM runtime asset tests in `prometeu-system`.
- Run `cargo test -p pbxgen-stress` if available.
- Run scans for `GLYPH_BANK_PALETTE.*u16`, `* 2`, `size_of::<u16>()`, and
  `RGB565` in asset/glyph-bank/tooling files.
- Run `discussion validate`.

## Risks

- Payload-size constants are duplicated in tests. Update all derived size
  helpers in the same PR to avoid misleading failures.
- If the existing asset package has no version marker for palette encoding, the
  plan must choose an explicit metadata/version discriminator before accepting
  ambiguous payloads.