housekeep DSC-0037
This commit is contained in:
+78
@@ -0,0 +1,78 @@
|
||||
---
|
||||
id: LSN-0046
|
||||
ticket: rgba8888-framebuffer-and-pixel-format-direction
|
||||
title: Pixel Format Contracts Must Move as One Surface
|
||||
created: 2026-05-23
|
||||
tags: [gfx, framebuffer, rgba8888, abi, assets, host]
|
||||
decision: DEC-0029
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
The runtime migrated its graphics contract from RGB565 to RGBA8888. The
|
||||
important discovery was that RGB565 was not only a renderer storage detail. It
|
||||
had become a cross-cutting contract spanning VM values, syscalls, HAL types,
|
||||
renderer buffers, asset palette bytes, host presentation, tests, and specs.
|
||||
|
||||
Treating the change as a local buffer replacement would have left contradictory
|
||||
contracts behind. The successful migration split the work into small plans, but
|
||||
each plan still respected one global rule: a pixel format is a published
|
||||
surface, not an implementation token.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### RGBA8888 Runtime Pixel Format Contract
|
||||
|
||||
**What:** RGBA8888 became the single logical color and physical framebuffer
|
||||
contract. RGB565 compatibility surfaces were removed instead of deprecated as
|
||||
canonical aliases.
|
||||
|
||||
**Why:** Keeping RGB565 as compatibility would have preserved the old coupling
|
||||
between logical color, framebuffer storage, asset palette encoding, and host
|
||||
presentation. A single RGBA8888 contract made the runtime easier to reason
|
||||
about and aligned with alpha-capable UI and modern host presentation.
|
||||
|
||||
**Trade-offs:** The migration intentionally broke existing RGB565 assets and
|
||||
tests. It also doubled framebuffer byte width. The payoff was removing support
|
||||
for two simultaneous color models and making alpha an ordinary property of
|
||||
color instead of a special case.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
Move published contracts before code. Specs, ABI docs, and public docs were
|
||||
updated first so implementation work had a stable target.
|
||||
|
||||
Keep API names format-neutral when the runtime supports only one format.
|
||||
Names such as `GfxClear565` create permanent compatibility residue. The
|
||||
canonical surface should be `GfxClear`; RGBA8888 is the contract behind it.
|
||||
|
||||
Use the alpha channel as data, not a magic index. Palette indices are ordinary
|
||||
indices. Transparency is represented by the RGBA alpha channel of the resolved
|
||||
palette entry rather than by reserving palette index `0`.
|
||||
|
||||
Validate with residue scans. The final pass searched for RGB565, `Gfx*565`,
|
||||
RGB565 palette sizing, host conversion helpers, and `u16` framebuffer surfaces.
|
||||
Remaining hits had to be negative documentation or unrelated `u16` usage.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
Pixel format names leak into places that look unrelated: generator fixtures,
|
||||
cartridge payload size calculations, syscall metadata, host copy utilities, and
|
||||
test assembly snippets.
|
||||
|
||||
Endian assumptions are easy to hide when using `u32`. The contract must say
|
||||
RGBA channel order explicitly, and host presentation code must unpack channels
|
||||
by shifts instead of relying on native memory layout.
|
||||
|
||||
Compatibility helpers are useful only as short-lived scaffolding. If they are
|
||||
left in normal paths, they become a second contract.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- A framebuffer format is a runtime-wide contract once it reaches ABI, assets,
|
||||
host presentation, or tests.
|
||||
- Format-suffixed public APIs should be removed when the format is no longer a
|
||||
selectable backend.
|
||||
- Alpha should be modeled as color data, not as a reserved palette index.
|
||||
- A staged migration can still enforce one final contract when each plan has a
|
||||
residue scan and acceptance criteria.
|
||||
Reference in New Issue
Block a user