146 lines
4.6 KiB
Markdown
146 lines
4.6 KiB
Markdown
---
|
|
id: PLN-0083
|
|
ticket: studio-packer-rgba8888-asset-pipeline
|
|
title: RGBA8888 Glyph Payload Emission and Size Accounting
|
|
status: done
|
|
created: 2026-05-23
|
|
completed: 2026-05-23
|
|
ref_decisions:
|
|
- DEC-0037
|
|
tags:
|
|
- packer
|
|
- assets-pa
|
|
- glyph-bank
|
|
- rgba8888
|
|
---
|
|
|
|
## Objective
|
|
|
|
Change packer glyph-bank runtime payload emission from RGB565 palette bytes to
|
|
RGBA8888 palette bytes while keeping `GLYPH/indexed_v1` and the fixed
|
|
64-palette model.
|
|
|
|
## Background
|
|
|
|
`DEC-0037` requires `GLYPH/indexed_v1` to retain its format name and indexed
|
|
model but emit RGBA8888 palette entries. Current payload emission in
|
|
`FileSystemPackerWorkspaceService` writes RGB565 bytes, reserves index `0`, and
|
|
uses color-key bytes.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
|
|
- Update glyph-bank payload palette byte emission.
|
|
- Update measured payload size and decoded-size accounting.
|
|
- Remove RGB565 palette constants and palette color-key bytes from emission.
|
|
- Keep scene `palette_id` payload semantics unchanged.
|
|
|
|
### Excluded
|
|
|
|
- Palette model extraction changes covered by `PLN-0082`.
|
|
- Read/detail projection changes covered by `PLN-0084`.
|
|
- Variable palette count.
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Update glyph payload constants and formulas
|
|
|
|
**What:** Change palette entry width from 2 bytes to 4 bytes.
|
|
|
|
**How:** Introduce clear constants for palette count, colors per palette, and
|
|
RGBA bytes per color. Use `64 * 16 * 4` for palette block size.
|
|
|
|
**File(s):**
|
|
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerAssetWalker.java`
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerRuntimeAssetMaterializer.java`
|
|
|
|
### Step 2 - Emit RGBA8888 palette bytes
|
|
|
|
**What:** Write each palette color as runtime RGBA channel bytes.
|
|
|
|
**How:** Replace RGB565 little-endian writes with four byte writes in `R`, `G`,
|
|
`B`, `A` order derived from the canonical `rgba8888` integer value.
|
|
|
|
**File(s):**
|
|
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
|
|
|
### Step 3 - Remove reserved color-key emission
|
|
|
|
**What:** Stop writing a synthetic color-key value at palette index `0`.
|
|
|
|
**How:** Remove `GLYPH_BANK_COLOR_KEY_RGB565` and any emission path that fills
|
|
index `0` with magenta. Emit declared RGBA values for index `0` like every
|
|
other index.
|
|
|
|
**File(s):**
|
|
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
|
|
|
### Step 4 - Update declared palette lookup
|
|
|
|
**What:** Read `rgba8888` from declared pipeline metadata.
|
|
|
|
**How:** Replace `originalArgb8888`/`convertedRgb565` lookup paths with
|
|
`rgba8888`. Ensure empty or malformed `rgba8888` is structural failure where
|
|
emission requires a palette.
|
|
|
|
**File(s):**
|
|
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerAssetWalker.java`
|
|
|
|
### Step 5 - Keep scene payload stable
|
|
|
|
**What:** Preserve scene `palette_id` layout.
|
|
|
|
**How:** Do not change `writeSceneBankPayload` except compile fixes caused by
|
|
shared helper changes. Scene tile records continue carrying `palette_id` as an
|
|
index into the referenced glyph palette.
|
|
|
|
**File(s):**
|
|
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
|
|
- Add or update tests asserting glyph payload size includes a 4096-byte palette
|
|
block.
|
|
- Assert emitted palette bytes for a known RGBA value, including alpha.
|
|
- Assert index `0` emits declared RGBA data, not magenta.
|
|
|
|
### Integration Tests
|
|
|
|
- Update workspace build tests that read `build/assets.pa` and assert glyph-bank
|
|
offsets/sizes.
|
|
|
|
### Manual Verification
|
|
|
|
- Search production packer code for `GLYPH_BANK_COLOR_KEY_RGB565`,
|
|
`convertedRgb565`, RGB565 palette byte writes, and hard-coded `2048`.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [x] Glyph payloads keep `GLYPH/indexed_v1`.
|
|
- [x] Glyph palette blocks are 4096 bytes.
|
|
- [x] Palette entries are emitted as RGBA bytes in runtime channel order.
|
|
- [x] No synthetic magenta/color-key value is emitted.
|
|
- [x] Size and decoded-size metadata match the new payload length.
|
|
- [x] Scene `palette_id` payload shape is unchanged.
|
|
|
|
## Dependencies
|
|
|
|
- Depends on `PLN-0082`.
|
|
- Should run before tests/fixture conformance in `PLN-0085`.
|
|
|
|
## Risks
|
|
|
|
- Updating size formulas without updating emitted bytes, or vice versa, will
|
|
corrupt payload slicing in `assets.pa`.
|
|
- Accidental scene payload edits could widen the change beyond `DEC-0037`.
|