Variable Glyph Bank Palette Serialization
This commit is contained in:
+108
@@ -0,0 +1,108 @@
|
||||
---
|
||||
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`.
|
||||
Reference in New Issue
Block a user