447 lines
25 KiB
Markdown
447 lines
25 KiB
Markdown
---
|
|
id: AGD-0038
|
|
ticket: render-frame-packet-boundary
|
|
title: Logical Render Pipelines and Command Packets
|
|
status: accepted
|
|
created: 2026-05-25
|
|
resolved:
|
|
decision:
|
|
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
|
---
|
|
|
|
# Agenda - Logical Render Pipelines and Command Packets
|
|
|
|
## Contexto
|
|
|
|
Depois da migracao para RGBA8888, o proximo passo arquitetural do renderer nao deve ser GPU, 3D, multiplos backends ou troca dinamica complexa de pipeline. O objetivo imediato e separar melhor tres responsabilidades:
|
|
|
|
1. pipelines logicos produzem comandos de alto nivel;
|
|
2. uma implementacao de hardware/render surface consome esses comandos;
|
|
3. o framebuffer RGBA8888 atual continua sendo a superficie final no desktop.
|
|
|
|
A direcao desejada agora e explicitar pelo menos dois pipelines logicos:
|
|
|
|
```text
|
|
Game 2D Pipeline
|
|
scene + sprites + HUD
|
|
-> Game2DFramePacket / Game2DCommandSet
|
|
-> hardware/render implementation
|
|
-> framebuffer RGBA8888
|
|
|
|
Prometeu UI Pipeline
|
|
shell/home/system UI/windows
|
|
-> UiFramePacket / UiCommandSet
|
|
-> hardware/render implementation
|
|
-> framebuffer RGBA8888
|
|
```
|
|
|
|
Esses pipelines podem funcionar de formas totalmente diferentes. O ponto comum nao deve ser uma API unica pobre que force tudo a parecer igual. O ponto comum deve ser a fronteira operacional: cada pipeline publica seu proprio conjunto logico de comandos para uma implementacao de hardware/superficie.
|
|
|
|
Com isso, se depois surgir um pipeline 3D, outro pipeline 2D, ou um renderer especializado para hardware barato/DIY, o trabalho fica concentrado no novo pipeline e/ou no consumidor de comandos, sem reabrir a VM inteira.
|
|
|
|
## Problema
|
|
|
|
Hoje o runtime ainda mistura producao logica de frame com desenho imediato no `Gfx`/framebuffer.
|
|
|
|
O codigo ja tem separacoes parciais:
|
|
|
|
- `FrameComposer` coordena scene binding, camera, cache/resolver e sprites do jogo.
|
|
- `Gfx` rasteriza em `back`, faz `present()` para `front`, e expoe `front_buffer()` para o host.
|
|
- `VirtualMachineRuntime` chama `hw.render_frame()` quando o frame logico termina.
|
|
- Prometeu Hub, splash/crash e varias chamadas `gfx.*` ainda desenham diretamente via `gfx_mut()`.
|
|
- O host desktop copia o `front_buffer()` RGBA8888 para `pixels`.
|
|
|
|
O limite atual ainda e "codigo logico chama renderer", nao "pipeline publica comandos para uma implementacao".
|
|
|
|
Isso cria custo futuro:
|
|
|
|
- o pipeline 2D de jogo fica preso ao formato operacional atual de `Gfx`;
|
|
- a UI do Prometeu fica misturada ao mesmo caminho imperativo de primitives;
|
|
- um futuro pipeline 3D teria que disputar o mesmo contrato em vez de definir sua propria saida logica;
|
|
- hardware barato/DIY teria que emular detalhes de `Gfx` em vez de consumir um command set adequado;
|
|
- testes ficam presos a pixels finais mesmo quando o que interessa e o pacote logico produzido.
|
|
|
|
## Pontos Criticos
|
|
|
|
### 1. Pipeline nao e backend
|
|
|
|
Pipeline deve significar "modelo logico de producao de comandos". Backend/implementacao deve significar "como esses comandos viram pixels/superficie".
|
|
|
|
Nao queremos agora:
|
|
|
|
- registry sofisticado de backends;
|
|
- troca dinamica de pipeline;
|
|
- GPU backend;
|
|
- 3D;
|
|
- refatoracao agressiva de asset pipeline;
|
|
- mudanca visual.
|
|
|
|
Queremos uma fronteira para que esses itens possam existir depois sem contaminar o passo atual.
|
|
|
|
### 2. Game 2D e Prometeu UI nao precisam compartilhar o mesmo command set
|
|
|
|
O pipeline 2D de jogos naturalmente fala de scene/cache/camera/sprites/HUD.
|
|
|
|
O pipeline de UI do Prometeu naturalmente fala de janelas, paineis, texto, retangulos, estados de foco, home/shell/system UI, talvez layout e clipping.
|
|
|
|
Forcar ambos a um `RenderCommand` generico demais no v1 pode criar uma abstracao fraca. A agenda deve decidir se o contrato comum sera:
|
|
|
|
- um enum top-level de pacotes por pipeline; ou
|
|
- uma trait de submissao ao hardware; ou
|
|
- um `FrameSubmission` que contem command sets tipados por dominio.
|
|
|
|
### 3. `FrameComposer` continua sendo bom candidato para o Game 2D Pipeline
|
|
|
|
`FrameComposer` ja e o ponto natural para produzir o pacote de jogo:
|
|
|
|
- scene binding;
|
|
- camera;
|
|
- cache/resolver;
|
|
- sprites por frame;
|
|
- HUD/primitives de jogo quando aplicavel.
|
|
|
|
O menor corte para jogo ainda parece ser transformar `FrameComposer.render_frame(&mut dyn GfxBridge)` em uma producao de `Game2DFramePacket`, consumida em seguida pelo renderer Classic2D atual.
|
|
|
|
### 4. Prometeu UI precisa sair do desenho direto, mas talvez nao no mesmo PR
|
|
|
|
Prometeu Hub e system UI hoje usam `hw.gfx_mut()` diretamente. Isso e exatamente o tipo de acoplamento que a arquitetura quer remover, mas migrar UI junto com Game 2D pode deixar a primeira mudanca grande demais.
|
|
|
|
A decisao precisa escolher entre:
|
|
|
|
- definir os dois contratos agora e implementar em fases;
|
|
- implementar primeiro Game 2D e registrar UI como segundo plan;
|
|
- ou implementar um envelope comum e dois producers minimos no mesmo plano.
|
|
|
|
### 5. HUD pertence ao pipeline 2D de jogo, nao ao Prometeu UI por padrao
|
|
|
|
Para esta agenda, "HUD" significa HUD do jogo como parte do frame de jogo: overlays do cart/gameplay, texto/debug de jogo e primitives 2D associadas ao jogo.
|
|
|
|
Prometeu UI significa UI do sistema: hub, shell, janelas, home, crash/splash se forem tratados como telas do sistema.
|
|
|
|
Essa separacao evita confundir UI de jogo com UI do console.
|
|
|
|
### 6. A implementacao inicial ainda pode ser uma so
|
|
|
|
Mesmo com dois pipelines logicos, a implementacao inicial pode continuar sendo o `Gfx`/Classic2D atual gravando em RGBA8888. O ganho arquitetural nao exige multiplos backends. Exige que a entrada da implementacao deixe de ser acesso direto ao framebuffer e passe a ser submissao de comandos logicos.
|
|
|
|
### 7. A fronteira deve preparar VM e render pipeline paralelos
|
|
|
|
Render thread nao e objetivo do v1, mas a fronteira nao deve impedir que a VM e o renderer rodem em paralelo depois.
|
|
|
|
Isso implica que a submissao de frame deve ser tratada como um snapshot fechado do trabalho de render daquele frame. Depois de publicada, a VM nao deve continuar mutando estruturas que o renderer precisa ler. A implementacao inicial pode consumir o snapshot imediatamente e no mesmo thread, mas o contrato deve evitar dependencias como `&mut Hardware`, `&mut Gfx`, ou acesso mutavel ao estado vivo da VM durante a rasterizacao.
|
|
|
|
Para o v1, isso sugere:
|
|
|
|
- `RenderSubmission` deve carregar `frame_id`, `app_mode` e dados suficientes para identificar a ordem de publicacao;
|
|
- command sets pequenos devem preferir dados owned ou buffers owned pelo produtor ate a publicacao;
|
|
- referencias pesadas, como cache/assets, devem ser read-only e ter ownership compartilhado ou lifetime claramente limitado;
|
|
- a camada de hardware/render surface deve ser a unica dona de publicacao/present;
|
|
- a VM deve produzir/submeter comandos, nao desenhar nem esperar acesso ao framebuffer;
|
|
- testes devem conseguir validar o packet/submission sem depender apenas do framebuffer final.
|
|
|
|
### 8. Deve existir um `RenderManager` acima dos pipelines
|
|
|
|
Mesmo evitando registry sofisticado de backends no v1, a arquitetura precisa de uma camada acima dos pipelines individuais. Essa camada nao deve ser "mais um pipeline"; ela deve coordenar:
|
|
|
|
- qual `AppMode` esta ativo (`Game` ou `Shell`);
|
|
- quais command buffers/submissions estao validos para esse modo;
|
|
- transicoes entre modos;
|
|
- publicacao da superficie;
|
|
- politica de latest frame;
|
|
- capacidades disponiveis por modo.
|
|
|
|
Motivacao principal: transicoes entre Shell e Game nao pertencem completamente a nenhum dos dois pipelines. Exemplo: o Shell UI pode executar uma transicao visual de saida ao abrir um jogo, mas depois que o Game 2D assume, o Shell UI ja nao existe mais para executar a transicao de entrada do jogo. Isso sugere uma base comum de render/control plane acima dos pipelines, capaz de manter transicoes e estado de superficie durante a troca de modo.
|
|
|
|
Essa camada deve se chamar `RenderManager`. O nome indica coordenacao de render, nao implementacao de desenho. A decisao precisa separar com cuidado:
|
|
|
|
- `RenderManager` como abstracao/runtime contract de coordenacao;
|
|
- host/render-surface implementation como adaptador local que sabe publicar em uma superficie real.
|
|
|
|
O `RenderManager` coordena pipelines e superficie, mas nao produz comandos de jogo/UI e nao deve conter detalhes de host desktop.
|
|
|
|
### 9. Command buffers e submissions sao conceitos diferentes
|
|
|
|
Cada dominio/pipeline acumula estado e comandos em seu proprio buffer mutavel durante o frame logico. Exemplos:
|
|
|
|
- `ComposerBuffer` para scene, camera e sprites;
|
|
- `Gfx2dBuffer` para primitivas 2D de jogo;
|
|
- `GfxUiBuffer` para primitivas de Shell UI;
|
|
- `ComposerBuffer` tambem cobre HUD do Game 2D no v1.
|
|
|
|
No fechamento do frame, o `RenderManager` transforma esses buffers na `RenderSubmission` valida para o `AppMode` atual.
|
|
|
|
Depois do fechamento, a submission e um snapshot fechado. Produtores logicos nao podem continuar mutando a submission fechada. Essa regra deve ser cravada agora porque e a base para VM e render pipeline rodarem em paralelo no futuro.
|
|
|
|
Politica de backlog: nao existe fila infinita. A regra canonica e `latest complete submission wins`.
|
|
|
|
## Opcoes
|
|
|
|
### Opcao A - Dois command sets tipados, uma implementacao Classic2D inicial
|
|
|
|
**Abordagem:**
|
|
|
|
- Criar `Game2DFramePacket` para scene/sprites/HUD.
|
|
- Criar `UiFramePacket` para Prometeu UI/system UI.
|
|
- Criar um envelope simples, por exemplo `RenderSubmission`, que identifica qual pacote esta sendo submetido.
|
|
- Fazer a implementacao Classic2D atual consumir os pacotes e continuar escrevendo no framebuffer RGBA8888.
|
|
- Implementar em fases: primeiro Game 2D, depois Prometeu UI, ou ambos com producers minimos se o plano ficar pequeno o suficiente.
|
|
|
|
**Pro:**
|
|
|
|
- preserva modelos logicos diferentes para jogo e UI;
|
|
- evita uma command list generica demais;
|
|
- prepara 3D ou outros pipelines sem forcar eles a parecerem com 2D;
|
|
- deixa claro que pipeline e backend sao coisas diferentes.
|
|
|
|
**Con:**
|
|
|
|
- cria mais tipos no inicio;
|
|
- precisa definir como o hardware recebe pacotes heterogeneos;
|
|
- se so Game 2D for migrado no primeiro plan, UI continua acoplada por um tempo.
|
|
|
|
**Maintainability:**
|
|
|
|
Alta. Esta opcao combina com a direcao de longo prazo sem exigir varios backends agora.
|
|
|
|
### Opcao B - Um `RenderCommand` universal para tudo
|
|
|
|
**Abordagem:**
|
|
|
|
- Criar uma display list unica com comandos como `Clear`, `DrawSprite`, `DrawText`, `FillRect`, `SceneCache`, `Window`, `Transition`.
|
|
- Fazer Game 2D e Prometeu UI emitirem a mesma lista.
|
|
|
|
**Pro:**
|
|
|
|
- facil de passar por uma unica fila;
|
|
- simples para logging/replay inicial;
|
|
- reduz o numero de tipos.
|
|
|
|
**Con:**
|
|
|
|
- tende a virar um denominador comum fraco;
|
|
- mistura semantica de jogo, UI de sistema e futuros pipelines;
|
|
- pode forcar o pipeline 3D futuro a um contrato 2D inadequado;
|
|
- aumenta chance de reabrir a arquitetura quando outro pipeline surgir.
|
|
|
|
**Maintainability:**
|
|
|
|
Media a baixa como arquitetura principal. Pode ser util internamente dentro de um pipeline, mas nao como contrato unico do runtime.
|
|
|
|
### Opcao C - Trait comum de pipeline, sem pacote explicito
|
|
|
|
**Abordagem:**
|
|
|
|
- Definir algo como `RenderPipeline` com metodo `render(&mut HardwareSurface)`.
|
|
- Game 2D e UI implementam a trait, mas continuam desenhando por callbacks imediatos.
|
|
|
|
**Pro:**
|
|
|
|
- pequena mudanca inicial;
|
|
- organiza nomes e ownership;
|
|
- reduz um pouco o acoplamento por modulo.
|
|
|
|
**Con:**
|
|
|
|
- nao cria pacote logico observavel;
|
|
- continua misturando producao e execucao;
|
|
- nao ajuda tanto render thread, replay, testes de comandos ou hardware alternativo.
|
|
|
|
**Maintainability:**
|
|
|
|
Insuficiente se virar a decisao final. Pode ser uma API auxiliar, mas nao substitui command packets.
|
|
|
|
### Opcao D - Definir todos os pipelines e backend abstraction agora
|
|
|
|
**Abordagem:**
|
|
|
|
- Criar pipeline registry, backend interfaces, CPU/GPU abstractions, surfaces, scheduling, command queues e talvez render thread.
|
|
|
|
**Pro:**
|
|
|
|
- parece completo no papel;
|
|
- antecipa muitos cenarios futuros.
|
|
|
|
**Con:**
|
|
|
|
- grande demais para o objetivo atual;
|
|
- alto risco de abstrair sem uso real;
|
|
- pode atrasar a estabilizacao do 2D atual;
|
|
- tende a introduzir nomes e contratos que depois precisarao ser quebrados.
|
|
|
|
**Maintainability:**
|
|
|
|
Baixa para o momento atual. Melhor deixar essa camada emergir depois de pelo menos dois pipelines reais funcionando.
|
|
|
|
## Sugestao / Recomendacao
|
|
|
|
A recomendacao atual e a Opcao A: definir dois pipelines logicos com command sets proprios e uma implementacao Classic2D inicial.
|
|
|
|
Modelo recomendado:
|
|
|
|
```text
|
|
Game2DPipeline
|
|
produces Game2DFramePacket
|
|
owns/uses FrameComposer concepts:
|
|
scene/cache/camera
|
|
sprites
|
|
game HUD
|
|
HUD/primitives
|
|
|
|
PrometeuUiPipeline
|
|
produces UiFramePacket
|
|
owns/uses system UI concepts:
|
|
home/hub
|
|
shell windows
|
|
panels/rects/text
|
|
focus/input visual state
|
|
|
|
RenderHardware / RenderSurface implementation
|
|
consumes typed submissions:
|
|
Game2D(Game2DFramePacket)
|
|
PrometeuUi(UiFramePacket)
|
|
future: Game3D(...), Custom2D(...), etc.
|
|
writes to current RGBA8888 framebuffer for now
|
|
|
|
RenderManager
|
|
owns current AppMode render routing
|
|
closes per-domain command buffers into a submission
|
|
manages mode transitions
|
|
keeps only the latest complete submission
|
|
owns publish/present policy through the render surface
|
|
```
|
|
|
|
O primeiro plano de execucao pode ser incremental:
|
|
|
|
1. Definir nomes e contratos dos pacotes sem criar backend registry.
|
|
2. Migrar o Game 2D path para `Game2DFramePacket -> Classic2D`.
|
|
3. Manter comportamento pixel-level identico.
|
|
4. Em seguida migrar Prometeu UI para `UiFramePacket -> Classic2D`.
|
|
5. So depois discutir outros backends, render thread ou 3D.
|
|
|
|
Se quisermos reduzir ainda mais risco, a decisao pode determinar que o primeiro PR implementa apenas o Game 2D packet, mas ja reserva a arquitetura e nomes para `UiFramePacket`. O importante e nao fingir que Prometeu UI e apenas "mais primitives gfx" dentro do pipeline de jogo.
|
|
|
|
## Riscos
|
|
|
|
- **Abstracao comum errada:** um command set universal pode parecer simples agora, mas virar bloqueio para UI e 3D depois.
|
|
- **Escopo grande demais:** migrar Game 2D, UI, firmware screens e host presentation em um unico PR aumenta risco de regressao visual.
|
|
- **Dual path permanente:** se `gfx_mut()` continuar como escape hatch normal, a fronteira de comandos nao vira contrato real.
|
|
- **Ownership/lifetime dos pacotes:** pacotes borrowed reduzem copia no v1; pacotes owned ajudam render thread futura. A decisao precisa declarar o alvo do primeiro passo.
|
|
- **HUD ambiguo:** HUD de jogo e UI do Prometeu precisam ficar separados por contrato, mesmo que ambos sejam 2D.
|
|
- **Present/publication:** `present()` precisa ser tratado como publicacao de superficie, nao como parte aleatoria de cada produtor logico.
|
|
- **Asset/cache leakage:** command packets devem referenciar recursos logicos/resolvidos sem copiar asset pipeline nem expor detalhes demais do `Gfx`.
|
|
- **Paralelismo futuro:** se o packet v1 depender de estado mutavel vivo da VM/hardware, uma render thread futura exigira nova quebra arquitetural. A submissao precisa parecer um snapshot fechado mesmo quando consumida sincronicamente no v1.
|
|
- **Transicoes entre modos:** se Shell e Game forem totalmente independentes sem uma coordenacao mestre, efeitos de transicao e manutencao de superficie ficam sem dono claro.
|
|
- **Backpressure:** render futuro nao deve acumular fila infinita. A politica aceita e manter somente a submissao completa mais recente.
|
|
- **Abstracao vs host:** `RenderManager` deve ser contrato runtime/abstracao de coordenacao. Host desktop/render surface deve ser implementacao local separada, sem vazar detalhes para os pipelines.
|
|
- **HUD ownership:** HUD nao deve ficar escondido dentro de `Gfx2D`. `Gfx2D` deve conter apenas primitivas. No v1, HUD pertence explicitamente ao `composer`.
|
|
|
|
## Arquivos / Areas Provavelmente Afetados em uma Plan Futura
|
|
|
|
Nucleo Game 2D:
|
|
|
|
- `crates/console/prometeu-hal/src/` para tipos compartilhados de packet/submission, se virarem contrato de hardware.
|
|
- `crates/console/prometeu-hal/src/lib.rs` para exportar novos modulos.
|
|
- `crates/console/prometeu-drivers/src/frame_composer.rs` para produzir `Game2DFramePacket`.
|
|
- `crates/console/prometeu-drivers/src/gfx.rs` para consumir `Game2DFramePacket` no Classic2D atual.
|
|
- `crates/console/prometeu-drivers/src/hardware.rs` para conectar pipeline/submission/implementacao.
|
|
- `crates/console/prometeu-hal/src/hardware_bridge.rs` para reduzir acesso direto a `GfxBridge` no fluxo de frame.
|
|
|
|
Nucleo Prometeu UI:
|
|
|
|
- `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`
|
|
- `crates/console/prometeu-system/src/services/windows/*`
|
|
- `crates/console/prometeu-firmware/src/firmware/firmware_step_splash_screen.rs`
|
|
- `crates/console/prometeu-firmware/src/firmware/firmware_step_crash_screen.rs`
|
|
- possivelmente um novo modulo de UI commands em `prometeu-hal` ou `prometeu-system`.
|
|
|
|
Possivel, mas deve ser minimizado no primeiro passo:
|
|
|
|
- `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs` se `gfx.*` primitives forem convertidas em command submission.
|
|
- `crates/console/prometeu-hal/src/gfx_bridge.rs` se a ponte antiga for estreitada.
|
|
- `crates/host/prometeu-host-desktop-winit/src/runner.rs` se o acesso ao framebuffer for encapsulado, mas host presentation idealmente fica igual no v1.
|
|
|
|
## Perguntas em Aberto
|
|
|
|
- [x] O primeiro plano deve implementar Game 2D e Prometeu UI juntos, ou apenas Game 2D com contrato preparado para UI?
|
|
- Resposta: faseado. O primeiro plano deve priorizar Game 2D, mas o contrato deve nomear Prometeu UI como pipeline separado desde o inicio.
|
|
- [x] O contrato comum deve ser um enum `RenderSubmission`, uma trait de submissao, ou uma fila tipada por pipeline?
|
|
- Resposta: `AppMode` e `RenderSubmission` devem andar juntos. `AppMode::Game` e `AppMode::Shell` podem ter cadencias e pipelines diferentes; alguns renderers pertencem a um modo e nao ao outro. O envelope inicial pode ser um `RenderSubmission` tipado por modo/pipeline, sem registry dinamico.
|
|
- [x] `Game2DFramePacket` deve incluir HUD de jogo no v1 ou apenas reservar o campo?
|
|
- Resposta: deve incluir HUD de jogo no v1. O pipeline 2D de jogos abrange scene, sprites e HUD.
|
|
- [x] `UiFramePacket` deve representar UI em comandos baixos (`rect`, `text`, `clip`) ou em comandos mais semanticos (`window`, `panel`, `button`)?
|
|
- Resposta: comandos de UI podem ser diferentes dos comandos Game 2D, mas widget/layout deve ficar fora da implementacao do host. No host, `UiFramePacket` pode ser reduzido a diretivas semelhantes ou equivalentes as primitivas finais de desenho.
|
|
- [x] Pacotes v1 devem ser borrowed, owned, ou hibridos?
|
|
- Resposta: hibridos. O modelo precisa suportar transicoes de modo, como clicar no jogo, sair da UI, abrir o jogo e alternar entre `Game` e `Shell`, sem exigir copia pesada de todo recurso.
|
|
- [x] Onde fica `present()` no novo modelo: no hardware/render surface, no consumidor Classic2D, ou temporariamente no firmware?
|
|
- Resposta: `present()` pertence a implementacao de hardware/render surface quando ela precisa publicar/trocar buffers. Ele faz sentido em um blit/double-buffer path como Game 2D, mas nao deve ser parte obrigatoria do path canonico de todos os pipelines.
|
|
- [x] O acesso publico a `gfx.*` deve virar submissao de comandos, ser mantido como debug overlay temporario, ou ser separado em outra discussao?
|
|
- Resposta: separar apenas as primitivas de desenho por contrato de pipeline. O que ja e `composer.*` deve continuar no dominio `composer`, porque scene, camera, sprites, HUD e orquestracao de frame sao um contrato mais alto nivel do Game 2D, nao primitivas `gfx2d`. `Gfx2D` deve conter somente primitivas. O atual `gfx.*` deve ser dividido em primitivas apropriadas para Game e Shell, por exemplo `gfx2d.*` para primitivas do Game 2D e `gfxui.*` para Prometeu UI/Shell. As stdlibs podem continuar expondo nomes de alto nivel como `gfx`, desde que apontem para syscalls diferentes por `AppMode`.
|
|
- [x] A agenda aberta `DSC-0011` de dirty regions deve depender desta fronteira antes de continuar?
|
|
- Resposta: sim. `DSC-0011` vem depois desta fronteira, para nao otimizar o acoplamento errado.
|
|
- [x] O v1 precisa implementar render thread?
|
|
- Resposta: nao. Mas o v1 deve preparar a fronteira para isso: `RenderSubmission` deve ser um snapshot fechado por `frame_id`/`AppMode`, sem exigir `&mut Hardware` ou framebuffer mutavel no produtor logico. O consumo pode continuar sincrono na primeira implementacao.
|
|
- [x] Quem e dono do frame builder?
|
|
- Resposta: cada dominio/pipeline deve ter seus proprios buffers de comando/estado. O fechamento do frame deve ser centralizado no host/render coordinator, que transforma esses buffers na `RenderSubmission` valida para o `AppMode` atual.
|
|
- [x] Qual e a ordem de composicao Game 2D?
|
|
- Resposta: scene e sprites intercalam por `layer` inteiro usando os 4 layers disponiveis do Game 2D, normalmente como `sprite -> scene -> sprite -> scene -> ...` conforme ordenacao por layer. Depois vem um layer de HUD sobre tudo e entao publish. Transicoes visuais devem pertencer ao `RenderManager`, nao ao Game 2D frame path.
|
|
- [x] Como lidar com transicoes Game/Shell?
|
|
- Resposta: a arquitetura precisa de um `RenderManager` acima dos pipelines. Ele gerencia troca de modo, manutencao da superficie, capacidades ativas e transicoes que nao pertencem integralmente nem ao Shell UI nem ao Game 2D.
|
|
- [x] Qual politica de backpressure para render paralelo futuro?
|
|
- Resposta: sem fila infinita. Manter somente a submissao completa mais recente.
|
|
- [x] Capabilities devem ser separadas?
|
|
- Resposta: sim. O contrato deve prever capabilities separadas para `composer`, `gfx2d` e `gfxui`, reforcando o isolamento por `AppMode`.
|
|
- [x] O host debug overlay deve continuar?
|
|
- Resposta: nao como parte desta arquitetura. O overlay atual pode ser removido por completo em uma execucao futura; se um console/debug UI voltar a ser necessario, deve ser rediscutido como produto proprio, nao como overlay host-owned herdado.
|
|
- [x] Fade deve permanecer em algum contrato?
|
|
- Resposta: nao. Fade deve sair completamente. Ele era uma ideia de hardware inicial e nao deve permanecer como campo de packet, syscall ou habito de implementacao. Transicoes visuais futuras pertencem ao `RenderManager`, nao a `composer`, `gfx2d` ou `gfxui`.
|
|
- [x] HUD deve ser dominio proprio ou parte do `composer`?
|
|
- Resposta: HUD fica dentro de `composer` no v1, por ser parte alta do frame Game 2D junto de scene, camera e sprites. `Gfx2D` continua limitado a primitivas.
|
|
|
|
## Criterio para Encerrar
|
|
|
|
Esta agenda pode virar decisao quando houver consenso sobre:
|
|
|
|
- quais pipelines existem no v1;
|
|
- qual command set pertence ao Game 2D;
|
|
- qual command set pertence a Prometeu UI;
|
|
- qual e a fronteira comum entre pipeline e implementacao de hardware/superficie;
|
|
- o que fica explicitamente fora de escopo;
|
|
- estrategia de migracao incremental sem mudanca visual;
|
|
- testes de equivalencia esperados.
|
|
|
|
## Discussion
|
|
|
|
Atualizacao de 2026-05-25:
|
|
|
|
O foco nao deve ser apenas "introduzir `RenderFramePacket` para Classic2D". O foco deve ser separar pipelines logicos por dominio. Game 2D e Prometeu UI podem ter modelos de comando distintos, mas ambos devem submeter comandos a uma implementacao de hardware/render surface.
|
|
|
|
A menor refatoracao segura provavelmente continua partindo do Game 2D, porque `FrameComposer` ja concentra scene/cache/sprites. Mas a decisao deve nomear Prometeu UI como pipeline separado desde agora, para evitar que a UI do sistema vire uma extensao acidental do pipeline de jogo.
|
|
|
|
Respostas fechadas em discussao:
|
|
|
|
- `AppMode::Game` e `AppMode::Shell` continuam sendo os modos canonicos atuais; nao ha rename para `System`.
|
|
- `RenderSubmission` deve ser coerente com `AppMode`, porque a atualizacao de frame e os renderers disponiveis podem diferir entre Game e Shell.
|
|
- `composer.*` deve continuar representando scene, camera, sprites, HUD e orquestracao de frame do Game 2D.
|
|
- `Gfx2D` deve representar apenas primitivas/drawing commands do pipeline Game 2D.
|
|
- `GfxUI` deve representar primitivas/drawing commands do pipeline Prometeu UI/Shell.
|
|
- As stdlibs PBS de Game e Shell podem usar nomes parecidos em alto nivel, inclusive `gfx`, mas devem mapear para dominios ABI diferentes conforme `AppMode`.
|
|
- O host/render implementation pode reduzir command sets diferentes a diretivas locais parecidas, mas widget/layout nao deve morar no host.
|
|
- `present()` e publicacao de superficie, nao parte obrigatoria de todo pipeline logico.
|
|
- `DSC-0011` deve aguardar esta fronteira.
|
|
- Render thread futura nao deve ser implementada agora, mas a fronteira deve nascer compativel com VM e renderer rodando em paralelo: submissions fechadas, leitura imutavel de recursos compartilhados e publicacao isolada na render surface.
|
|
- Buffers de comando/estado devem pertencer aos dominios/pipelines; o fechamento em `RenderSubmission` deve ser centralizado no `RenderManager`.
|
|
- `RenderManager` e abstracao/runtime contract; host/render-surface implementation e adaptador local separado.
|
|
- Game 2D intercalara scene e sprites por layer. HUD fica acima de tudo e pertence ao `composer` no v1, ainda com contrato minimo e evolutivo.
|
|
- Fade sai completamente. Transicoes de entrada/saida entre Shell e Game pertencem ao `RenderManager`.
|
|
- Backpressure futuro: latest complete submission wins.
|
|
- Capabilities devem ser separadas para `composer`, `gfx2d` e `gfxui`.
|
|
- O debug overlay host-owned atual nao deve ser preservado como requisito; pode ser removido quando a execucao chegar nessa area.
|
|
|
|
## Resolution
|
|
|
|
As perguntas principais de escopo foram respondidas. A agenda ainda precisa ser aceita explicitamente antes de virar decisao normativa.
|
|
|
|
## Next Step
|
|
|
|
Fechar as perguntas sobre escopo do v1. Se a direcao de dois pipelines logicos for aceita, transformar esta agenda em uma decisao normativa antes de qualquer plan ou alteracao de codigo.
|