prometeu-runtime/discussion/workflow/decisions/DEC-0029-rgba8888-runtime-pixel-format-contract.md

id	ticket	title	status	created	ref_agenda	tags
DEC-0029	rgba8888-framebuffer-and-pixel-format-direction	RGBA8888 Runtime Pixel Format Contract	accepted	2026-05-23	AGD-0037	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.