diff --git a/docs/runtime/agendas/README.md b/docs/runtime/agendas/README.md index 50c745d0..95dec250 100644 --- a/docs/runtime/agendas/README.md +++ b/docs/runtime/agendas/README.md @@ -24,6 +24,7 @@ As agendas atuais são: - `020-perf-host-debug-overlay-isolation.md` - `021-perf-vm-allocation-and-copy-pressure.md` - `022-perf-cartridge-boot-and-program-ownership.md` +- `023-asset-codec-none-vs-raw.md` ## Sequenciamento Recomendado [PERF] Ordem sugerida para discussao das agendas de performance: diff --git a/docs/runtime/learn/mental-model-asset-management.md b/docs/runtime/learn/mental-model-asset-management.md index 1828520d..8d7710ff 100644 --- a/docs/runtime/learn/mental-model-asset-management.md +++ b/docs/runtime/learn/mental-model-asset-management.md @@ -5,6 +5,7 @@ Companion specs: - [`../specs/13-cartridge.md`](../specs/13-cartridge.md) - [`../specs/15-asset-management.md`](../specs/15-asset-management.md) +- [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md) Origin decision: [`../decisions/011-assets-pa-autocontained-runtime-contract.md`](../decisions/011-assets-pa-autocontained-runtime-contract.md) @@ -104,6 +105,36 @@ The key point is to separate: - the asset storage contract; - the operational strategy for reading and decode. +## Serialized Form Is Not Resident Form + +One of the most important asset-management lessons in the current runtime is that `RAW` does not mean "bitwise identical to in-memory layout". + +The tile-bank path is the concrete example: + +- the serialized payload stores indexed pixels as packed `4bpp`; +- the palette table remains serialized as `RGB565` little-endian; +- the runtime expands pixels into one `u8` index per pixel after decode. + +That is why `AssetEntry.size` and `AssetEntry.decoded_size` must be thought of as different concepts: + +- `size` is transport cost inside `assets.pa`; +- `decoded_size` is resident-bank cost after materialization. + +If those two numbers are treated as interchangeable, telemetry, budgets, and validation all become misleading. + +## Tile Banks Teach The Real Boundary + +Tile banks are useful because they show the real separation of concerns: + +- `assets.pa` defines the serialized envelope and metadata needed to reconstruct the bank; +- the runtime validates that metadata against the expected v1 contract; +- the resident `TileBank` is a runtime object, not a direct view over the cold bytes. + +This is the right PROMETEU mental model: + +- cartridge asset bytes are transport; +- bank objects are execution state. + ## Why This Fits PROMETEU This model fits the project well because: diff --git a/docs/runtime/learn/mental-model-gfx.md b/docs/runtime/learn/mental-model-gfx.md index 5f20a217..0049e017 100644 --- a/docs/runtime/learn/mental-model-gfx.md +++ b/docs/runtime/learn/mental-model-gfx.md @@ -3,6 +3,8 @@ Status: pedagogical Companion spec: [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md) +Related asset spec: [`../specs/15-asset-management.md`](../specs/15-asset-management.md) + PROMETEU treats graphics as an explicit peripheral, not as a modern GPU. The right mental model is a retro 2D machine with: @@ -10,7 +12,7 @@ The right mental model is a retro 2D machine with: - framebuffer; - tile banks; - tile layers; -- sprites por ordem de desenho; +- sprites ordered by draw order; - deterministic composition per frame. ## Why This Exists @@ -57,6 +59,30 @@ That enables: - HUD themes; - day and night cycles. +In the current tile-bank v1 baseline, this palette model is intentionally bounded: + +- each bank carries `64` palettes; +- each palette carries `16` colors; +- `palette_id` is therefore a small runtime-facing selector, not an open-ended color namespace. + +That limit is not incidental bookkeeping. It is part of how art packaging, runtime validation, and rendering stay aligned. + +## Tile Banks Are Decoded Runtime Objects + +The most useful intuition is to separate three layers: + +- authored indexed art; +- serialized cart payload; +- resident runtime bank. + +For tile banks in v1: + +- authored pixels are logical indices `0..15`; +- serialized payload stores those indices as packed `4bpp`; +- runtime memory expands them to one `u8` index per pixel after decode. + +So when reading the graphics model, do not imagine the renderer reading packed nibbles directly from cartridge storage. The renderer consumes a decoded `TileBank` object whose memory shape is optimized for runtime lookup, not for transport density. + ## Use Cases - area transition with `Scene Fade`; diff --git a/docs/runtime/pull-requests/013-tile-bank-runtime-contract-alignment.md b/docs/runtime/pull-requests/013-tile-bank-runtime-contract-alignment.md deleted file mode 100644 index 3d2d8fbc..00000000 --- a/docs/runtime/pull-requests/013-tile-bank-runtime-contract-alignment.md +++ /dev/null @@ -1,87 +0,0 @@ -# 013 Tile Bank Runtime Contract Alignment - -## Briefing - -O runtime hoje tem divergencia entre especificacao e implementacao para `tile bank`. - -O objetivo desta PR e fechar o contrato runtime-side que o packer deve atender antes de prosseguir com a materializacao definitiva de `tile bank` em `assets.pa`. - -Em especial, o repositorio precisa alinhar: - -- representacao serializada de indices de pixel; -- cardinalidade de paletas por bank; -- shape minimo de metadata usado pelo loader; -- e semantica de `codec` / `decoded_size` para `TILES`. - -## Decisions de Origem - -- `docs/packer/decisions/Pack Wizard Pack Execution Semantics Decision.md` -- discussao em andamento no packer sobre `Tile Bank Packing Materialization` - -## Alvo - -Alinhar o contrato normativo do runtime para `tile bank` v1 com a direcao: - -1. indices serializados como `u4` packed em `assets.pa`; -2. paletas serializadas como `RGB565 (u16 little-endian)`; -3. baseline v1 com `64` paletas por bank; -4. `palette_id` valido em `0..63`; -5. `codec = RAW` para tile bank no primeiro wave; -6. metadata minima suficiente para o loader reconstruir o bank em memoria. - -## Escopo - -- revisar `docs/runtime/specs/04-gfx-peripheral.md` -- revisar `docs/runtime/specs/15-asset-management.md` -- revisar `docs/runtime/specs/13-cartridge.md` somente se necessario para coerencia de referencia -- explicitar o contrato runtime-facing de tile bank em termos de: - - layout serializado; - - layout em memoria; - - limites de paleta; - - metadata minima; - - `decoded_size` - -## Fora de Escopo - -- implementar codigo do loader ou do driver -- ampliar o numero de paletas para `256` -- definir formatos comprimidos para `tile bank` -- definir `tilemap bank` -- redesenhar o modelo de GFX alem do necessario para coerencia do contrato - -## Plano de Execucao - -1. Auditar e registrar as divergencias atuais entre `specs/04`, `specs/15` e o codigo runtime. -2. Consolidar um baseline unico para `tile bank` v1: - - payload serializado com indices `u4` packed - - paletas `64 * 16 * u16` - - `palette_id` em `0..63` -3. Explicitar que a representacao em memoria pode continuar expandida para `u8` por pixel mesmo quando a forma serializada usa `u4`. -4. Definir metadata minima obrigatoria em `AssetEntry.metadata` para tiles: - - `tile_size` - - `width` - - `height` - - `palette_count` - - outros campos apenas se realmente necessarios para reconstruir o bank -5. Fechar a semantica de `decoded_size` para `tile bank` v1. -6. Revisar exemplos e linguagem normativa para remover contradicoes internas. - -## Criterios de Aceite - -- `docs/runtime/specs/04-gfx-peripheral.md` nao contradiz mais o limite de paletas efetivo de `tile bank` -- `docs/runtime/specs/04-gfx-peripheral.md` define `4bpp` packed como forma serializada do payload -- `docs/runtime/specs/15-asset-management.md` deixa claro o contrato runtime-facing necessario para reconstruir `TileBank` -- a distincao entre forma serializada e forma em memoria fica explicita -- a semantica de `palette_id` e `decoded_size` fica fechada para `tile bank` v1 - -## Tests / Validacao - -- revisao editorial cruzada entre `specs/04`, `specs/13` e `specs/15` -- checklist de coerencia contra o codigo existente do loader/runtime -- validacao com a agenda/decision do packer para garantir que o contrato e implementavel pelo `assets.pa` - -## Riscos - -- cristalizar cedo demais um limite de paletas que depois precise ser ampliado -- documentar `decoded_size` de forma utilitaria demais e gerar custo futuro em telemetry/budget -- deixar ambiguo o que pertence ao payload versus o que pertence ao `metadata` diff --git a/docs/runtime/pull-requests/014-tile-bank-loader-packed-nibbles-and-palette-boundary.md b/docs/runtime/pull-requests/014-tile-bank-loader-packed-nibbles-and-palette-boundary.md deleted file mode 100644 index b10b7714..00000000 --- a/docs/runtime/pull-requests/014-tile-bank-loader-packed-nibbles-and-palette-boundary.md +++ /dev/null @@ -1,76 +0,0 @@ -# 014 Tile Bank Loader Packed Nibbles and Palette Boundary - -## Briefing - -O codigo do runtime hoje ainda decodifica `tile bank` como: - -- `1 byte` por pixel indexado; -- `2048` bytes fixos de paleta; -- validacao efetiva de `palette_id` em `0..63`. - -Se o contrato v1 sera `u4` packed + `RGB565 u16`, o loader e os pontos de validacao do runtime precisam ser corrigidos antes de seguir com o packer-side materialization. - -## Decisions de Origem - -- `013-tile-bank-runtime-contract-alignment.md` -- `docs/packer/decisions/Pack Wizard Pack Execution Semantics Decision.md` - -## Alvo - -Atualizar o codigo do runtime para consumir `tile bank` v1 como: - -1. indices de pixel `u4` packed no payload serializado; -2. paletas `RGB565 (u16 little-endian)`; -3. `64` paletas por bank no primeiro wave; -4. representacao expandida em memoria para `Vec` somente apos decode; -5. validacao coerente de `palette_id` no ABI/runtime. - -## Escopo - -- atualizar decode de `tile bank` em `prometeu-drivers/src/asset.rs` -- revisar comentarios e invariantes em `prometeu-hal/src/tile_bank.rs` -- revisar pontos de validacao e range de `palette_id` no runtime path -- ajustar testes existentes do runtime que assumem payload `u8` por pixel - -## Fora de Escopo - -- introduzir compressao para `tile bank` -- ampliar `palette_count` para `256` -- mudar o modelo de `TileBank` para armazenar nibbles packed em memoria -- mudar o contrato de `sound bank` -- definir ou implementar `tilemap bank` - -## Plano de Execucao - -1. Alterar o decode do payload de `tile bank` para calcular o tamanho esperado de indices como `(width * height + 1) / 2`. -2. Implementar unpack deterministico de nibbles para a representacao em memoria `Vec`. -3. Preservar a leitura das paletas como `u16 little-endian`. -4. Tornar explicita a quantidade de paletas suportadas em v1 no codigo, evitando magic numbers soltos. -5. Revisar comentarios/documentacao inline em `TileBank` para diferenciar: - - payload serializado - - representacao expandida em memoria -6. Ajustar testes para cobrir: - - unpack correto de nibbles - - transparencias (`0`) - - limites de paleta - - rejeicao de buffer curto - -## Criterios de Aceite - -- o loader de `tile bank` nao assume mais `1 byte` por pixel no payload serializado -- o runtime reconstrui corretamente `pixel_indices: Vec` a partir de nibbles packed -- o bloco de paletas continua sendo lido como `RGB565 u16 little-endian` -- o range efetivo de `palette_id` fica coerente com o contrato v1 de `64` paletas -- os testes do runtime cobrem o novo layout e falhas de tamanho insuficiente - -## Tests / Validacao - -- testes unitarios do decode de `tile bank` -- testes de roundtrip do loader usando payload sintetico -- validacao de compatibilidade com o contrato normativo atualizado em `docs/runtime/specs` - -## Riscos - -- unpack incorreto de nibbles gerar corrupcao visual silenciosa -- confusao entre `decoded_size` logico e tamanho serializado do payload -- deixar o codigo parcialmente alinhado com a spec, mas com ranges de ABI ainda antigos ou contraditorios diff --git a/docs/runtime/pull-requests/README.md b/docs/runtime/pull-requests/README.md index 28be0955..9a96ae15 100644 --- a/docs/runtime/pull-requests/README.md +++ b/docs/runtime/pull-requests/README.md @@ -41,3 +41,5 @@ Nenhuma PR em aberto no momento. ## PRs Finalizadas - `012-assets-preload-asset-id-propagation.md`: concluída. Propagação de ID-based preload concluída em specs e prometeu-hal. +- `013-tile-bank-runtime-contract-alignment.md`: concluída. Contrato normativo de `tile bank` v1 alinhado entre `specs/04` e `specs/15`. +- `014-tile-bank-loader-packed-nibbles-and-palette-boundary.md`: concluída. Loader/runtime atualizado para consumir payload serializado `4bpp` packed com `64` paletas por bank.