RGBA8888 Framebuffer and Pixel Format Direction
This commit is contained in:
@@ -0,0 +1,106 @@
|
||||
---
|
||||
id: PLN-0067
|
||||
ticket: rgba8888-framebuffer-and-pixel-format-direction
|
||||
title: RGBA8888 Published Contracts and Specs
|
||||
status: open
|
||||
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.
|
||||
@@ -0,0 +1,118 @@
|
||||
---
|
||||
id: PLN-0068
|
||||
ticket: rgba8888-framebuffer-and-pixel-format-direction
|
||||
title: RGBA8888 Color Type HAL and ABI Surface
|
||||
status: open
|
||||
created: 2026-05-23
|
||||
ref_decisions: [DEC-0029]
|
||||
tags: [gfx, framebuffer, rgb565, rgba8888, renderer, assets, host, backend]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Introduce the RGBA8888 logical color contract and format-neutral HAL/ABI
|
||||
surface while keeping renderer internals as stable as possible for the next
|
||||
plan. This is the boundary-setting code PR after the specs are updated.
|
||||
|
||||
## Source Decisions
|
||||
|
||||
- DEC-0029 - RGBA8888 Runtime Pixel Format Contract.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- PLN-0067 must be accepted or complete enough that the target spec wording is
|
||||
stable.
|
||||
|
||||
## Target
|
||||
|
||||
The public runtime color type, syscall registry, ABI metadata, and HAL bridge
|
||||
must stop exposing RGB565 as the canonical contract. Public names must be
|
||||
format-neutral.
|
||||
|
||||
## Scope
|
||||
|
||||
Included:
|
||||
|
||||
- Replace `prometeu_hal::color::Color(pub u16)` semantics with RGBA8888 in
|
||||
`crates/console/prometeu-hal/src/color.rs`.
|
||||
- Define constructors and raw accessors for RGBA channel order.
|
||||
- Preserve ergonomic named constants as RGBA8888 values.
|
||||
- Replace `Syscall::GfxClear565` with format-neutral `Syscall::GfxClear`.
|
||||
- Update syscall registry/domain metadata in
|
||||
`crates/console/prometeu-hal/src/syscalls.rs`,
|
||||
`crates/console/prometeu-hal/src/syscalls/registry.rs`, and
|
||||
`crates/console/prometeu-hal/src/syscalls/domains/gfx.rs`.
|
||||
- Update VM dispatch color parsing and validation in
|
||||
`crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`.
|
||||
- Update ABI/opcode documentation surfaces in
|
||||
`crates/console/prometeu-bytecode/src/abi.rs` and
|
||||
`crates/console/prometeu-bytecode/src/opcode_spec.rs` if they expose the
|
||||
syscall name or raw color range.
|
||||
- Change `GfxBridge::front_buffer` only if needed to compile the public API
|
||||
shape; full renderer buffer migration belongs to PLN-0069.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Migrating renderer front/back storage.
|
||||
- Migrating asset palette serialization.
|
||||
- Removing host RGB565 conversion.
|
||||
- Performance optimization for alpha or RGBA operations.
|
||||
- Adding alpha-only commands.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Rewrite `Color` as RGBA8888.
|
||||
- Store raw color as `u32` or an equivalent transparent representation.
|
||||
- `Color::rgb(r, g, b)` must create opaque alpha `255`.
|
||||
- Add or update `Color::rgba(r, g, b, a)`.
|
||||
- `raw()` and `from_raw()` must use RGBA channel order.
|
||||
- Remove or quarantine RGB565 helpers such as 5/6/5 pack/unpack from the
|
||||
canonical API.
|
||||
|
||||
2. Remove format-suffixed GFX syscall naming.
|
||||
- Rename `GfxClear565` to `GfxClear`.
|
||||
- Rename the domain metadata from `clear_565` to `clear`.
|
||||
- Keep the numeric syscall id stable only if the ABI policy allows preserving
|
||||
the opcode while changing the name/semantics; otherwise document the new
|
||||
id in the spec before changing it.
|
||||
- Search for any other `Gfx*565` public surface and rename it to
|
||||
format-neutral form.
|
||||
|
||||
3. Update VM color ABI handling.
|
||||
- Replace `0xFFFF` validation with the RGBA8888 range/shape.
|
||||
- Ensure the VM passes RGBA8888 raw values into `Color`.
|
||||
- Remove comments and test expectations that identify the GFX clear syscall
|
||||
as RGB565.
|
||||
|
||||
4. Update tests at the boundary.
|
||||
- HAL color tests must assert RGBA raw order.
|
||||
- Syscall metadata tests must assert `GfxClear`, not `GfxClear565`.
|
||||
- VM dispatch tests must use RGBA8888 values and meaningful alpha examples.
|
||||
|
||||
5. Run a targeted residue scan.
|
||||
- `rg -n "Gfx.*565|RGB565|rgb565|0xFFFF|Color\\(.*u16|front_buffer\\(\\).*u16" crates/console`.
|
||||
- Remaining hits must be either in lower layers scheduled for later plans or
|
||||
marked as temporary implementation residue.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `Color` represents RGBA8888 and exposes RGBA-order raw values.
|
||||
- [ ] `GfxClear565` is no longer a canonical syscall/API name; `GfxClear` is.
|
||||
- [ ] No public `Gfx*565` surface remains in HAL/syscall metadata.
|
||||
- [ ] VM color validation accepts RGBA8888 and does not enforce RGB565 range.
|
||||
- [ ] Boundary tests are RGBA8888-first.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Run the HAL/syscall unit tests touched by this plan.
|
||||
- Run VM dispatch tests that cover GFX clear/color values.
|
||||
- Run `cargo test` for the affected crates if compile scope remains contained.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Risks
|
||||
|
||||
- Renaming syscall variants may have wide compile fallout. Keep the PR focused
|
||||
on boundary names and color semantics, leaving renderer internals for the next
|
||||
plan.
|
||||
- If opcode ids are part of a stable ABI, changing numeric ids requires a
|
||||
separate explicit spec change before implementation.
|
||||
@@ -0,0 +1,109 @@
|
||||
---
|
||||
id: PLN-0069
|
||||
ticket: rgba8888-framebuffer-and-pixel-format-direction
|
||||
title: RGBA8888 CPU Renderer and Composition
|
||||
status: open
|
||||
created: 2026-05-23
|
||||
ref_decisions: [DEC-0029]
|
||||
tags: [gfx, framebuffer, rgb565, rgba8888, renderer, assets, host, backend]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Migrate the existing CPU renderer and frame composition path from RGB565
|
||||
storage to RGBA8888 storage. This plan keeps the current destructive renderer
|
||||
model and does not introduce a render thread or backend abstraction.
|
||||
|
||||
## Source Decisions
|
||||
|
||||
- DEC-0029 - RGBA8888 Runtime Pixel Format Contract.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- PLN-0067 for published contract wording.
|
||||
- PLN-0068 for `Color`, HAL, and syscall boundary semantics.
|
||||
|
||||
## Target
|
||||
|
||||
The renderer front/back buffers, render target writes, fades, blends, text,
|
||||
tiles, sprites, and frame composer tests must operate on RGBA8888 pixels.
|
||||
|
||||
## Scope
|
||||
|
||||
Included:
|
||||
|
||||
- `crates/console/prometeu-drivers/src/gfx.rs`.
|
||||
- `crates/console/prometeu-drivers/src/frame_composer.rs`.
|
||||
- `crates/console/prometeu-drivers/src/hardware.rs` where framebuffer/color
|
||||
assumptions are tested or documented.
|
||||
- HAL bridge implementation in drivers if it still returns `&[u16]`.
|
||||
- Renderer unit tests and frame-composer tests that assert raw pixel values.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Asset package palette serialization changes; covered by PLN-0070.
|
||||
- Host presentation conversion removal; covered by PLN-0071.
|
||||
- GPU backend, render thread, dirty-region optimization, span optimization, or
|
||||
multi-format backend abstraction.
|
||||
- Alpha-only commands.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Change renderer storage to RGBA8888.
|
||||
- Replace `front: Vec<u16>` and `back: Vec<u16>` with RGBA8888 storage.
|
||||
- Update `RenderTarget` and all buffer accessors to the new pixel type.
|
||||
- Ensure `present()` keeps its swap semantics.
|
||||
|
||||
2. Update primitive writes.
|
||||
- `clear`, `draw_pixel`, `fill_rect`, `draw_text`, hardware font drawing,
|
||||
and overlay primitives must write RGBA8888 values.
|
||||
- Opaque calls may write direct RGBA8888 pixels.
|
||||
- Alpha values must be preserved according to the operation semantics.
|
||||
|
||||
3. Replace RGB565 blending/fade.
|
||||
- Replace `blend_rgb565` with RGBA8888 blend logic.
|
||||
- Update `apply_fade_to_buffer` to operate on RGBA channels.
|
||||
- Do not force final alpha to `255`; preserve or compute alpha according to
|
||||
the operation.
|
||||
|
||||
4. Update tile and sprite composition.
|
||||
- Resolve palette entries as RGBA8888 colors.
|
||||
- Do not treat palette index `0` as automatically transparent.
|
||||
- Skip or blend based on resolved alpha and operation semantics.
|
||||
- Allow alpha across tile, sprite, primitive, UI/effect, and fade paths.
|
||||
|
||||
5. Update frame composer expectations.
|
||||
- Tests must assert RGBA8888 raw values.
|
||||
- Any old RGB565 expected values must be regenerated from RGBA source colors,
|
||||
not converted as compatibility behavior.
|
||||
|
||||
6. Isolate temporary compile seams.
|
||||
- If asset decode still supplies RGBA8888 `Color` through old fixture bytes,
|
||||
keep the fixture problem contained for PLN-0070 and do not add runtime
|
||||
RGB565 compatibility to the renderer.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Renderer front/back buffers materialize RGBA8888 pixels.
|
||||
- [ ] `front_buffer()` no longer exposes `&[u16]` in the driver/HAL
|
||||
implementation path.
|
||||
- [ ] RGB565 blend/fade helpers are removed from renderer normal paths.
|
||||
- [ ] Tile/sprite transparency is based on RGBA alpha, not palette index `0`.
|
||||
- [ ] Renderer and frame-composer tests assert RGBA8888 values.
|
||||
- [ ] No render thread, GPU backend, RGB565 backend, or multi-format backend is
|
||||
introduced.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Run renderer unit tests in `prometeu-drivers`.
|
||||
- Run frame composer tests in `prometeu-drivers`.
|
||||
- Run targeted scans for `blend_rgb565`, `Vec<u16>`, `&[u16]`, and `RGB565` in
|
||||
renderer files.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Risks
|
||||
|
||||
- This plan will likely touch many assertions. Keep each assertion update tied
|
||||
to a known RGBA value.
|
||||
- Alpha behavior can expose previously hidden assumptions in tests. Preserve the
|
||||
decision rule: alpha is allowed broadly and optimization comes later.
|
||||
@@ -0,0 +1,114 @@
|
||||
---
|
||||
id: PLN-0070
|
||||
ticket: rgba8888-framebuffer-and-pixel-format-direction
|
||||
title: RGBA8888 Asset Palettes Tooling and Fixtures
|
||||
status: open
|
||||
created: 2026-05-23
|
||||
ref_decisions: [DEC-0029]
|
||||
tags: [gfx, framebuffer, rgb565, rgba8888, renderer, assets, host, backend]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Migrate asset palette serialization, decode, generators, and fixtures to
|
||||
RGBA8888. This plan intentionally breaks RGB565 palette compatibility rather
|
||||
than preserving it through runtime fallback.
|
||||
|
||||
## Source Decisions
|
||||
|
||||
- DEC-0029 - RGBA8888 Runtime Pixel Format Contract.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- PLN-0067 for asset spec wording.
|
||||
- PLN-0068 for RGBA8888 `Color`.
|
||||
- PLN-0069 may run before or alongside this plan, but renderer normal paths must
|
||||
not require RGB565 palette compatibility.
|
||||
|
||||
## Target
|
||||
|
||||
`assets.pa` glyph-bank palette payloads, runtime decode, generators, and tests
|
||||
must use RGBA8888 palette entries with RGBA channel order.
|
||||
|
||||
## Scope
|
||||
|
||||
Included:
|
||||
|
||||
- `crates/console/prometeu-hal/src/glyph_bank.rs`.
|
||||
- `crates/console/prometeu-hal/src/asset.rs`.
|
||||
- `crates/console/prometeu-hal/src/cartridge_loader.rs`.
|
||||
- `crates/console/prometeu-drivers/src/asset.rs`.
|
||||
- `crates/tools/pbxgen-stress/src/lib.rs` and related generator code.
|
||||
- Runtime and system tests that compute glyph-bank payload sizes.
|
||||
- Test fixtures and generated `assets.pa` payload builders in the repository.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Supporting legacy RGB565 assets at runtime.
|
||||
- Adding a general asset package v2 negotiation layer unless the existing format
|
||||
requires an explicit version bump to avoid ambiguous decode.
|
||||
- Changing tile/sprite index packing beyond what RGBA8888 palettes require.
|
||||
- Changing palette count or colors-per-palette limits.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Change palette byte accounting.
|
||||
- Replace palette entry size from `size_of::<u16>()` / `2` bytes to `4`
|
||||
bytes.
|
||||
- Update decoded-size calculations in asset decode, cartridge loader tests,
|
||||
VM runtime tests, and pbxgen-stress.
|
||||
|
||||
2. Decode palettes as RGBA8888.
|
||||
- Read each palette entry as four bytes in RGBA order.
|
||||
- Construct `Color` through RGBA8888 APIs, not `Color(raw_u16)`.
|
||||
- Reject payloads whose palette byte size matches old RGB565 layout when the
|
||||
format can identify the mismatch.
|
||||
|
||||
3. Update glyph-bank semantics.
|
||||
- Keep `pixel_indices: Vec<u8>` and 4bpp authored payloads where currently
|
||||
specified.
|
||||
- Keep palette count and colors-per-palette constants unless the spec says
|
||||
otherwise.
|
||||
- Remove comments that say runtime palettes are RGB565.
|
||||
- Ensure palette index `0` is not treated as transparent by decode or data
|
||||
model.
|
||||
|
||||
4. Update generators and fixtures.
|
||||
- Make `pbxgen-stress` emit RGBA8888 palette bytes.
|
||||
- Regenerate inline fixture builders to append four-byte RGBA palette
|
||||
entries.
|
||||
- Do not keep RGB565 fixture decode as runtime compatibility.
|
||||
|
||||
5. Update asset tests.
|
||||
- Assert RGBA channel order.
|
||||
- Include at least one non-opaque alpha value in a palette entry.
|
||||
- Assert payload size failures for old two-byte palette layout where
|
||||
practical.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Glyph-bank palette payloads are RGBA8888 and use four bytes per entry.
|
||||
- [ ] Asset decode constructs RGBA8888 `Color` values in RGBA order.
|
||||
- [ ] Existing RGB565 palette payloads are not accepted as compatible runtime
|
||||
input.
|
||||
- [ ] `pbxgen-stress` emits RGBA8888 palettes.
|
||||
- [ ] Tests include meaningful alpha in palette entries.
|
||||
- [ ] Palette index `0` has no special transparency semantics in asset decode.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Run asset decode tests in `prometeu-drivers`.
|
||||
- Run cartridge loader tests in `prometeu-hal`.
|
||||
- Run VM runtime asset tests in `prometeu-system`.
|
||||
- Run `cargo test -p pbxgen-stress` if available.
|
||||
- Run scans for `GLYPH_BANK_PALETTE.*u16`, `* 2`, `size_of::<u16>()`, and
|
||||
`RGB565` in asset/glyph-bank/tooling files.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Risks
|
||||
|
||||
- Payload-size constants are duplicated in tests. Update all derived size
|
||||
helpers in the same PR to avoid misleading failures.
|
||||
- If the existing asset package has no version marker for palette encoding, the
|
||||
plan must choose an explicit metadata/version discriminator before accepting
|
||||
ambiguous payloads.
|
||||
@@ -0,0 +1,103 @@
|
||||
---
|
||||
id: PLN-0071
|
||||
ticket: rgba8888-framebuffer-and-pixel-format-direction
|
||||
title: RGBA8888 Host Presentation Path
|
||||
status: open
|
||||
created: 2026-05-23
|
||||
ref_decisions: [DEC-0029]
|
||||
tags: [gfx, framebuffer, rgb565, rgba8888, renderer, assets, host, backend]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Move the desktop host presentation path from RGB565 conversion to direct
|
||||
RGBA8888 presentation. This plan removes the normal `draw_rgb565_to_rgba8`
|
||||
path after the runtime publishes RGBA8888 frames.
|
||||
|
||||
## Source Decisions
|
||||
|
||||
- DEC-0029 - RGBA8888 Runtime Pixel Format Contract.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- PLN-0067 for host/spec contract wording.
|
||||
- PLN-0068 for public framebuffer type and ABI naming.
|
||||
- PLN-0069 for renderer front-buffer RGBA8888 storage.
|
||||
|
||||
## Target
|
||||
|
||||
The host must consume RGBA8888 frames directly in the normal presentation path
|
||||
and must not convert RGB565 frames on every redraw.
|
||||
|
||||
## Scope
|
||||
|
||||
Included:
|
||||
|
||||
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`.
|
||||
- `crates/host/prometeu-host-desktop-winit/src/utilities.rs`.
|
||||
- Host tests or utility tests for frame copy/channel order.
|
||||
- Host overlay integration where it assumes RGBA8 frame bytes.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Changing the windowing library.
|
||||
- Introducing wgpu/OpenGL/SDL backend abstractions.
|
||||
- Changing host frame pacing.
|
||||
- Changing render thread ownership.
|
||||
- Performance optimization beyond removing RGB565 conversion from the normal
|
||||
path.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Replace host frame conversion.
|
||||
- Remove use of `draw_rgb565_to_rgba8` from `runner.rs`.
|
||||
- Copy or expose RGBA8888 runtime pixels into the `pixels` frame using the
|
||||
documented RGBA channel order.
|
||||
- Preserve meaningful alpha unless the presentation library explicitly
|
||||
requires conversion; if conversion is required, document it as host
|
||||
presentation behavior, not runtime framebuffer semantics.
|
||||
|
||||
2. Remove RGB565 utilities from the normal path.
|
||||
- Delete `draw_rgb565_to_rgba8` and `rgb565_to_rgb888` if no tests or
|
||||
temporary migration tools need them.
|
||||
- If temporary conversion helpers remain for fixture regeneration, move them
|
||||
out of host presentation utilities and mark them non-runtime.
|
||||
|
||||
3. Verify overlay compatibility.
|
||||
- Ensure host overlay writes still target RGBA8 bytes in the `pixels` frame.
|
||||
- Ensure overlay composition does not assume the emulated framebuffer itself
|
||||
is opaque.
|
||||
|
||||
4. Update host tests.
|
||||
- Add or update tests for RGBA channel order.
|
||||
- Include a source pixel with non-`255` alpha.
|
||||
- Remove tests that only prove RGB565 expansion.
|
||||
|
||||
5. Run residue scan.
|
||||
- Search host crate for `rgb565`, `RGB565`, `draw_rgb565`, and `u16`
|
||||
framebuffer assumptions.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] The desktop host normal redraw path consumes RGBA8888 frames.
|
||||
- [ ] `draw_rgb565_to_rgba8` is not used by host presentation.
|
||||
- [ ] Host channel order matches canonical RGBA.
|
||||
- [ ] Host presentation does not force runtime front-buffer alpha to `255` as a
|
||||
runtime contract.
|
||||
- [ ] Host tests are RGBA8888-first.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Run `cargo test -p prometeu-host-desktop-winit`.
|
||||
- Run a targeted host scan for `rgb565`, `RGB565`, and `draw_rgb565`.
|
||||
- Run an interactive smoke test only if the repo already has a standard host
|
||||
smoke command; otherwise record that manual visual validation remains for the
|
||||
final validation plan.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Risks
|
||||
|
||||
- The `pixels` frame is byte-oriented; byte order mistakes are easy. Tests must
|
||||
use non-symmetric color values and non-opaque alpha.
|
||||
- If runtime publishes `u32`, host code must explicitly define how the `u32`
|
||||
maps to RGBA bytes instead of relying on native endian layout.
|
||||
+109
@@ -0,0 +1,109 @@
|
||||
---
|
||||
id: PLN-0072
|
||||
ticket: rgba8888-framebuffer-and-pixel-format-direction
|
||||
title: RGBA8888 Residue Removal and End to End Validation
|
||||
status: open
|
||||
created: 2026-05-23
|
||||
ref_decisions: [DEC-0029]
|
||||
tags: [gfx, framebuffer, rgb565, rgba8888, renderer, assets, host, backend]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Close the RGBA8888 migration by removing residual RGB565 contract text and code
|
||||
paths, running end-to-end validation, and preparing the discussion thread for
|
||||
post-execution lessons.
|
||||
|
||||
## Source Decisions
|
||||
|
||||
- DEC-0029 - RGBA8888 Runtime Pixel Format Contract.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- PLN-0067 through PLN-0071 must be complete or merged into the execution branch.
|
||||
|
||||
## Target
|
||||
|
||||
The repository must no longer expose RGB565, `Gfx*565`, `u16` framebuffer/color
|
||||
contracts, RGB565 palette payloads, or RGB565 host conversion as active runtime
|
||||
contract.
|
||||
|
||||
## Scope
|
||||
|
||||
Included:
|
||||
|
||||
- Whole-repository residue audit.
|
||||
- End-to-end build and test validation.
|
||||
- Documentation consistency checks.
|
||||
- Final migration notes needed for housekeeping and lessons.
|
||||
- Any small missed cleanup in code, docs, tests, or fixtures that directly
|
||||
violates DEC-0029.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- New alpha-only commands.
|
||||
- Performance optimization after broad alpha support.
|
||||
- GPU backend, render thread, RGB565 backend, multi-format backend abstraction.
|
||||
- New visual design work for the Hub.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Run repository-wide residue scans.
|
||||
- Search for `RGB565`, `rgb565`, `Gfx.*565`, `clear_565`, `u16` near color
|
||||
or framebuffer APIs, `GLYPH_BANK_PALETTE.*u16`, `size_of::<u16>()` near
|
||||
palette code, `draw_rgb565`, and `0xFFFF` near color validation.
|
||||
- Classify every remaining hit as removed, historical-only, unrelated, or a
|
||||
bug.
|
||||
|
||||
2. Remove active-contract residues.
|
||||
- Delete or rename any remaining active `Gfx*565` surface.
|
||||
- Remove RGB565 helpers from runtime and host normal paths.
|
||||
- Remove comments that still describe RGB565 as current behavior.
|
||||
- Remove tests that assert RGB565 output.
|
||||
|
||||
3. Verify docs and ABI consistency.
|
||||
- Ensure `docs/specs/runtime/04-gfx-peripheral.md`,
|
||||
`docs/specs/runtime/15-asset-management.md`, and
|
||||
`docs/specs/runtime/16-host-abi-and-syscalls.md` agree on RGBA8888.
|
||||
- Ensure public syscall declarations and docs use format-neutral names.
|
||||
- Ensure any historical RGB565 mention is clearly historical and not
|
||||
normative.
|
||||
|
||||
4. Run full test/build validation.
|
||||
- Run the repo's standard build command.
|
||||
- Run the relevant Rust test suites across HAL, drivers, system, VM, tools,
|
||||
and host.
|
||||
- Run any visual/snapshot validation available in the repository.
|
||||
|
||||
5. Record final evidence.
|
||||
- Capture the exact commands and outcomes in the plan or final PR notes.
|
||||
- List remaining historical RGB565 mentions and why they are acceptable.
|
||||
- Identify lesson candidates for `discussion-housekeep` after execution.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Repository scan finds no active RGB565 runtime contract.
|
||||
- [ ] No public `Gfx*565` API, syscall, metadata, or ABI declaration remains.
|
||||
- [ ] No normal renderer or host path performs RGB565 conversion.
|
||||
- [ ] No asset decode path accepts RGB565 palettes as compatible runtime input.
|
||||
- [ ] Specs, docs, ABI contracts, code, fixtures, and tests agree on RGBA8888.
|
||||
- [ ] Full validation commands pass or any failure is documented as unrelated.
|
||||
- [ ] The discussion thread has enough evidence for housekeeping and lessons.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Run the standard repository build command.
|
||||
- Run affected crate tests: `prometeu-hal`, `prometeu-drivers`,
|
||||
`prometeu-system`, `prometeu-vm`, `prometeu-bytecode`,
|
||||
`prometeu-host-desktop-winit`, and `pbxgen-stress` where applicable.
|
||||
- Run all available visual/snapshot tests.
|
||||
- Run repository-wide `rg` residue scans described above.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Risks
|
||||
|
||||
- Some remaining RGB565 references may be legitimate historical notes. They
|
||||
must be marked clearly enough that readers cannot mistake them for active
|
||||
contract.
|
||||
- End-to-end visual validation may not exist yet. If so, record the gap and add
|
||||
minimal deterministic checks around RGBA channel order and alpha behavior.
|
||||
Reference in New Issue
Block a user