120 lines
4.5 KiB
Markdown
120 lines
4.5 KiB
Markdown
---
|
|
id: PLN-0072
|
|
ticket: rgba8888-framebuffer-and-pixel-format-direction
|
|
title: RGBA8888 Residue Removal and End to End Validation
|
|
status: done
|
|
created: 2026-05-23
|
|
ref_decisions: [DEC-0029]
|
|
tags: [gfx, framebuffer, rgb565, rgba8888, renderer, assets, host, backend]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Close the RGBA8888 migration by removing residual RGB565 contract text and code
|
|
paths, running end-to-end validation, and preparing the discussion thread for
|
|
post-execution lessons.
|
|
|
|
## Source Decisions
|
|
|
|
- DEC-0029 - RGBA8888 Runtime Pixel Format Contract.
|
|
|
|
## Dependencies
|
|
|
|
- PLN-0067 through PLN-0071 must be complete or merged into the execution branch.
|
|
|
|
## Target
|
|
|
|
The repository must no longer expose RGB565, `Gfx*565`, `u16` framebuffer/color
|
|
contracts, RGB565 palette payloads, or RGB565 host conversion as active runtime
|
|
contract.
|
|
|
|
## Scope
|
|
|
|
Included:
|
|
|
|
- Whole-repository residue audit.
|
|
- End-to-end build and test validation.
|
|
- Documentation consistency checks.
|
|
- Final migration notes needed for housekeeping and lessons.
|
|
- Any small missed cleanup in code, docs, tests, or fixtures that directly
|
|
violates DEC-0029.
|
|
|
|
## Out of Scope
|
|
|
|
- New alpha-only commands.
|
|
- Performance optimization after broad alpha support.
|
|
- GPU backend, render thread, RGB565 backend, multi-format backend abstraction.
|
|
- New visual design work for the Hub.
|
|
|
|
## Execution Plan
|
|
|
|
1. Run repository-wide residue scans.
|
|
- Search for `RGB565`, `rgb565`, `Gfx.*565`, `clear_565`, `u16` near color
|
|
or framebuffer APIs, `GLYPH_BANK_PALETTE.*u16`, `size_of::<u16>()` near
|
|
palette code, `draw_rgb565`, and `0xFFFF` near color validation.
|
|
- Classify every remaining hit as removed, historical-only, unrelated, or a
|
|
bug.
|
|
|
|
2. Remove active-contract residues.
|
|
- Delete or rename any remaining active `Gfx*565` surface.
|
|
- Remove RGB565 helpers from runtime and host normal paths.
|
|
- Remove comments that still describe RGB565 as current behavior.
|
|
- Remove tests that assert RGB565 output.
|
|
|
|
3. Verify docs and ABI consistency.
|
|
- Ensure `docs/specs/runtime/04-gfx-peripheral.md`,
|
|
`docs/specs/runtime/15-asset-management.md`, and
|
|
`docs/specs/runtime/16-host-abi-and-syscalls.md` agree on RGBA8888.
|
|
- Ensure public syscall declarations and docs use format-neutral names.
|
|
- Ensure any historical RGB565 mention is clearly historical and not
|
|
normative.
|
|
|
|
4. Run full test/build validation.
|
|
- Run the repo's standard build command.
|
|
- Run the relevant Rust test suites across HAL, drivers, system, VM, tools,
|
|
and host.
|
|
- Run any visual/snapshot validation available in the repository.
|
|
|
|
5. Record final evidence.
|
|
- Capture the exact commands and outcomes in the plan or final PR notes.
|
|
- List remaining historical RGB565 mentions and why they are acceptable.
|
|
- Identify lesson candidates for `discussion-housekeep` after execution.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] Repository scan finds no active RGB565 runtime contract.
|
|
- [ ] No public `Gfx*565` API, syscall, metadata, or ABI declaration remains.
|
|
- [ ] No normal renderer or host path performs RGB565 conversion.
|
|
- [ ] No asset decode path accepts RGB565 palettes as compatible runtime input.
|
|
- [ ] Specs, docs, ABI contracts, code, fixtures, and tests agree on RGBA8888.
|
|
- [ ] Full validation commands pass or any failure is documented as unrelated.
|
|
- [ ] The discussion thread has enough evidence for housekeeping and lessons.
|
|
|
|
## Tests / Validation
|
|
|
|
- Run the standard repository build command.
|
|
- Run affected crate tests: `prometeu-hal`, `prometeu-drivers`,
|
|
`prometeu-system`, `prometeu-vm`, `prometeu-bytecode`,
|
|
`prometeu-host-desktop-winit`, and `pbxgen-stress` where applicable.
|
|
- Run all available visual/snapshot tests.
|
|
- Run repository-wide `rg` residue scans described above.
|
|
- Run `discussion validate`.
|
|
|
|
## Risks
|
|
|
|
- Some remaining RGB565 references may be legitimate historical notes. They
|
|
must be marked clearly enough that readers cannot mistake them for active
|
|
contract.
|
|
- End-to-end visual validation may not exist yet. If so, record the gap and add
|
|
minimal deterministic checks around RGBA channel order and alpha behavior.
|
|
|
|
## Validation Evidence
|
|
|
|
- `cargo check --workspace` passed.
|
|
- `cargo test --workspace` passed.
|
|
- `discussion validate` passed.
|
|
- Residue scan command:
|
|
`rg -n "RGB565|rgb565|Gfx.*565|clear_565|_565|draw_rgb565|0x1010|front_buffer\\(\\).*u16|Vec<u16>|\\[u16\\]|GLYPH_BANK_PALETTE.*u16|size_of::<u16>|from_rgb565|to_rgb565" crates docs -S`
|
|
- Remaining scan hits are either negative normative documentation or unrelated
|
|
`u16` uses such as VM verifier instruction offsets / glyph ids.
|