145 lines
4.3 KiB
Markdown
145 lines
4.3 KiB
Markdown
---
|
|
id: PLN-0082
|
|
ticket: studio-packer-rgba8888-asset-pipeline
|
|
title: RGBA8888 Palette Model and ARGB Conversion
|
|
status: done
|
|
created: 2026-05-23
|
|
completed: 2026-05-23
|
|
ref_decisions:
|
|
- DEC-0037
|
|
tags:
|
|
- packer
|
|
- palette
|
|
- rgba8888
|
|
- conversion
|
|
---
|
|
|
|
## Objective
|
|
|
|
Replace the packer palette model with canonical RGBA8888 data and introduce a
|
|
single deliberate ARGB-to-RGBA conversion boundary for image inputs.
|
|
|
|
## Background
|
|
|
|
`PackerPaletteV1` currently stores `originalArgb8888` and `convertedRgb565`.
|
|
`PackerGlyphBankWalker` reads Java ARGB pixels, drops alpha semantics, reserves
|
|
index `0`, applies magenta color-key, and converts colors to RGB565.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
|
|
- Replace `PackerPaletteV1` fields with canonical `rgba8888`.
|
|
- Add or localize ARGB-to-RGBA conversion helpers.
|
|
- Preserve partial alpha.
|
|
- Remove RGB565 conversion from the normal palette model.
|
|
- Expand glyph palette extraction from 15 to 16 usable colors.
|
|
|
|
### Excluded
|
|
|
|
- Binary `assets.pa` emission changes.
|
|
- Read/detail API projection changes outside direct model compile fixes.
|
|
- Spec edits.
|
|
- Fixture regeneration for `main` and `fragments`.
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Replace the palette record
|
|
|
|
**What:** Change the packer palette model to carry canonical RGBA8888 values.
|
|
|
|
**How:** Replace `int[] originalArgb8888, short[] convertedRgb565` with
|
|
`int[] rgba8888`. Keep the record name only if it remains semantically useful;
|
|
otherwise rename only if all callers are updated in the same change.
|
|
|
|
**File(s):**
|
|
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/PackerPaletteV1.java`
|
|
|
|
### Step 2 - Convert ARGB image pixels to RGBA
|
|
|
|
**What:** Introduce one conversion path from Java `BufferedImage` ARGB to raw
|
|
runtime RGBA.
|
|
|
|
**How:** Convert `0xAARRGGBB` to `0xRRGGBBAA` when building palette entries.
|
|
Do not store ARGB in canonical packer metadata.
|
|
|
|
**File(s):**
|
|
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java`
|
|
|
|
### Step 3 - Remove magenta color-key and reserved index behavior
|
|
|
|
**What:** Stop treating alpha zero or magenta as special palette-index behavior.
|
|
|
|
**How:** Remove `COLOR_KEY_RGB`. Build palette identity from full RGBA8888
|
|
values, including alpha. Assign indices from `0` through `15`.
|
|
|
|
**File(s):**
|
|
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java`
|
|
|
|
### Step 4 - Preserve partial alpha
|
|
|
|
**What:** Remove partial-alpha warnings and flattening.
|
|
|
|
**How:** Delete the `partialAlphaFound` warning path. Ensure pixels with alpha
|
|
from `0` through `255` participate in palette extraction by full RGBA value.
|
|
|
|
**File(s):**
|
|
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java`
|
|
|
|
### Step 5 - Update color-limit validation
|
|
|
|
**What:** Change validation from 15 usable colors to 16 usable colors.
|
|
|
|
**How:** Replace `MAX_COLORS_PER_PALETTE = 15` with a 16-entry limit and update
|
|
diagnostic wording to remove `indices 1..15`.
|
|
|
|
**File(s):**
|
|
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerGlyphBankWalker.java`
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
|
|
- Update `PackerGlyphBankWalkerTest` to assert:
|
|
- 16 unique RGBA colors are valid.
|
|
- a 17th unique RGBA color is blocking.
|
|
- alpha `0`, partial alpha, and alpha `255` are preserved.
|
|
- magenta is treated as an ordinary color.
|
|
- palette index `0` can hold an ordinary color.
|
|
|
|
### Integration Tests
|
|
|
|
- None for this plan; binary emission is covered by a later plan.
|
|
|
|
### Manual Verification
|
|
|
|
- Search packer model and glyph walker sources for `convertedRgb565`,
|
|
`originalArgb8888`, `COLOR_KEY_RGB`, `convertToRgb565`, and partial-alpha
|
|
warning text.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [x] `PackerPaletteV1` exposes `rgba8888` and no RGB565 field.
|
|
- [x] `PackerGlyphBankWalker` stores canonical RGBA values.
|
|
- [x] Magenta is not special.
|
|
- [x] Alpha zero and partial alpha are valid palette data.
|
|
- [x] All 16 palette indices are usable.
|
|
- [x] Unit tests cover conversion and palette indexing semantics.
|
|
|
|
## Dependencies
|
|
|
|
- Depends on `PLN-0081` for spec wording.
|
|
- Must complete before payload emission and projection plans.
|
|
|
|
## Risks
|
|
|
|
- Confusing Java ARGB input with runtime RGBA output will create hard-to-debug
|
|
byte-order failures.
|
|
- Cache reuse may keep stale palette metadata if reusable metadata checks are
|
|
not updated with the model change.
|