109 lines
4.8 KiB
Markdown
109 lines
4.8 KiB
Markdown
---
|
|
id: LSN-0053
|
|
ticket: studio-packer-rgba8888-asset-pipeline
|
|
title: RGBA8888 Is the Canonical Studio and Packer Palette Contract
|
|
created: 2026-07-14
|
|
tags:
|
|
- studio
|
|
- packer
|
|
- assets
|
|
- glyph-bank
|
|
- palette
|
|
- rgba8888
|
|
- runtime-alignment
|
|
---
|
|
|
|
# RGBA8888 Is the Canonical Studio and Packer Palette Contract
|
|
|
|
### Original Problem
|
|
|
|
The runtime moved to RGBA8888 as the canonical logical color and framebuffer
|
|
format, but Studio and packer still treated glyph-bank palettes as RGB565-era
|
|
data. The old pipeline exposed `convertedRgb565`, preserved ARGB as normal
|
|
projected metadata, reserved palette index `0` for transparency, flattened or
|
|
discarded alpha semantics, and carried magenta color-key behavior as a hidden
|
|
transparency shortcut.
|
|
|
|
That made the asset pipeline ambiguous. A glyph-bank asset could look valid to
|
|
Studio while still carrying palette data that no longer matched the runtime
|
|
contract.
|
|
|
|
### Consolidated Decision
|
|
|
|
`GLYPH/indexed_v1` remains the runtime-facing format name and keeps its
|
|
indexed/paletized glyph-bank identity. The incompatible change is inside the
|
|
palette contract:
|
|
|
|
1. `rgba8888` is the canonical authored, projected, and emitted palette field.
|
|
2. RGBA8888 values are interpreted as `0xRRGGBBAA` in runtime channel order.
|
|
3. Java `BufferedImage` ARGB values are input-only host API details and must be
|
|
converted deliberately at the packer boundary.
|
|
4. Palette index `0` is ordinary. Glyph palettes have 16 usable entries.
|
|
5. Transparency, including partial transparency, is represented only by alpha.
|
|
6. Magenta color-key behavior is not a normal Studio or packer feature.
|
|
7. RGB565 is not a compatibility path for runtime-facing glyph-bank palettes.
|
|
|
|
### Implementation Result
|
|
|
|
The packer specs now define glyph-bank palette metadata with `rgba8888`, and
|
|
the binary `GLYPH/indexed_v1` payload uses a `64 * 16 * 4 = 4096` byte palette
|
|
block instead of the old `64 * 16 * 2 = 2048` byte RGB565 block.
|
|
|
|
The packer palette model now carries canonical RGBA8888 values. Image import
|
|
converts Java ARGB pixels into runtime RGBA values before palette extraction,
|
|
and palette identity includes alpha. This allows transparent and partially
|
|
transparent colors to be distinct palette entries.
|
|
|
|
Packer read, detail, write, and cache paths now use `rgba8888` as the normal
|
|
metadata contract. Emission writes palette bytes in `R`, `G`, `B`, `A` order
|
|
and no longer emits a synthetic magenta entry for index `0`.
|
|
|
|
Tests and fixtures were updated to prove the new contract: RGBA channel order,
|
|
alpha preservation, 16 usable colors, index `0` as ordinary data, magenta as
|
|
ordinary color data, and 4096-byte palette blocks. Final validation confirmed
|
|
that remaining stale-looking references are either normative "not supported"
|
|
statements, historical discussion context, or explicitly out-of-scope generated
|
|
project cache data.
|
|
|
|
### Practical Pattern
|
|
|
|
When a host API exposes color in a different layout than the runtime contract,
|
|
name the boundary explicitly and keep the canonical field runtime-oriented.
|
|
For this pipeline:
|
|
|
|
- accept host ARGB only at import/read time;
|
|
- convert to RGBA8888 before storing palette metadata;
|
|
- project `rgba8888` to Studio and packer clients;
|
|
- emit RGBA bytes directly into `assets.pa`;
|
|
- convert back to UI-friendly ARGB only inside presentation code.
|
|
|
|
This keeps tooling convenient without letting host representation leak into the
|
|
runtime asset contract.
|
|
|
|
### Common Pitfalls and Anti-patterns
|
|
|
|
- Do not treat `originalArgb8888` as canonical pipeline data. ARGB can be a UI
|
|
or image-input representation, but `rgba8888` owns the contract.
|
|
- Do not reintroduce `convertedRgb565` as a normal projected field or emitted
|
|
payload. RGB565 compatibility was deliberately rejected for this path.
|
|
- Do not reserve palette index `0` for transparency. Alpha owns transparency.
|
|
- Do not use magenta as a hidden color key. A magenta RGBA value is just color
|
|
data unless an explicit future import tool defines a separate conversion.
|
|
- Do not change scene `palette_id` semantics as part of color-format work.
|
|
Scene records still reference glyph-bank palette indices.
|
|
- Do not fold `DSC-0005` variable palette-count work into RGBA8888 cleanup.
|
|
Palette encoding changed here; palette-count optimization remains separate.
|
|
|
|
### References
|
|
|
|
- `DEC-0037`: Studio and Packer RGBA8888 Asset Pipeline Contract.
|
|
- `PLN-0081`: Packer and Studio spec propagation.
|
|
- `PLN-0082`: Palette model and ARGB conversion boundary.
|
|
- `PLN-0083`: Glyph payload emission and size accounting.
|
|
- `PLN-0084`: Packer projections and workspace APIs.
|
|
- `PLN-0085`: Tests, fixtures, and conformance updates.
|
|
- `PLN-0086`: Final integration and residue removal.
|
|
- `docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md`.
|
|
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`.
|
|
- `docs/specs/studio/4. Assets Workspace Specification.md`.
|