RGBA8888 Framebuffer and Pixel Format Direction
This commit is contained in:
@@ -0,0 +1,203 @@
|
||||
---
|
||||
id: DEC-0029
|
||||
ticket: rgba8888-framebuffer-and-pixel-format-direction
|
||||
title: RGBA8888 Runtime Pixel Format Contract
|
||||
status: accepted
|
||||
created: 2026-05-23
|
||||
ref_agenda: AGD-0037
|
||||
tags: [gfx, framebuffer, rgb565, rgba8888, renderer, assets, host, backend]
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
Accepted. Drafted from accepted agenda AGD-0037 and accepted on 2026-05-23.
|
||||
Execution is split across the linked RGBA8888 migration plan family.
|
||||
|
||||
## Contexto
|
||||
|
||||
AGD-0037 evaluated whether Prometeu should keep RGB565 as the runtime color
|
||||
and framebuffer contract or migrate to RGBA8888.
|
||||
|
||||
RGB565 is currently coupled into multiple layers:
|
||||
|
||||
- the public `Color(pub u16)` representation;
|
||||
- HAL and VM-facing GFX APIs such as `front_buffer() -> &[u16]` and
|
||||
`GfxClear565`;
|
||||
- renderer front/back buffers and blending helpers;
|
||||
- host presentation through RGB565-to-RGBA8 conversion;
|
||||
- serialized asset palettes in `assets.pa`;
|
||||
- tests and fixtures that assert RGB565 values.
|
||||
|
||||
The accepted agenda resolves that RGB565 should not remain as compatibility
|
||||
surface in this migration. RGBA8888 becomes both the logical color contract and
|
||||
the physical framebuffer format. This decision replaces the prior performance
|
||||
phase direction in AGD-0010 that rejected RGBA8888 for the back buffer.
|
||||
|
||||
## Decisao
|
||||
|
||||
Prometeu SHALL migrate its normal runtime graphics contract from RGB565 to
|
||||
RGBA8888.
|
||||
|
||||
RGBA8888 MUST be the single canonical logical color representation for the
|
||||
runtime, HAL, VM-facing color values, renderer buffers, asset palette decode,
|
||||
tests, and host presentation path.
|
||||
|
||||
RGBA8888 MUST also be the single canonical physical framebuffer format for this
|
||||
wave. RGB565 MUST NOT remain as a supported runtime framebuffer backend,
|
||||
compatibility mode, normal palette encoding, VM color ABI, renderer pixel
|
||||
format, or host presentation contract.
|
||||
|
||||
The canonical raw channel order is RGBA.
|
||||
|
||||
The published front buffer MAY contain meaningful alpha. The runtime MUST NOT
|
||||
force the final front buffer alpha channel to `255` as a blanket rule in this
|
||||
wave.
|
||||
|
||||
Alpha is allowed broadly. Palettes, sprites, tiles, primitives, UI/effects, and
|
||||
renderer operations MAY carry and apply real alpha where the operation needs
|
||||
it. The first implementation wave SHALL treat alpha as available across all
|
||||
operations rather than splitting the migration into alpha-capable and
|
||||
alpha-forbidden paths.
|
||||
|
||||
Dedicated commands for managing only alpha are expected in the broader design,
|
||||
but they are explicitly out of scope for this wave.
|
||||
|
||||
Asset packages MUST encode palettes as RGBA8888. Existing RGB565 palette assets
|
||||
MUST NOT be preserved as compatible runtime input. Any old asset or fixture that
|
||||
is still needed must be regenerated or converted as part of migration work, not
|
||||
supported through a permanent compatibility path.
|
||||
|
||||
Tests MUST be RGBA8888-first. They MUST assert the new RGBA8888 contract rather
|
||||
than proving binary equivalence with RGB565 output.
|
||||
|
||||
This decision does not introduce render thread ownership, a GPU backend, an
|
||||
RGB565 backend, or a generic multi-format backend abstraction.
|
||||
|
||||
## Rationale
|
||||
|
||||
RGB565 currently plays too many roles at once: logical color, physical pixel,
|
||||
serialized palette encoding, and host presentation source. Keeping it as a
|
||||
compatibility layer would preserve that coupling and force the new RGBA8888
|
||||
direction to coexist with an old contract that the runtime no longer wants to
|
||||
guarantee.
|
||||
|
||||
RGBA8888 aligns better with modern host APIs, texture upload paths, alpha-based
|
||||
UI, Hub visuals, and future GPU-oriented work. It also removes the mandatory
|
||||
RGB565-to-RGBA8 conversion in the desktop host's normal presentation path.
|
||||
|
||||
The migration deliberately accepts the cost of a coordinated breaking change:
|
||||
HAL, VM/syscalls, renderer buffers, asset decode, tooling, fixtures, and tests
|
||||
must move together. The result is simpler than maintaining two color formats or
|
||||
a premature backend matrix.
|
||||
|
||||
The fantasy-console identity is not tied to RGB565 memory layout. It should be
|
||||
preserved by resolution, indexed assets, palette limits, art direction,
|
||||
authoring constraints, and composition rules.
|
||||
|
||||
Allowing meaningful framebuffer alpha and broad alpha in operations keeps the
|
||||
contract flexible while the renderer evolves. Performance specialization remains
|
||||
important, but it should follow the correctness migration instead of blocking
|
||||
the pixel-format contract.
|
||||
|
||||
## Invariantes / Contrato
|
||||
|
||||
- `Color` or its replacement MUST represent RGBA8888 semantics in the final
|
||||
contract.
|
||||
- Raw color values MUST use RGBA channel order.
|
||||
- Runtime renderer front/back buffers MUST materialize RGBA8888 pixels.
|
||||
- Public runtime/HAL/host contracts MUST stop exposing `&[u16]` as the normal
|
||||
framebuffer output.
|
||||
- Format-suffixed compatibility APIs such as `GfxClear565` or any other
|
||||
`Gfx*565` surface MUST cease to exist in the final contract. Canonical GFX API
|
||||
names MUST be format-neutral, e.g. `GfxClear`, because RGBA8888 is the only
|
||||
supported runtime color contract.
|
||||
- RGB565 conversion helpers may exist only as temporary migration utilities or
|
||||
test-regeneration tools; they MUST NOT sit on the normal runtime hot path.
|
||||
- Asset palette payloads MUST be RGBA8888.
|
||||
- Indexed tile/sprite payloads MAY remain indexed/paletized; palette index
|
||||
limits and 4bpp authored pixels may remain part of the artistic model.
|
||||
- Palette indices are ordinary indices. Transparency MUST be represented by the
|
||||
RGBA alpha channel of the resolved palette entry, not by reserving palette
|
||||
index `0` as a special transparent index.
|
||||
- Alpha MAY be meaningful in palettes, sprites, tiles, primitives, UI/effects,
|
||||
composed framebuffer pixels, and published front-buffer pixels.
|
||||
- The first migration wave MUST allow alpha across all renderer operations.
|
||||
- Optimization work MAY later add faster opaque/masked/alpha paths, but that
|
||||
optimization MUST NOT reintroduce RGB565 as a supported contract.
|
||||
- Tests MUST use RGBA8888 expectations as source of truth.
|
||||
- Render thread, GPU backend, RGB565 backend, SDL/wgpu backend abstraction, and
|
||||
multi-format `FrameSurface` design are out of scope for this decision's
|
||||
first execution wave.
|
||||
|
||||
## Impactos
|
||||
|
||||
### Spec
|
||||
|
||||
Canonical specs for GFX, assets, VM/syscalls, and host presentation need to be
|
||||
updated to describe RGBA8888 as the normal color and framebuffer contract.
|
||||
Published specs must be in English.
|
||||
|
||||
Spec updates are mandatory propagation for this decision, not follow-up cleanup.
|
||||
|
||||
### Runtime / HAL
|
||||
|
||||
The HAL color type, raw color APIs, framebuffer accessor, clear operation,
|
||||
blend/fade helpers, renderer target storage, and tests must migrate away from
|
||||
RGB565. Compatibility API names that encode RGB565, including any `Gfx*565`
|
||||
surface, must be removed rather than carried forward as deprecated canonical
|
||||
surface.
|
||||
|
||||
### Host
|
||||
|
||||
The desktop host must consume RGBA8888 frames directly in the normal path. The
|
||||
existing RGB565-to-RGBA8 conversion path must be removed from normal
|
||||
presentation.
|
||||
|
||||
### Firmware / VM / PBS
|
||||
|
||||
VM-facing color values and syscall validation must change from the RGB565
|
||||
`0xFFFF` range to the RGBA8888 contract. PBS or syscall declarations that expose
|
||||
`GfxClear565`, any other `Gfx*565` surface, or raw RGB565 color must be replaced
|
||||
with format-neutral APIs such as `GfxClear`.
|
||||
|
||||
ABI contracts and syscall declarations are part of the required update surface.
|
||||
They must not be left describing RGB565 values, `Gfx*565` names, or `u16`
|
||||
framebuffer/color contracts after this migration.
|
||||
|
||||
### Assets / Tooling
|
||||
|
||||
`assets.pa`, glyph-bank palette decode, generators, fixtures, and validators
|
||||
must use RGBA8888 palette entries. Compatibility with existing RGB565 palette
|
||||
assets is intentionally not preserved.
|
||||
|
||||
### Tests
|
||||
|
||||
Tests must be rewritten around RGBA8888 values, RGBA channel order, broad alpha
|
||||
support, meaningful front-buffer alpha, asset palette RGBA8888 encoding, and
|
||||
host presentation without RGB565 conversion.
|
||||
|
||||
Visual/snapshot tests should assert intended RGBA8888 composition behavior, not
|
||||
binary equivalence with legacy RGB565 output.
|
||||
|
||||
## Propagacao Necessaria
|
||||
|
||||
- specs: GFX peripheral, asset package/glyph-bank palette format, VM/syscall
|
||||
ABI, host presentation where documented.
|
||||
- plans: a dedicated execution plan must be written before spec or code edits.
|
||||
- code: `prometeu-hal`, `prometeu-drivers`, `prometeu-system`,
|
||||
`prometeu-host-desktop-winit`, asset tooling, fixtures.
|
||||
- tests: HAL color tests, renderer tests, asset decode tests, VM/syscall tests,
|
||||
host conversion/presentation tests, visual or snapshot tests where available.
|
||||
- docs: discussion lessons only after execution is complete.
|
||||
- canonical docs: specs, ABI contracts, and public documentation must be updated
|
||||
in the same execution plan as the code/spec migration, not deferred as
|
||||
optional cleanup.
|
||||
|
||||
## Referencias
|
||||
|
||||
- Agenda: AGD-0037
|
||||
- Prior agenda superseded for this topic: AGD-0010
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-05-23: Initial decision draft from AGD-0037.
|
||||
Reference in New Issue
Block a user