This commit is contained in:
-405
@@ -1,405 +0,0 @@
|
||||
---
|
||||
id: AGD-0026
|
||||
ticket: render-all-scene-cache-and-camera-integration
|
||||
title: Agenda - Integrate render_all with Scene Cache and Camera
|
||||
status: accepted
|
||||
created: 2026-04-14
|
||||
updated: 2026-04-15
|
||||
tags: [gfx, runtime, render, camera, scene]
|
||||
---
|
||||
|
||||
## Contexto
|
||||
|
||||
A thread `DSC-0025` fechou a base arquitetural para `SceneBank`, `SceneViewportCache`, `SceneViewportResolver` e o decoder binário de `SCENE`. O renderer já possui um caminho explícito `render_scene_from_cache(&SceneViewportCache, &ResolverUpdate)`, mas o loop operacional do runtime ainda chama apenas `render_all()`.
|
||||
|
||||
Hoje, em [tick.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs:148), o frame segue pelo `hw.gfx_mut().render_all()`. Isso significa que o caminho novo de world render ainda não está integrado ao ciclo normal do runtime.
|
||||
|
||||
Ao mesmo tempo, a integração correta depende de fechar o contrato mínimo da câmera, porque o `SceneViewportResolver` já assume uma posição de câmera em pixel space e produz `ResolverUpdate` a partir dela. Sem essa integração, o runtime fica com duas verdades práticas:
|
||||
|
||||
- a arquitetura aceita para world rendering;
|
||||
- o caminho ainda efetivamente usado pelo frame loop.
|
||||
|
||||
## Problema
|
||||
|
||||
Precisamos integrar `render_scene_from_cache()` ao `render_all()` e ao ciclo real do runtime sem reabrir a arquitetura já aceita para `SceneBank` / `SceneViewportCache` / `SceneViewportResolver`.
|
||||
|
||||
O problema concreto não é só “chamar uma função”. É decidir:
|
||||
|
||||
- quem é dono do estado de câmera mínimo;
|
||||
- onde `SceneBank`, `SceneViewportCache` e `SceneViewportResolver` passam a residir em runtime;
|
||||
- quando o cache é atualizado;
|
||||
- como o `render_all()` deixa de ser um caminho “scene-blind” e vira o entrypoint normal da composição final.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
- `render_all()` deve continuar funcional mesmo quando nenhuma scene estiver carregada.
|
||||
- O `render_all()` atual não desenha world layers; ele só compõe sprites de prioridade 0 e fades.
|
||||
- O modelo atual de `Sprite.priority` mistura duas responsabilidades:
|
||||
- em qual faixa de composição o sprite entra;
|
||||
- qual a ordem relativa entre sprites naquela faixa.
|
||||
- `render_scene_from_cache()` existe, mas exige `SceneViewportCache` e `ResolverUpdate` já preparados por fora.
|
||||
- O modelo atual de sprites ainda é slot-first para o chamador:
|
||||
- há armazenamento fixo;
|
||||
- o dev informa índice;
|
||||
- e o renderer precisa filtrar `active`.
|
||||
- O `SceneViewportResolver` já carrega política importante:
|
||||
- câmera em pixel space
|
||||
- anchors
|
||||
- clamp
|
||||
- histerese
|
||||
- refresh requests
|
||||
- copy requests
|
||||
- Ainda não existe um dono explícito do estado operacional:
|
||||
- cena ativa
|
||||
- cache ativo
|
||||
- resolver ativo
|
||||
- câmera ativa
|
||||
- O `FrameComposer` não pode regredir o contrato já aceito no scene model:
|
||||
- `SceneLayer.tile_size` já é por-layer e aceita `8x8`, `16x16` e `32x32`;
|
||||
- o decoder de `SCENE` já materializa esses tamanhos;
|
||||
- fixar o pipeline em `16x16` dentro do orquestrador de frame criaria uma restrição artificial que não existe no modelo canônico.
|
||||
- Se a integração for mal feita, o renderer pode voltar a misturar:
|
||||
- política de câmera
|
||||
- atualização de cache
|
||||
- composição final
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao 1 - Integrar tudo diretamente dentro de `Gfx`
|
||||
|
||||
**Como seria:**
|
||||
`Gfx` passa a possuir a scene ativa, o cache, o resolver e a câmera; `render_all()` atualiza resolver/cache e já compõe tudo.
|
||||
|
||||
**Vantagens:**
|
||||
- caminho curto de integração;
|
||||
- menos objetos atravessando o runtime;
|
||||
- fácil de chamar a partir do tick.
|
||||
|
||||
**Desvantagens:**
|
||||
- empurra para `Gfx` responsabilidade demais;
|
||||
- mistura composição com estado de cena/câmera;
|
||||
- reduz clareza para testes e evolução futura.
|
||||
|
||||
### Opcao 2 - Integrar no runtime com um controlador explícito de scene viewport
|
||||
|
||||
**Como seria:**
|
||||
O runtime ou um pequeno controlador operacional passa a possuir:
|
||||
- scene ativa
|
||||
- cache
|
||||
- resolver
|
||||
- câmera
|
||||
|
||||
Esse controlador atualiza o cache quando a câmera muda e entrega ao `Gfx` apenas o que ele precisa para compor.
|
||||
|
||||
**Vantagens:**
|
||||
- separa melhor estado operacional de composição;
|
||||
- mantém `Gfx` mais focado em render;
|
||||
- preserva a ideia de que o resolver é dono da política de movimento/rematerialização.
|
||||
- permite manter um caminho explícito de `render_all()` sem scene carregada.
|
||||
|
||||
**Desvantagens:**
|
||||
- adiciona mais um objeto operacional no runtime;
|
||||
- exige definir uma superfície clara entre runtime e renderer.
|
||||
|
||||
### Opcao 3 - Fazer uma integração mínima temporária em `render_all()` e postergar a arquitetura do dono da câmera
|
||||
|
||||
**Como seria:**
|
||||
Criar um caminho temporário para que `render_all()` receba ou consulte estado suficiente para chamar `render_scene_from_cache()`, mas sem ainda fechar onde mora a câmera a longo prazo.
|
||||
|
||||
**Vantagens:**
|
||||
- acelera a ligação do caminho novo ao frame loop;
|
||||
- destrava testes end-to-end rapidamente.
|
||||
|
||||
**Desvantagens:**
|
||||
- alto risco de solução transitória virar definitiva;
|
||||
- deixa ambiguidade operacional exatamente no ponto mais sensível da integração.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Seguir com a **Opcao 2**.
|
||||
|
||||
Ou seja:
|
||||
|
||||
- `FrameComposer` passa a ser o orquestrador de frame/scene;
|
||||
- `FrameComposer` deve morar em `hardware/drivers`;
|
||||
- `Hardware` passa a agregar `FrameComposer` ao lado de `Gfx`;
|
||||
- `Gfx` permanece como backend de composição e blit;
|
||||
- a política do frame não deve ficar presa ao hardware atual;
|
||||
- isso preserva espaço para:
|
||||
- fast paths com diretivas/capacidades de GPU quando existirem;
|
||||
- uma futura implementação mais próxima de PPU / bare metal;
|
||||
- `render_all()` deve continuar sendo o entrypoint normal de composição;
|
||||
- `render_all()` deve continuar funcionando mesmo sem scene ativa;
|
||||
- mas ele não deve virar dono da câmera nem do ciclo de atualização do cache;
|
||||
- precisamos de um orquestrador operacional no runtime, ou imediatamente adjacente a ele, que:
|
||||
- mantenha a scene ativa opcional;
|
||||
- mantenha a câmera / viewport mínima;
|
||||
- mantenha o controlador de sprites do frame;
|
||||
- atualize o `SceneViewportResolver` quando houver scene;
|
||||
- aplique refreshes ao `SceneViewportCache` quando houver scene;
|
||||
- e entregue ao `Gfx` o estado pronto para compor.
|
||||
|
||||
Mais explicitamente:
|
||||
|
||||
- `FrameComposer` passa a ser dono de:
|
||||
- scene ativa;
|
||||
- câmera / viewport;
|
||||
- `SceneViewportCache`;
|
||||
- `SceneViewportResolver`;
|
||||
- sprites emitidos no frame;
|
||||
- o state de scene/sprite que hoje esteja em `Gfx` deve migrar para `FrameComposer`;
|
||||
- `Gfx` deve ficar focado em:
|
||||
- composição;
|
||||
- blit;
|
||||
- raster;
|
||||
- execução visual do frame preparado.
|
||||
|
||||
Para V1, o contrato mínimo de câmera pode continuar pequeno:
|
||||
|
||||
- `camera_x_px: i32`
|
||||
- `camera_y_px: i32`
|
||||
- representando o canto superior esquerdo da viewport no mundo
|
||||
|
||||
Sem follow/smoothing/shake/cut nesta etapa.
|
||||
|
||||
O comportamento mínimo recomendado fica:
|
||||
|
||||
- sem scene ativa:
|
||||
- `FrameComposer` continua válido;
|
||||
- `render_all()` compõe apenas o que já existe fora do pipeline de world (`sprites`, `fades`, e futuramente `HUD` quando aplicável);
|
||||
- não existe `clear` implícito;
|
||||
- limpar o `back` continua sendo responsabilidade explícita do chamador / dev;
|
||||
- com scene ativa:
|
||||
- `FrameComposer` atualiza resolver/cache;
|
||||
- `render_all()` compõe o world a partir do cache e preserva a ordem já aceita.
|
||||
|
||||
Esta direção é provisoriamente aceita mesmo sem a figura final completa, justamente para permitir que a integração avance e revele os pontos onde a separação runtime/backend ainda precise de ajuste.
|
||||
|
||||
Para sprites, a direção provisória recomendada fica:
|
||||
|
||||
- cada `Sprite` deve carregar:
|
||||
- `layer`
|
||||
- `priority`
|
||||
- `Sprite.active` deve ser removido;
|
||||
- `layer` define em qual faixa de composição o sprite entra;
|
||||
- `priority` define a ordenação entre sprites daquela mesma faixa;
|
||||
- a composição observável passa a ser por camada:
|
||||
- `(sprites -> scene) layer_0`
|
||||
- `(sprites -> scene) layer_1`
|
||||
- `(sprites -> scene) layer_2`
|
||||
- `(sprites -> scene) layer_3`
|
||||
|
||||
Isso substitui o modelo atual em que um único `priority` tenta representar ao mesmo tempo posição macro na composição e ordenação fina.
|
||||
|
||||
O modelo operacional recomendado para sprites passa a ser:
|
||||
|
||||
- capacidade máxima interna de `512` sprites por frame;
|
||||
- contador zerado a cada frame;
|
||||
- o dev não informa mais índice de sprite;
|
||||
- cada emissão ocupa o próximo slot interno disponível;
|
||||
- o registro já coloca o sprite no bucket correto da layer;
|
||||
- a composição consome apenas os sprites emitidos naquele frame.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- Fechado provisoriamente:
|
||||
- `FrameComposer` em `hardware/drivers`;
|
||||
- `Hardware` agrega `FrameComposer` e `Gfx`;
|
||||
- `Gfx` atua como backend operacional de composição.
|
||||
- O contrato mínimo do `FrameComposer` precisa ser fechado normativamente.
|
||||
- Fechado:
|
||||
- o subsistema interno de sprites se chama `SpriteController`.
|
||||
- `Sprite.layer` deve ser um enum fechado (`Layer0..Layer3`) ou um tipo mais genérico?
|
||||
- fechado provisoriamente:
|
||||
- manter numérico;
|
||||
- usar o mesmo tipo/referência de layer do `SceneBank`.
|
||||
- A composição por camada deve ser:
|
||||
- `sprites -> scene` dentro de cada layer, como direção inicial,
|
||||
- ou `scene -> sprites` para alguma camada específica?
|
||||
- A ordenação entre sprites de uma mesma layer será:
|
||||
- fechado:
|
||||
- `priority` menor blita primeiro;
|
||||
- em empate, FIFO por ordem de registro.
|
||||
- Overflow de sprite no frame:
|
||||
- fechado: excedentes são ignorados;
|
||||
- deve existir espaço para log/telemetria;
|
||||
- futuramente isso pode virar sinal negativo para certificação.
|
||||
- `emit_sprite(...)` precisa retornar algo, ou ter reset separado além de `begin_frame()`?
|
||||
- fechado por enquanto:
|
||||
- não;
|
||||
- usar apenas log do sistema para overflow/eventos operacionais;
|
||||
- não introduzir reset extra além do fluxo normal do frame.
|
||||
- `render_all()` deve:
|
||||
- continuar sem parâmetros e consultar estado já preparado,
|
||||
- ou ganhar uma nova superfície interna para receber o scene state preparado?
|
||||
- direção aceita:
|
||||
- `FrameComposer` chama o entrypoint de composição do backend visual;
|
||||
- `Gfx.render_all()` deve morrer;
|
||||
- o serviço deve migrar para `FrameComposer.renderFrame()`.
|
||||
|
||||
## Contrato Minimo Proposto
|
||||
|
||||
Direção proposta para V1 do `FrameComposer`:
|
||||
|
||||
- `bind_scene(...)`
|
||||
- recebe um `scene bank id`;
|
||||
- `FrameComposer` deve possuir acesso a `SceneBankPoolAccess`;
|
||||
- resolve a scene ativa através do pool;
|
||||
- o acesso ao bank deve ser sempre por ponteiro / referência compartilhada, nunca por cópia;
|
||||
- ao bindar, o compositor guarda:
|
||||
- `scene_bank_id`;
|
||||
- `Arc<SceneBank>` já resolvido;
|
||||
- consegue verificar se a scene está carregada;
|
||||
- inicializa ou reinicializa cache/resolver conforme necessário.
|
||||
|
||||
- `unbind_scene()`
|
||||
- remove a scene ativa;
|
||||
- invalida o pipeline de world;
|
||||
- descarta o cache associado à scene bindada;
|
||||
- mantém o compositor funcional para `sprites + fades`.
|
||||
|
||||
- `set_camera(x, y)`
|
||||
- atualiza a posição da câmera em pixel space;
|
||||
- `x, y` representam o canto superior esquerdo da viewport no mundo.
|
||||
|
||||
- `begin_frame()`
|
||||
- zera o contador de sprites emitidos;
|
||||
- limpa buckets internos de sprite;
|
||||
- prepara o estado transitório do frame.
|
||||
|
||||
- `emit_sprite(...)`
|
||||
- registra um sprite no próximo slot interno disponível;
|
||||
- associa o sprite à sua `layer`;
|
||||
- insere no bucket correspondente;
|
||||
- overflow é ignorado com espaço para log/telemetria.
|
||||
|
||||
- `compose_frame()`
|
||||
- se houver scene ativa:
|
||||
- atualiza `SceneViewportResolver`;
|
||||
- aplica `CacheRefreshRequest`s ao `SceneViewportCache`;
|
||||
- aciona o caminho de composição world + sprites;
|
||||
- se não houver scene ativa:
|
||||
- aciona o caminho `sprites + fades`;
|
||||
- delega a composição efetiva ao `Gfx`.
|
||||
|
||||
### Observacoes
|
||||
|
||||
- `end_frame()` não parece obrigatório na V1.
|
||||
- `begin_frame()` + `compose_frame()` já cobrem o ciclo mínimo.
|
||||
- `FrameComposer` decide e prepara;
|
||||
`Gfx` executa a composição.
|
||||
- o binding de scene deve ser por `scene bank id`, não por ownership direto de `SceneBank`.
|
||||
- o `SceneViewportCache` vive dentro do `FrameComposer` enquanto a scene estiver bindada.
|
||||
- troca do conteúdo do slot/bank exige novo `bind_scene(...)`;
|
||||
o `FrameComposer` não deve ficar fazendo polling constante do pool para revalidar a scene ativa.
|
||||
- o fluxo operacional aceito é:
|
||||
- `FrameComposer.compose_frame()`
|
||||
- chama o serviço `FrameComposer.renderFrame()`.
|
||||
- `FrameComposer` deve ser capaz de renderizar algo 100% do tempo:
|
||||
- cache/resolver ficam `None` sem bind;
|
||||
- deve existir uma forma explícita de saber se a scene está disponível para render.
|
||||
- `bind_scene(...)` substitui completamente a scene anterior.
|
||||
|
||||
## Sugestao / Recomendacao Atualizada
|
||||
|
||||
Aceitar o contrato mínimo acima como base de fechamento da agenda, a menos que apareça alguma necessidade concreta de:
|
||||
|
||||
- separar `compose_frame()` em múltiplas fases públicas;
|
||||
- expor refresh manual de cache para o chamador;
|
||||
- ou introduzir um `end_frame()` com semântica real além do reset que já ocorre em `begin_frame()`.
|
||||
- manter o binding de scene como:
|
||||
- `scene_bank_id + Arc<SceneBank>`;
|
||||
- com rebind explícito quando o slot mudar.
|
||||
- Quem é responsável por aplicar `CacheRefreshRequest` ao `SceneViewportCache`:
|
||||
- fechado: sempre o `FrameComposer`.
|
||||
- Qual é o contrato explícito de “nenhuma scene carregada”:
|
||||
- fechado: `sprites + fades`, sem `clear` implícito.
|
||||
- Como a cena ativa é selecionada e trocada no ciclo real:
|
||||
- fechado: `bind_scene(scene_bank_id)` com resolução através de `SceneBankPoolAccess`.
|
||||
- O HUD entra nesta integração já agora, ou o foco da primeira integração é apenas world + sprites + fades?
|
||||
- fechado: sem HUD nesta primeira integração.
|
||||
|
||||
## Reabertura 2026-04-15
|
||||
|
||||
### Contexto adicional
|
||||
|
||||
Ao revisitar a thread, apareceu uma restrição indevida: tratar o `FrameComposer` como se aceitasse apenas tilesets `16x16`.
|
||||
|
||||
Isso conflita com o estado atual do runtime:
|
||||
|
||||
- `TileSize` no HAL já enumera `Size8`, `Size16` e `Size32`;
|
||||
- `SceneLayer` carrega `tile_size` por layer;
|
||||
- o decoder de `SCENE` já aceita `8`, `16` e `32`;
|
||||
- `SceneViewportResolver` e `SceneViewportCache` já calculam offsets, anchors e cópia a partir do `tile_size` da própria layer.
|
||||
|
||||
O risco aqui não é apenas de implementação. Se o contrato do `FrameComposer` assumir `16x16` como pré-condição, ele quebra a neutralidade do orquestrador e reabre uma limitação artificial acima do scene model.
|
||||
|
||||
### Problema reaberto
|
||||
|
||||
Precisamos fechar explicitamente que o `FrameComposer` aceita cenas/layers com `tile_size` `8x8` e não impõe `16x16` como tamanho mínimo ou obrigatório para o world path.
|
||||
|
||||
### Opcoes adicionais
|
||||
|
||||
### Opcao 4 - Fixar `16x16` no `FrameComposer` e tratar `8x8` como fora de escopo
|
||||
|
||||
**Vantagens:**
|
||||
- reduz casos de teste imediatos;
|
||||
- simplifica implementação inicial se alguém estiver assumindo viewport/caches calibrados manualmente para `16`.
|
||||
|
||||
**Desvantagens:**
|
||||
- contradiz o scene model já aceito;
|
||||
- introduz restrição artificial no orquestrador;
|
||||
- obriga futura revisão de contrato para reaceitar algo que a base já suporta.
|
||||
|
||||
### Opcao 5 - Manter `FrameComposer` tile-size agnostic e aceitar `8x8` desde V1
|
||||
|
||||
**Vantagens:**
|
||||
- preserva o contrato canônico já existente em `SceneLayer`;
|
||||
- mantém o `FrameComposer` como orquestrador, não como redefinidor de formato;
|
||||
- evita bifurcação entre pipeline de scene e pipeline de composição.
|
||||
|
||||
**Desvantagens:**
|
||||
- exige deixar isso explícito na decisão e nos planos;
|
||||
- aumenta a exigência de testes para viewport/cache/cópia com `8x8`.
|
||||
|
||||
### Recomendacao adicional
|
||||
|
||||
Seguir com a **Opcao 5**.
|
||||
|
||||
Norma proposta para fechamento desta reabertura:
|
||||
|
||||
- `FrameComposer` deve aceitar scenes/layers cujo `tile_size` resolvido seja `8x8`, `16x16` ou `32x32`;
|
||||
- `FrameComposer` nao deve impor `16x16` como pré-condição para bind, cache, resolver ou composição;
|
||||
- qualquer validação de compatibilidade deve ser derivada do `tile_size` declarado pela própria layer / glyph bank, nunca de um default rígido no compositor;
|
||||
- os planos derivados desta thread precisam citar testes explícitos para `8x8`.
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
Esta agenda pode ser encerrada quando estiver explícito:
|
||||
|
||||
- quem é dono do estado mínimo de câmera;
|
||||
- quem é dono da scene/cache/resolver ativos;
|
||||
- como funciona o bind/unbind da scene ativa;
|
||||
- quando o cache é atualizado;
|
||||
- como `render_all()` passa a compor o world path aceito;
|
||||
- que o `FrameComposer` permanece agnóstico ao `tile_size` canônico da layer e aceita `8x8` sem downgrade contratual;
|
||||
- e qual é a superfície mínima de integração para implementação sem reabrir a arquitetura base.
|
||||
|
||||
## Resolucao
|
||||
|
||||
Esta agenda fica aceita com a seguinte direcao:
|
||||
|
||||
- `Gfx.render_all()` deve ser aposentado;
|
||||
- o fluxo operacional deve convergir para `FrameComposer.render_frame()`;
|
||||
- `FrameComposer` vive em `hardware/drivers`, ao lado de `Gfx`, e passa a ser dono do estado operacional do frame;
|
||||
- `FrameComposer` deve manter:
|
||||
- scene ativa opcional;
|
||||
- camera/viewport;
|
||||
- `SceneViewportCache`;
|
||||
- `SceneViewportResolver`;
|
||||
- `SpriteController`;
|
||||
- scene ativa e acessada por `scene_bank_id + Arc<SceneBank>` via `SceneBankPoolAccess`, sem copias;
|
||||
- troca de slot exige novo `bind_scene(...)`;
|
||||
- sem scene ativa, o frame continua valido com `sprites + fades`, sem `clear` implicito;
|
||||
- sprites passam a ser emitidos por frame, sem `Sprite.active`, com capacidade maxima de `512`, overflow ignorado e ordenacao por `layer`, `priority`, e FIFO em empate;
|
||||
- HUD fica fora desta primeira integracao.
|
||||
@@ -1,214 +0,0 @@
|
||||
---
|
||||
id: AGD-0027
|
||||
ticket: frame-composer-public-syscall-surface
|
||||
title: Agenda - FrameComposer Public Syscall Surface
|
||||
status: accepted
|
||||
created: 2026-04-17
|
||||
updated: 2026-04-17
|
||||
tags: [gfx, runtime, syscall, abi, frame-composer, scene, camera, sprites]
|
||||
---
|
||||
|
||||
## Contexto
|
||||
|
||||
`DEC-0014` e os planos `PLN-0017` a `PLN-0021` fecharam a migração interna do pipeline de frame para `FrameComposer`:
|
||||
|
||||
- `FrameComposer` virou o orquestrador canônico do frame;
|
||||
- `Hardware` passou a agregá-lo ao lado de `Gfx`;
|
||||
- scene, camera, cache, resolver e sprite emission migraram para ownership interno dele;
|
||||
- o frame loop do runtime passou a renderizar via `FrameComposer.render_frame()`.
|
||||
|
||||
Isso resolveu a base operacional interna, mas não fechou a superfície pública equivalente para a VM. A ABI pública ainda expõe apenas o contrato legado de `gfx.set_sprite(...)`, enquanto `bind_scene(...)` e `set_camera(...)` existem apenas como APIs internas do driver.
|
||||
|
||||
Na prática, hoje temos uma assimetria:
|
||||
|
||||
- a base canônica do frame está em `FrameComposer`;
|
||||
- mas a ABI pública ainda não trata `FrameComposer` como serviço canônico para scene, camera e sprites.
|
||||
|
||||
Essa lacuna impede a migração do restante da stack e também impede um stress cartridge que atravesse de verdade o pipeline novo por syscall pública.
|
||||
|
||||
## Problema
|
||||
|
||||
Precisamos definir a nova superfície pública de syscall para o pipeline canônico de `FrameComposer` sem reabrir a decisão já aceita sobre ownership interno do frame.
|
||||
|
||||
O problema concreto não é “adicionar 2 ou 3 syscalls”. Precisamos decidir:
|
||||
|
||||
- quais operações de `FrameComposer` viram ABI pública agora;
|
||||
- se `gfx.set_sprite(...)` continua como shim legado ou perde status canônico;
|
||||
- qual é o contrato mínimo de scene/camera que a VM pode observar/controlar;
|
||||
- como nomear e versionar essa superfície pública sem criar um segundo modelo canônico concorrente;
|
||||
- qual é a estratégia de transição para cartridge, runtime tests e stress tests;
|
||||
- como propagar essa mudança para a spec canônica e, se necessário, para contratos de ABI e `ISA_CORE`.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
- `DEC-0014` já fechou `FrameComposer` como base canônica interna; esta agenda não deve reabrir isso.
|
||||
- A ABI pública atual ainda expõe `gfx.set_sprite(...)` com semântica herdada de índice/slot, mesmo que a implementação interna já use frame emission.
|
||||
- `bind_scene(scene_bank_id)` e `set_camera(x, y)` já existem no driver, mas ainda não existem como syscalls públicas.
|
||||
- Se a nova ABI expuser demais logo de início, vamos congelar cedo demais detalhes que ainda não provaram valor operacional.
|
||||
- Se a nova ABI expuser de menos, manteremos um modelo híbrido por tempo demais:
|
||||
- canônico internamente via `FrameComposer`;
|
||||
- legado externamente via `Gfx`/`set_sprite`.
|
||||
- Precisamos decidir se o namespace público continua em `gfx.*` por estabilidade do domínio, ou se devemos introduzir algo como `frame.*`.
|
||||
- A transição precisa preservar compatibilidade suficiente para não quebrar cartridges e testes existentes antes da migração do restante.
|
||||
- O contrato de sprite precisa deixar claro se o chamador ainda informa índice, se informa `layer`, e se `active` continua existindo na superfície pública.
|
||||
- A mudança não pode ficar só em código/runtime; a spec canônica precisa ser atualizada para refletir o novo serviço público.
|
||||
- Se o contrato público afetar superfícies documentadas de ABI ou o material de `ISA_CORE`, essa propagação precisa ser tratada como parte da mesma thread, não como follow-up solto.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao 1 - Expor um núcleo mínimo canônico em `gfx.*`
|
||||
|
||||
**Como seria:**
|
||||
Adicionar apenas a superfície mínima para a VM controlar o pipeline novo:
|
||||
|
||||
- `gfx.bind_scene(bank_id)`
|
||||
- `gfx.unbind_scene()`
|
||||
- `gfx.set_camera(x, y)`
|
||||
- `gfx.emit_sprite(...)`
|
||||
|
||||
`gfx.set_sprite(...)` permaneceria por um período como shim legado de compatibilidade.
|
||||
|
||||
**Vantagens:**
|
||||
- fecha rapidamente a lacuna operacional;
|
||||
- habilita stress real do pipeline novo;
|
||||
- reduz o tempo de convivência entre modelo canônico e legado;
|
||||
- mantém o domínio público em `gfx`, evitando churn de namespace.
|
||||
|
||||
**Desvantagens:**
|
||||
- introduz ABI nova que precisará de migração coordenada;
|
||||
- exige definir `emit_sprite(...)` com cuidado para não herdar sem querer o modelo de slot.
|
||||
|
||||
### Opcao 2 - Expor scene/camera agora e adiar o contrato novo de sprite
|
||||
|
||||
**Como seria:**
|
||||
Publicar apenas:
|
||||
|
||||
- `gfx.bind_scene(bank_id)`
|
||||
- `gfx.unbind_scene()`
|
||||
- `gfx.set_camera(x, y)`
|
||||
|
||||
Sprites continuariam publicamente via `gfx.set_sprite(...)` até uma segunda fase.
|
||||
|
||||
**Vantagens:**
|
||||
- menor mudança imediata de ABI;
|
||||
- desbloqueia o stress do world path e da câmera;
|
||||
- reduz o volume inicial da migração pública.
|
||||
|
||||
**Desvantagens:**
|
||||
- mantém dois modelos públicos de sprite por mais tempo;
|
||||
- prolonga a semântica de compatibilidade do syscall legado;
|
||||
- adia exatamente uma das partes centrais da migração para `FrameComposer`.
|
||||
|
||||
### Opcao 3 - Criar um novo namespace público separado, como `composer.*`
|
||||
|
||||
**Como seria:**
|
||||
O pipeline novo ganha syscalls em um domínio separado, por exemplo:
|
||||
|
||||
- `composer.bind_scene`
|
||||
- `composer.unbind_scene`
|
||||
- `composer.set_camera`
|
||||
- `composer.emit_sprite`
|
||||
|
||||
`gfx.*` ficaria como superfície legacy/low-level.
|
||||
|
||||
**Vantagens:**
|
||||
- deixa explícita a mudança de serviço canônico;
|
||||
- evita sobrecarregar semanticamente `gfx`.
|
||||
|
||||
**Desvantagens:**
|
||||
- adiciona churn conceitual e de nomenclatura;
|
||||
- fragmenta demais a superfície pública neste momento;
|
||||
- cria um custo de transição maior sem benefício operacional evidente.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Seguir com a **Opcao 3**.
|
||||
|
||||
Direção recomendada:
|
||||
|
||||
- a superfície pública canônica deve migrar para o domínio `composer.*`;
|
||||
- `FrameComposer` vira a base canônica também na ABI pública, com namespace próprio em vez de continuar semanticamente preso a `gfx.*`;
|
||||
- o núcleo mínimo público deve ser:
|
||||
- `composer.bind_scene(bank_id) -> status`
|
||||
- `composer.unbind_scene()`
|
||||
- `composer.set_camera(x, y)`
|
||||
- `composer.emit_sprite(...) -> status`
|
||||
- `gfx.set_sprite(...)` deve morrer e ser removido completamente do contrato público.
|
||||
|
||||
Para sprites, a recomendação provisória é:
|
||||
|
||||
- a nova ABI pública não deve exigir índice explícito;
|
||||
- `composer.emit_sprite(...)` deve receber o payload completo necessário para o frame:
|
||||
- `glyph_id`
|
||||
- `palette_id`
|
||||
- `x`
|
||||
- `y`
|
||||
- `layer`
|
||||
- `bank_id`
|
||||
- `flip_x`
|
||||
- `flip_y`
|
||||
- `priority`
|
||||
- a ABI pode futuramente agrupar esse payload se isso melhorar ergonomia, mas o contrato mínimo deve nascer completo;
|
||||
- `active` não deve continuar no contrato canônico novo;
|
||||
- overflow continua sendo ignorado com status/telemetria adequada, sem trapar o runtime.
|
||||
|
||||
Para scene/camera, a recomendação provisória é:
|
||||
|
||||
- manter o contrato mínimo já aceito internamente;
|
||||
- `bind_scene` por bank id;
|
||||
- `unbind_scene` explícito;
|
||||
- `set_camera(x, y)` em pixel space com top-left viewport.
|
||||
- `bind_scene(...)`, `unbind_scene(...)` e `emit_sprite(...)` devem usar `ComposerOpStatus` como retorno operacional canônico.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- Resolvido:
|
||||
- o nome público canônico de sprite será `composer.emit_sprite(...)`;
|
||||
- o syscall novo de sprite nasce completo com `glyph_id`, `palette_id`, `x`, `y`, `layer`, `bank_id`, `flip_x`, `flip_y`, `priority`;
|
||||
- `gfx.set_sprite(...)` deve morrer e ser removido completamente;
|
||||
- não haverá leitura de estado nesta primeira fase;
|
||||
- `bind_scene(...)`, `unbind_scene(...)` e `emit_sprite(...)` usarão `ComposerOpStatus`;
|
||||
- A ABI nova precisa expor refresh explícito, ou isso deve continuar totalmente interno ao `FrameComposer`?
|
||||
- Resolvido:
|
||||
- a ABI nova não deve expor refresh explícito;
|
||||
- o domínio público canônico será `composer.*`, não `gfx.*`.
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
Esta agenda pode ser encerrada quando houver acordo explícito sobre:
|
||||
|
||||
- a lista mínima de syscalls públicas canônicas do `FrameComposer`;
|
||||
- o nome canônico da operação pública de sprite;
|
||||
- a remoção completa de `gfx.set_sprite(...)` do contrato público;
|
||||
- o formato de retorno/status das novas operações;
|
||||
- a estratégia de transição necessária para decisão, plano e migração do restante da stack.
|
||||
|
||||
## Resolucao em Andamento
|
||||
|
||||
Direção atualmente acordada nesta agenda:
|
||||
|
||||
- o namespace público canônico será `composer.*`;
|
||||
- o núcleo mínimo inicial será:
|
||||
- `composer.bind_scene(bank_id) -> ComposerOpStatus`
|
||||
- `composer.unbind_scene() -> ComposerOpStatus`
|
||||
- `composer.set_camera(x, y)`
|
||||
- `composer.emit_sprite(glyph_id, palette_id, x, y, layer, bank_id, flip_x, flip_y, priority) -> ComposerOpStatus`
|
||||
- não haverá introspecção pública nesta primeira fase;
|
||||
- refresh/cache policy continua interno ao `FrameComposer`;
|
||||
- `gfx.set_sprite(...)` não terá caminho de compatibilidade e deve ser removido.
|
||||
|
||||
## Resolucao
|
||||
|
||||
Esta agenda fica aceita com os seguintes pontos fechados:
|
||||
|
||||
- o namespace público canônico do serviço será `composer.*`;
|
||||
- a superfície mínima inicial será:
|
||||
- `composer.bind_scene(bank_id) -> ComposerOpStatus`
|
||||
- `composer.unbind_scene() -> ComposerOpStatus`
|
||||
- `composer.set_camera(x, y)`
|
||||
- `composer.emit_sprite(glyph_id, palette_id, x, y, layer, bank_id, flip_x, flip_y, priority) -> ComposerOpStatus`
|
||||
- não haverá introspecção pública nesta primeira fase;
|
||||
- não haverá refresh/cache policy público;
|
||||
- `gfx.set_sprite(...)` deve ser removido completamente, sem shim de compatibilidade;
|
||||
- a transição deve introduzir `composer.*` e remover `gfx.set_sprite(...)` na mesma thread de migração, com atualização coordenada de bytecode, cartridges, tests e runtime;
|
||||
- a mesma thread deve atualizar a spec canônica do assunto e propagar a mudança para contratos de ABI e `ISA_CORE` quando essas superfícies forem impactadas pelo novo serviço público.
|
||||
@@ -1,140 +0,0 @@
|
||||
---
|
||||
id: AGD-0028
|
||||
ticket: deferred-overlay-and-primitive-composition
|
||||
title: Deferred Overlay and Primitive Composition over FrameComposer
|
||||
status: accepted
|
||||
created: 2026-04-18
|
||||
updated: 2026-04-18
|
||||
resolved: 2026-04-18
|
||||
decision: DEC-0016
|
||||
tags: [gfx, runtime, render, frame-composer, overlay, primitives, hud]
|
||||
---
|
||||
|
||||
## Contexto
|
||||
|
||||
`FrameComposer.render_frame()` hoje recompõe o `back` no fim da logical frame. Quando há scene bound, o caminho `render_scene_from_cache(...)` limpa o buffer e desenha scene + sprites, o que apaga qualquer primitive ou `draw_text(...)` emitido antes via `gfx`.
|
||||
|
||||
Isso expôs um conflito de modelo:
|
||||
|
||||
- `composer.*` já é o caminho canônico de orquestração de frame;
|
||||
- `gfx.draw_text(...)` e demais primitives ainda escrevem diretamente no `back`;
|
||||
- o runtime só chama `render_frame()` no final do frame, então a escrita imediata em `back` deixou de ser semanticamente estável.
|
||||
- As primitives de `gfx` não são o mecanismo desejado para composição de jogos com scene/tile/sprite; elas existem principalmente como debug, instrumentação visual e artefatos rápidos.
|
||||
|
||||
Conteúdo relevante migrado de [AGD-0010](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/discussion/workflow/agendas/AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md):
|
||||
|
||||
- a arquitetura aceita continua sendo de framebuffer destrutivo em memória, não scene graph ou renderer tipo GPU;
|
||||
- otimizações em primitives devem preservar a semântica observável, mesmo quando ganharem fast paths internos;
|
||||
- existe preocupação explícita com custo por classe de primitive e com orçamento de memória no alvo handheld;
|
||||
- caminhos de spans/linhas/clears são desejáveis como aceleração interna, mas sem reabrir o modelo operacional do pipeline do jogo.
|
||||
|
||||
## Problema
|
||||
|
||||
Precisamos decidir qual é o modelo canônico para primitives e texto no pipeline pós-`FrameComposer`.
|
||||
|
||||
Sem isso:
|
||||
|
||||
- texto e primitives continuam com comportamento dependente da ordem interna do renderer;
|
||||
- o stress test e qualquer cartridge que combine `composer.*` com `gfx.*` terão resultado inconsistente;
|
||||
- fica indefinido se primitives pertencem ao mundo, ao HUD, ou a um overlay final.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
- `draw_text(...)` e primitives screen-space não podem depender de escrita imediata em `back`.
|
||||
- Para esta thread, primitives de `gfx` devem permanecer agnósticas ao pipeline canônico de render do jogo e não devem ser mescladas semanticamente com tiles/sprites.
|
||||
- A ordem de composição precisa ser explícita e estável: `scene -> sprites -> HUD -> primitives/debug overlay`, ou outra ordem formal equivalente.
|
||||
- Precisamos decidir se o contrato público de `gfx.*` muda semanticamente sem mudar ABI, ou se parte dessa superfície migra para `composer.*`.
|
||||
- A solução deve preservar o caminho sem scene bound.
|
||||
- A implementação deve evitar contaminar a infraestrutura de `gfx` responsável por scene, sprites e HUD com estado misto de overlay/debug; se necessário, o overlay deve ter fila/fase própria.
|
||||
- melhorias internas de primitive path devem continuar permitidas, desde que não mudem a semântica de overlay final e não exijam buffers extras incompatíveis com o orçamento de memória aceito.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao 1 - Manter escrita direta em `back`
|
||||
|
||||
- **Abordagem:** manter `gfx.draw_text(...)` e primitives rasterizando imediatamente.
|
||||
- **Pro:** zero mudança estrutural agora.
|
||||
- **Contra:** o modelo continua quebrado sempre que `render_frame()` recompõe o buffer depois.
|
||||
- **Tradeoff:** só funciona de forma confiável fora do caminho canônico do `FrameComposer`.
|
||||
|
||||
### Opcao 2 - Fila única de draw commands pós-scene/pós-sprite
|
||||
|
||||
- **Abordagem:** transformar texto e primitives em comandos diferidos, drenados depois de `scene + sprites`.
|
||||
- **Pro:** resolve o problema imediato de overlay/HUD e estabiliza o stress test.
|
||||
- **Contra:** mistura HUD e primitives/debug sob o mesmo conceito, reduzindo clareza contratual mesmo quando a ordem prática for a mesma.
|
||||
- **Tradeoff:** simples para V1, mas semanticamente mais fraco do que separar overlay de jogo e overlay de debug.
|
||||
|
||||
### Opcao 3 - Separar HUD diferido de primitives/debug overlay final
|
||||
|
||||
- **Abordagem:** tratar `gfx.draw_text(...)` e demais primitives de `gfx` como overlay/debug final, separado da composição canônica de jogo (`scene + sprites + HUD`).
|
||||
- **Pro:** casa com a intenção declarada para `gfx.*`: debug, artefato rápido e instrumentação visual acima do frame do jogo.
|
||||
- **Contra:** exige modelar explicitamente uma fase extra no pipeline.
|
||||
- **Tradeoff:** aumenta a clareza contratual e evita mesclar primitives com o domínio de jogo.
|
||||
|
||||
### Opcao 4 - Manter HUD e primitives no mesmo estágio final, mas com categorias separadas
|
||||
|
||||
- **Abordagem:** drenar HUD e primitives ambos no fim do frame, porém com filas/categorias distintas e ordem formal `HUD -> primitives`.
|
||||
- **Pro:** preserva implementação próxima entre caminhos similares, mantendo contrato separado.
|
||||
- **Contra:** é mais custoso que a opção 3 sem entregar muito valor adicional imediato.
|
||||
- **Tradeoff:** bom se já houver expectativa de HUD canônico separado no curtíssimo prazo.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Seguir com a **Opcao 3**.
|
||||
|
||||
Minha recomendação é:
|
||||
|
||||
- retirar a escrita direta em `back` como contrato operacional para `gfx.draw_text(...)` e demais primitives de `gfx`;
|
||||
- introduzir uma fila diferida canônica de primitives/debug overlay drenada no fim do frame;
|
||||
- tratar `gfx.*` primitive/text como superfície agnóstica ao pipeline de jogo e explicitamente acima da composição canônica;
|
||||
- não misturar semanticamente primitives com scene/tile/sprite/HUD.
|
||||
- evitar compartilhar indevidamente o mesmo mecanismo operacional de composição entre overlay/debug e os caminhos de scene/sprite/HUD, mesmo quando o backend de rasterização reutilizado for o mesmo.
|
||||
|
||||
Ordem recomendada para o frame canônico:
|
||||
|
||||
1. limpar/compor scene;
|
||||
2. compor sprites;
|
||||
3. compor HUD canônico, se existir;
|
||||
4. aplicar `scene_fade`;
|
||||
5. aplicar `hud_fade`;
|
||||
6. drenar primitives/debug overlay de `gfx.*`.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- `draw_text(...)` e as demais primitives de `gfx` entram todas na mesma família de overlay final já na V1, ou começamos só com `draw_text(...)`?
|
||||
- `render_no_scene_frame()` deve usar a mesma fila diferida para manter semântica idêntica com e sem scene?
|
||||
- HUD canônico precisa existir explicitamente nesta mesma thread, ou pode continuar implícito/externo enquanto as primitives já migram para overlay final?
|
||||
- quais fast paths internos de primitives continuam desejáveis nessa nova fase, por exemplo spans horizontais/verticais, fills e clears, sem misturar isso com a composição do jogo?
|
||||
- o overlay/debug final precisa de dirtying próprio por classe de primitive ou isso pode ficar fora da primeira migração?
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
Esta agenda pode ser encerrada quando tivermos uma resposta explícita para:
|
||||
|
||||
- o destino semântico de `draw_text(...)`;
|
||||
- se haverá uma fila própria para primitives/debug overlay e qual a relação dela com HUD;
|
||||
- a ordem canônica de composição do frame;
|
||||
- o escopo exato da primeira migração implementável sem reabrir o restante do pipeline.
|
||||
|
||||
## Resolucao Parcial
|
||||
|
||||
Direção já aceita nesta agenda:
|
||||
|
||||
- primitives e `draw_text(...)` de `gfx.*` devem ser tratadas como overlay/debug final;
|
||||
- esse overlay deve ser drenado **depois** de `hud_fade`;
|
||||
- scene, sprites e HUD canônico não devem ser semanticamente misturados com o overlay/debug;
|
||||
- a implementação deve preservar separação operacional suficiente para que o `gfx` usado pelo pipeline do jogo não passe a depender do estado transitório de primitives/debug;
|
||||
- otimizações de primitive path discutidas na `AGD-0010` continuam válidas, mas passam a operar dentro do domínio de overlay/debug final, não como parte da composição canônica de scene/sprite/HUD.
|
||||
|
||||
## Resolucao
|
||||
|
||||
Esta agenda fica aceita com os seguintes pontos fechados:
|
||||
|
||||
- `gfx.draw_text(...)` e as demais primitives públicas de `gfx.*` pertencem à mesma família V1 de overlay/debug final;
|
||||
- esse overlay/debug fica **fora** do `FrameComposer`;
|
||||
- `FrameComposer` continua restrito à composição canônica do jogo (`scene`, `sprites` e HUD canônico quando existir);
|
||||
- o overlay/debug deve ser drenado depois de `hud_fade`;
|
||||
- o caminho sem scene bound deve observar a mesma semântica final de overlay/debug;
|
||||
- HUD canônico explícito não faz parte desta thread e pode permanecer implícito/externo por enquanto;
|
||||
- fast paths internos de primitives continuam permitidos, desde que preservem a semântica observável do overlay/debug final;
|
||||
- dirtying granular ou otimizações finas por classe de primitive não fazem parte da primeira migração normativa desta thread.
|
||||
Reference in New Issue
Block a user