204 lines
8.6 KiB
Markdown
204 lines
8.6 KiB
Markdown
---
|
|
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.
|