107 lines
4.2 KiB
Markdown
107 lines
4.2 KiB
Markdown
---
|
|
id: PLN-0067
|
|
ticket: rgba8888-framebuffer-and-pixel-format-direction
|
|
title: RGBA8888 Published Contracts and Specs
|
|
status: done
|
|
created: 2026-05-23
|
|
ref_decisions: [DEC-0029]
|
|
tags: [gfx, framebuffer, rgb565, rgba8888, renderer, assets, host, backend]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Publish the RGBA8888 contract before touching runtime code. This plan updates
|
|
the canonical specs, ABI documentation, and public docs so the repository has a
|
|
single written source of truth for the migration required by DEC-0029.
|
|
|
|
## Source Decisions
|
|
|
|
- DEC-0029 - RGBA8888 Runtime Pixel Format Contract.
|
|
|
|
## Target
|
|
|
|
Document RGBA8888 as the only supported runtime color and framebuffer contract,
|
|
remove RGB565 compatibility language from published contracts, and define
|
|
format-neutral GFX API naming rules.
|
|
|
|
## Scope
|
|
|
|
Included:
|
|
|
|
- Update `docs/specs/runtime/04-gfx-peripheral.md` to define logical color,
|
|
framebuffer output, alpha behavior, and format-neutral GFX command naming.
|
|
- Update `docs/specs/runtime/15-asset-management.md` to define RGBA8888 palette
|
|
entries in `assets.pa` and remove RGB565 palette compatibility.
|
|
- Update `docs/specs/runtime/16-host-abi-and-syscalls.md` to remove `Gfx*565`
|
|
as public ABI and define format-neutral syscall names such as `GfxClear`.
|
|
- Update `docs/specs/runtime/02a-vm-values-and-calling-convention.md` only if
|
|
it describes raw color value width/range.
|
|
- Update `docs/specs/runtime/11-portability-and-cross-platform-execution.md`
|
|
only if it describes host framebuffer format or RGB565 presentation.
|
|
- Update `docs/specs/runtime/README.md` if the index or spec summaries mention
|
|
RGB565 as current contract.
|
|
|
|
## Out of Scope
|
|
|
|
- Code changes under `crates/`.
|
|
- Asset fixture regeneration.
|
|
- Host presentation implementation.
|
|
- Lessons; they are written after execution, not before.
|
|
- New backend abstractions, render thread, GPU backend, RGB565 fallback.
|
|
|
|
## Execution Plan
|
|
|
|
1. Audit published contract text.
|
|
- Search `docs/` for `RGB565`, `rgb565`, `565`, `u16`, `GfxClear565`,
|
|
`Gfx*565`, `front_buffer`, `palette`, `assets.pa`, and `RGBA`.
|
|
- Classify each hit as historical, obsolete contract, or still-valid
|
|
implementation detail.
|
|
|
|
2. Update the GFX peripheral spec.
|
|
- State that runtime color values are RGBA8888 in RGBA channel order.
|
|
- State that front-buffer alpha may be meaningful.
|
|
- State that GFX APIs must be format-neutral and must not expose `Gfx*565`.
|
|
- State that palette indices are ordinary indices and transparency comes
|
|
from resolved RGBA alpha.
|
|
|
|
3. Update asset-management specs.
|
|
- Define palette entries as RGBA8888.
|
|
- Keep indexed tile/sprite payloads and palette limits if already specified.
|
|
- Remove compatibility promises for RGB565 palette payloads.
|
|
- Call out that existing RGB565 assets must be regenerated or converted by
|
|
tooling, not accepted as runtime compatibility input.
|
|
|
|
4. Update host and ABI specs.
|
|
- Replace RGB565 and `u16` color/framebuffer ABI language with RGBA8888.
|
|
- Replace `GfxClear565` and any `Gfx*565` surface with format-neutral names.
|
|
- Document expected syscall color range/shape for RGBA8888 values.
|
|
|
|
5. Add a short migration note to each touched spec.
|
|
- Reference DEC-0029.
|
|
- Make clear that RGB565 text is superseded for the active runtime contract.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `docs/` no longer describes RGB565 as the current runtime color,
|
|
framebuffer, palette, or host presentation contract.
|
|
- [ ] `docs/` no longer describes `Gfx*565` as public canonical ABI.
|
|
- [ ] Specs state RGBA8888 raw channel order as RGBA.
|
|
- [ ] Specs state that front-buffer alpha may be meaningful.
|
|
- [ ] Specs state that palette transparency comes from alpha, not reserved index
|
|
`0`.
|
|
- [ ] Specs state that RGB565 asset palettes are not compatible runtime input.
|
|
|
|
## Tests / Validation
|
|
|
|
- Run a repository text audit with `rg -n "RGB565|rgb565|Gfx.*565|u16|565" docs`
|
|
and verify every remaining hit is explicitly historical or unrelated.
|
|
- Run `discussion validate`.
|
|
- No Rust build is required for this docs-only plan.
|
|
|
|
## Risks
|
|
|
|
- Specs may contain old historical sections that should remain for context. If
|
|
retained, they must be marked historical and must not read as active contract.
|
|
- Some ABI names may be generated from Rust enums; this plan documents the
|
|
target but does not update generated code.
|