115 lines
4.1 KiB
Markdown
115 lines
4.1 KiB
Markdown
---
|
|
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.
|