229 lines
9.0 KiB
Markdown
229 lines
9.0 KiB
Markdown
---
|
|
id: DEC-0037
|
|
ticket: studio-packer-rgba8888-asset-pipeline
|
|
title: Studio and Packer RGBA8888 Asset Pipeline Contract
|
|
status: accepted
|
|
created: 2026-05-23
|
|
accepted: 2026-05-23
|
|
ref_agenda: AGD-0041
|
|
plans:
|
|
- PLN-0081
|
|
- PLN-0082
|
|
- PLN-0083
|
|
- PLN-0084
|
|
- PLN-0085
|
|
- PLN-0086
|
|
tags:
|
|
- studio
|
|
- packer
|
|
- assets
|
|
- glyph-bank
|
|
- palette
|
|
- rgba8888
|
|
- runtime-alignment
|
|
---
|
|
|
|
## Status
|
|
|
|
Accepted. Drafted from accepted agenda `AGD-0041` and accepted on
|
|
2026-05-23.
|
|
|
|
## Context
|
|
|
|
Runtime `DEC-0029` makes RGBA8888 the canonical logical color representation
|
|
and physical framebuffer format for Prometeu. It also requires asset package
|
|
palettes to use RGBA8888, rejects RGB565 compatibility as normal runtime input,
|
|
and defines transparency through alpha rather than a reserved palette index.
|
|
|
|
Studio embeds the packer and owns the asset authoring and publication pipeline
|
|
that emits `assets.pa`. Before this decision, the Studio/packer glyph-bank path
|
|
still carried RGB565 assumptions:
|
|
|
|
- `GLYPH/indexed_v1` palette payloads were specified as fixed
|
|
`64 * 16 * 2` RGB565 `u16` values.
|
|
- `PackerPaletteV1` exposed `originalArgb8888` and `convertedRgb565`.
|
|
- `PackerGlyphBankWalker` flattened partial alpha, treated alpha zero and
|
|
magenta as transparent index `0`, limited authored colors to 15 usable
|
|
entries, and converted colors to RGB565.
|
|
- Studio/packer read projections, details APIs, fixtures, and sample assets
|
|
exposed `convertedRgb565` as ordinary pipeline data.
|
|
|
|
The runtime decision is already normative for the color contract. This decision
|
|
locks how Studio and packer align their glyph-bank asset pipeline with it.
|
|
|
|
## Decision
|
|
|
|
Studio and packer SHALL keep the runtime-facing glyph payload format name
|
|
`GLYPH/indexed_v1`.
|
|
|
|
The `GLYPH/indexed_v1` glyph-bank model SHALL remain indexed/paletized. Indexed
|
|
pixel payloads, fixed emitted sheet shape, scene `palette_id` references, and
|
|
the broad glyph-bank identity remain stable.
|
|
|
|
The structural change is the palette contract. `GLYPH/indexed_v1` palette data
|
|
MUST move from RGB565-derived values to RGBA8888 values in runtime RGBA channel
|
|
order.
|
|
|
|
Packer output, packer metadata, Studio read/detail projections, tests, and
|
|
fixtures MUST stop treating RGB565 as the normal palette representation.
|
|
`convertedRgb565` MUST be removed from the normal authored and projected
|
|
palette contract.
|
|
|
|
The canonical authored/projected palette field for this wave SHALL be
|
|
`rgba8888`.
|
|
|
|
Java `BufferedImage` and PNG inputs MAY be read as ARGB by host APIs, but ARGB
|
|
is only an input representation. The packer boundary MUST convert ARGB input to
|
|
runtime RGBA8888 output deliberately before emitting or projecting canonical
|
|
palette data.
|
|
|
|
Palette index `0` MUST be an ordinary palette index. Glyph palettes SHALL have
|
|
16 usable entries, not 15 usable entries plus a reserved transparent index.
|
|
|
|
Transparency and partial transparency MUST be represented only by the alpha
|
|
channel in the RGBA8888 palette value.
|
|
|
|
Magenta color-key behavior MUST be removed completely from the normal Studio
|
|
and packer asset pipeline. Magenta MUST NOT remain a hidden compatibility rule,
|
|
normal authoring shortcut, or runtime-facing transparency encoding.
|
|
|
|
Partial alpha in PNG/glyph inputs SHALL be valid palette data. Packer behavior
|
|
that warns about, flattens, rejects, or otherwise strips partial alpha MUST be
|
|
removed or rewritten around the RGBA8888 palette contract.
|
|
|
|
The fixed 64-palette serialization model remains in scope for this wave unless
|
|
another accepted decision explicitly revises it. `DSC-0005` remains a later
|
|
palette-count serialization discussion and MUST NOT be folded into this
|
|
RGBA8888 migration by implication.
|
|
|
|
Existing `main` and `fragments` sample project assets may be regenerated
|
|
manually later. Their regeneration is not a blocker for this decision and MUST
|
|
NOT justify preserving RGB565 compatibility in the packer.
|
|
|
|
## Rationale
|
|
|
|
Keeping `GLYPH/indexed_v1` avoids renaming a format whose core identity remains
|
|
the same: indexed glyph pixels resolved through palettes. The incompatible part
|
|
is specifically the palette encoding and transparency semantics.
|
|
|
|
Making RGBA8888 the normal packer-side representation aligns Studio with
|
|
runtime `DEC-0029` without introducing a parallel RGB565 compatibility path.
|
|
This keeps the asset pipeline direct: authoring input is normalized once at the
|
|
packer boundary, and emitted runtime artifacts carry the runtime color contract.
|
|
|
|
Treating index `0` as ordinary is required because transparency now belongs to
|
|
the alpha channel. This also gives each glyph palette the full 16 authored
|
|
entries available from the indexed payload.
|
|
|
|
Removing magenta color-key behavior avoids a second transparency mechanism that
|
|
would conflict with meaningful alpha. Allowing partial alpha preserves source
|
|
image information and supports the broader RGBA8888 renderer direction.
|
|
|
|
Keeping fixed 64-palette serialization separates mandatory color-format
|
|
migration from later payload-size optimization. Palette count and sparse/dense
|
|
serialization remain independent questions.
|
|
|
|
## Technical Specification
|
|
|
|
### Runtime-Facing Glyph Payload
|
|
|
|
- The format name remains `GLYPH/indexed_v1`.
|
|
- The indexed pixel plane remains packed `u4`.
|
|
- The emitted glyph-bank sheet shape remains unchanged for this wave.
|
|
- The palette block changes from 2-byte RGB565 entries to 4-byte RGBA8888
|
|
entries.
|
|
- The fixed palette block remains `64 * 16` entries for this wave.
|
|
- The byte-size formula for the palette block MUST be updated from
|
|
`64 * 16 * 2` to `64 * 16 * 4`.
|
|
- Size and decoded-size formulas for glyph-bank payloads MUST be updated
|
|
accordingly.
|
|
- Palette bytes MUST be interpreted as runtime RGBA channel order.
|
|
|
|
### Authored and Projected Palette Data
|
|
|
|
- Canonical palette data exposed by Studio/packer SHALL use `rgba8888`.
|
|
- `convertedRgb565` SHALL be removed from normal authored pipeline metadata,
|
|
details projections, read projections, fixtures, and tests.
|
|
- `originalArgb8888` SHALL NOT be the canonical field for runtime-facing or
|
|
packer-projected palette data in this wave.
|
|
- ARGB values read from Java image APIs MUST be converted to RGBA8888 before
|
|
entering canonical packer metadata or emitted payloads.
|
|
|
|
### Transparency and Alpha
|
|
|
|
- Palette index `0` is ordinary.
|
|
- A glyph palette has 16 usable entries.
|
|
- Alpha `0`, alpha between `1` and `254`, and alpha `255` are all valid
|
|
palette-entry states.
|
|
- Partial alpha MUST be preserved as data.
|
|
- Packer warnings or validations that describe partial alpha as flattened,
|
|
ignored, or unsupported MUST be removed.
|
|
- Color limit validation MUST be rewritten for 16 usable palette entries.
|
|
|
|
### Removed Behaviors
|
|
|
|
- RGB565 palette emission is not a normal packer output.
|
|
- RGB565 palette projection is not a normal Studio/packer read or details
|
|
contract.
|
|
- Magenta color-key transparency is not supported in the normal path.
|
|
- Palette index `0` is not reserved for transparency.
|
|
- Runtime asset compatibility with stale RGB565 palette payloads is not a
|
|
Studio/packer requirement for this wave.
|
|
|
|
## Propagation Targets
|
|
|
|
### Specs
|
|
|
|
- `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`, if Studio-facing
|
|
palette read/projection behavior is documented there.
|
|
|
|
### Code
|
|
|
|
- `prometeu-packer` palette model types.
|
|
- `PackerGlyphBankWalker`.
|
|
- `PackerAssetWalker` glyph-bank size and metadata calculations.
|
|
- `PackerAssetDetailsService`.
|
|
- `PackerReadMessageMapper`.
|
|
- Any packer serializer/materializer that emits `assets.pa` glyph payloads.
|
|
- Studio asset workspace read/detail surfaces that display or depend on
|
|
palette metadata.
|
|
|
|
### Tests and Fixtures
|
|
|
|
- Packer glyph-bank walker tests.
|
|
- Asset declaration parser tests that mention `convertedRgb565`.
|
|
- Runtime asset materializer tests.
|
|
- File-system workspace service tests.
|
|
- Fixture `asset.json` files that still declare RGB565-derived palette data.
|
|
- Test expectations for alpha, 16 usable colors, and removed magenta color-key
|
|
behavior.
|
|
|
|
`main` and `fragments` project assets are expected to be regenerated manually
|
|
later and are not blockers for this decision.
|
|
|
|
## Constraints
|
|
|
|
- This decision MUST NOT introduce an RGB565 compatibility mode.
|
|
- This decision MUST NOT rename the runtime-facing format away from
|
|
`GLYPH/indexed_v1`.
|
|
- This decision MUST NOT change scene `palette_id` semantics except as needed
|
|
to ensure referenced glyph palettes now resolve RGBA8888 entries.
|
|
- This decision MUST NOT decide variable palette-count serialization.
|
|
- This decision MUST NOT close or revise `DSC-0005`; that discussion remains a
|
|
later palette-count optimization track.
|
|
- Any implementation plan derived from this decision MUST preserve all
|
|
normative requirements above unless the user explicitly requests a decision
|
|
revision.
|
|
|
|
## References
|
|
|
|
- Agenda: `AGD-0041`
|
|
- Runtime decision: `../runtime/discussion/workflow/decisions/DEC-0029-rgba8888-runtime-pixel-format-contract.md`
|
|
- Related future discussion: `DSC-0005`
|
|
|
|
## Revision Log
|
|
|
|
- 2026-05-23: Initial accepted decision from `AGD-0041`.
|