[PERF] Async Background Work Lanes for Assets and FS
This commit is contained in:
+518
-46
@@ -2,84 +2,556 @@
|
||||
id: AGD-0008
|
||||
ticket: perf-async-background-work-lanes-for-assets-and-fs
|
||||
title: Agenda - [PERF] Async Background Work Lanes for Assets and FS
|
||||
status: open
|
||||
status: accepted
|
||||
created: 2026-03-27
|
||||
resolved:
|
||||
decision:
|
||||
tags: []
|
||||
resolved: 2026-06-28
|
||||
decision: DEC-0034
|
||||
tags: [perf, asset, fs, async, scheduler, runtime]
|
||||
---
|
||||
|
||||
# Agenda - [PERF] Async Background Work Lanes for Assets and FS
|
||||
|
||||
## Contexto
|
||||
|
||||
Depois das decisoes de render worker, a concorrencia de render saiu do escopo
|
||||
desta agenda. O problema restante e a lane de trabalho assincrono para IO,
|
||||
decode e persistencia.
|
||||
|
||||
O modelo de execucao que queremos discutir agora assume uma terceira core/lane
|
||||
dedicada a trabalhos assincronos de runtime:
|
||||
|
||||
```text
|
||||
Core/lane 1: VM, firmware, SystemOS e frame logico
|
||||
Core/lane 2: render worker / rasterizacao assincrona
|
||||
Core/lane 3: async work lane para asset IO/decode e possivelmente FS
|
||||
```
|
||||
|
||||
Essa terceira lane nao deve virar um pool grande e solto. A intencao e ter uma
|
||||
fila previsivel, com capacidade limitada, telemetria e regras de saturacao.
|
||||
|
||||
Para assets, a necessidade e concreta: `asset.load()` ainda cria uma thread do
|
||||
SO por requisicao. Para FS, a motivacao provavel era evitar que operacoes de
|
||||
leitura/escrita/listagem/delete, hoje chamadas de forma sincrona pelo dispatch,
|
||||
roubem tempo do frame quando o backend real envolver IO. Precisamos verificar
|
||||
se FS deve usar a mesma lane agora ou apenas reservar compatibilidade.
|
||||
|
||||
## Problema
|
||||
|
||||
`asset.load()` hoje cria uma thread do SO por requisicao. Ao mesmo tempo, `fs` ainda nao tem uma politica clara para sync assincrono barato em hardware simples.
|
||||
`asset.load()` hoje dispara `thread::spawn` por requisicao de asset nao
|
||||
residente. Isso escala mal, cria jitter e deixa o runtime sem uma politica
|
||||
unica de backpressure.
|
||||
|
||||
O projeto precisa de paralelismo para IO/decode/sync, mas o target inclui handheld DIY e hardware barato, onde um pool grande ou explosao de threads pode piorar a latencia em vez de melhorar.
|
||||
O dominio `fs` tambem tem operacoes potencialmente bloqueantes (`read`,
|
||||
`write`, `list_dir`, `delete`, memcard commit/read/write) e a tabela de
|
||||
syscalls ja as marca como nao deterministicas/custosas. Ainda assim, a
|
||||
implementacao atual executa essas chamadas diretamente no caminho de dispatch.
|
||||
|
||||
## Dor
|
||||
Sem um contrato explicito, cada dominio pode inventar sua propria concorrencia:
|
||||
asset criando threads, FS bloqueando o frame, e memcard herdando comportamento
|
||||
acidental do backend.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
- `thread::spawn` por request escala mal e cria jitter.
|
||||
- assets e `fs` competem por IO sem uma politica unica de fila/prioridade.
|
||||
- sem lane dedicada, operacoes de background tendem a vazar custo para o main loop.
|
||||
- sem disciplina, o host desktop vira referencia errada para hardware fraco.
|
||||
- A terceira core/lane deve ser um recurso de plataforma controlado, nao uma
|
||||
permissao geral para criar threads.
|
||||
- Asset loading precisa de um pool/fila limitada para multiplos loads
|
||||
pendentes.
|
||||
- FS pode justificar a mesma lane quando envolver IO real, mas nao devemos
|
||||
assinar uma API assincrona ampla sem entender a semantica de retorno.
|
||||
- Commit/install em bancos residentes pode ter restricoes de determinismo e
|
||||
ownership; decode pode ser assincrono, mas publicacao/instalacao talvez tenha
|
||||
que cruzar de volta para a lane principal.
|
||||
- A estrategia precisa funcionar em hardware alvo com poucos cores e tambem no
|
||||
host desktop sem transformar desktop em referencia de custo errada.
|
||||
- Render worker ja tem seu proprio contrato e nao deve compartilhar essa lane.
|
||||
|
||||
## Hotspots Atuais
|
||||
|
||||
- [asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs#L353)
|
||||
- [tick.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs#L53)
|
||||
- [runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs#L315)
|
||||
- [asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs#L438) - `AssetManager::load`.
|
||||
- [asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs#L507) - `thread::spawn` por load.
|
||||
- [fs.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/syscalls/domains/fs.rs#L4) - `fs` e `mem` marcados como superficies custosas/nao deterministicas.
|
||||
- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs#L549) - chamadas `fs.*` executam no dispatch.
|
||||
- [virtual_fs.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/services/fs/virtual_fs.rs#L69) - VFS normaliza path e chama backend diretamente.
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Fechar um modelo de execucao assincrona para `asset` e `fs` que seja previsivel em hardware simples.
|
||||
Fechar um modelo de terceira core/lane para trabalho assincrono de runtime,
|
||||
comecando por asset loading e avaliando se FS deve entrar na mesma lane no v1.
|
||||
|
||||
O alvo nao e criar multitarefa geral, callbacks para guest, ou um scheduler
|
||||
paralelo da VM. A lane deve executar trabalho de IO/decode/sync e publicar
|
||||
resultados observaveis por status/polling em pontos previsiveis.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Topologia de workers.
|
||||
Escolher entre:
|
||||
- uma thread dedicada para `asset` e outra para `fs`;
|
||||
- um worker unico multiplexando filas;
|
||||
- um pool minimo e fixo;
|
||||
- proibicao explicita de `spawn` por request.
|
||||
1. Topologia da terceira lane.
|
||||
Definir:
|
||||
- uma async work lane dedicada, separada da VM e do render worker;
|
||||
- se a lane e uma thread fixa no host e uma core dedicada no hardware alvo;
|
||||
- fallback quando nao houver core fisico dedicado;
|
||||
- proibicao explicita de `thread::spawn` por request no caminho normal.
|
||||
|
||||
2. Separacao por dominio.
|
||||
Decidir se `asset` e `fs` compartilham scheduler/fila ou se cada dominio tem lane propria.
|
||||
2. Pool/fila de asset loading.
|
||||
Definir:
|
||||
- backlog de pedidos sem limite operacional fixo;
|
||||
- exatamente um job ativo por vez na lane;
|
||||
- o "pool" significa backlog e estados de job, nao multiplos workers reais;
|
||||
- politica de substituicao/cancelamento para pedidos que miram o mesmo
|
||||
bank/slot;
|
||||
- status para pending/backlog, ativo, progresso, cancelamento, erro de
|
||||
decode e sucesso.
|
||||
|
||||
3. Politica de prioridade.
|
||||
3. Fases do asset load.
|
||||
Separar:
|
||||
- request e alocacao de handle;
|
||||
- leitura de bytes;
|
||||
- decode/materializacao;
|
||||
- staging de resultado;
|
||||
- install/commit em banco residente.
|
||||
|
||||
Ponto a fechar: quais fases rodam na terceira lane e quais voltam para a
|
||||
lane principal por determinismo/ownership.
|
||||
|
||||
4. Inclusao de FS na mesma lane.
|
||||
Verificar se `fs` deve usar a terceira lane no v1 para:
|
||||
- leituras grandes;
|
||||
- escritas;
|
||||
- listagem;
|
||||
- delete;
|
||||
- memcard commit/read/write.
|
||||
|
||||
Ponto a fechar: FS sync publico continua bloqueante/status-first, vira
|
||||
request/poll, ou ganha apenas uma implementacao interna que drena trabalho em
|
||||
pontos de frame.
|
||||
|
||||
5. Separacao por dominio.
|
||||
Decidir se `asset` e `fs` compartilham uma fila com classes de prioridade ou
|
||||
se a terceira lane contem subfilas dedicadas.
|
||||
|
||||
6. Politica de prioridade.
|
||||
Definir:
|
||||
- prioridade de loads visuais vs audio;
|
||||
- prioridade de sync de save/config;
|
||||
- limite de trabalho por frame para install/commit.
|
||||
- prioridade de save/config;
|
||||
- prioridade de memcard commit;
|
||||
- starvation prevention;
|
||||
- limite de trabalho de instalacao/publicacao por frame.
|
||||
|
||||
4. Modelo de retorno.
|
||||
Fechar como o guest observa backlog, cancelamento e saturacao:
|
||||
- status imediato de fila cheia;
|
||||
- status de pending;
|
||||
- metrica de backlog;
|
||||
- politica de cancelamento.
|
||||
7. Modelo de retorno e telemetria.
|
||||
Fechar como guest/runtime observa:
|
||||
- `pending`;
|
||||
- `loading`;
|
||||
- `ready`;
|
||||
- `canceled`;
|
||||
- `backend_unavailable`;
|
||||
- backlog;
|
||||
- posicao de um asset no backlog;
|
||||
- progresso percentual do asset ativo;
|
||||
- drops/retries quando aplicavel.
|
||||
|
||||
5. Orçamento para hardware barato.
|
||||
Definir quantas threads o runtime pode assumir como baseline.
|
||||
8. Orcamento para hardware barato.
|
||||
Definir o baseline:
|
||||
- VM principal;
|
||||
- render worker;
|
||||
- terceira async work lane;
|
||||
- limites de memoria para jobs pendentes e buffers temporarios.
|
||||
|
||||
## Open Questions de Arquitetura
|
||||
## Opcoes
|
||||
|
||||
1. O v1 precisa de lanes separadas para `asset` e `fs` ou basta uma fila central com classes de prioridade?
|
||||
2. Decode de asset fica no mesmo worker do IO ou em fase distinta?
|
||||
3. Commit/install no device continua no main thread por determinismo?
|
||||
### Opcao A - Terceira lane unica com subfilas e pool limitado de assets
|
||||
|
||||
- **Abordagem:** criar uma async work lane dedicada. Assets usam um pool/fila
|
||||
de jobs nessa lane; FS tambem pode submeter jobs na mesma lane, com
|
||||
prioridade menor ou classe separada.
|
||||
- **Pro:** modelo simples de budget; evita explosao de threads; encaixa no alvo
|
||||
de terceira core; permite compartilhar backpressure e telemetria.
|
||||
- **Contra:** assets e FS podem competir por IO; precisa politica clara para
|
||||
evitar que save/config fique atras de loads longos.
|
||||
- **Manutenibilidade:** boa se a lane tiver tipos de job e estados explicitos.
|
||||
|
||||
### Opcao B - Lane de assets agora, FS apenas reservado
|
||||
|
||||
- **Abordagem:** fechar v1 somente para asset loading, removendo `spawn` por
|
||||
request. FS continua sincrono por enquanto, mas o contrato da lane reserva
|
||||
compatibilidade para FS no futuro.
|
||||
- **Pro:** menor escopo; resolve a dor concreta de assets rapidamente; evita
|
||||
alterar semantica de FS antes da agenda de app home filesystem.
|
||||
- **Contra:** nao resolve stalls reais de FS/memcard; pode exigir refatorar a
|
||||
lane depois para aceitar FS.
|
||||
- **Manutenibilidade:** boa no curto prazo, com risco de segunda migracao.
|
||||
|
||||
### Opcao C - Lanes separadas para asset e FS
|
||||
|
||||
- **Abordagem:** criar uma lane/pool para assets e outra para FS.
|
||||
- **Pro:** isolamento forte; FS/save nao compete diretamente com loads de
|
||||
textura/audio/cena.
|
||||
- **Contra:** consome mais threads/cores; contraria a premissa de terceira core
|
||||
unica; pior para hardware simples.
|
||||
- **Manutenibilidade:** media; isolamento ajuda, mas a topologia fica pesada.
|
||||
|
||||
### Opcao D - Pool global pequeno sem nocao de terceira lane
|
||||
|
||||
- **Abordagem:** trocar `spawn` por request por um pool global fixo.
|
||||
- **Pro:** simples de implementar em host desktop.
|
||||
- **Contra:** perde a arquitetura de lanes por core; pode mascarar custo em
|
||||
desktop; fica menos claro como mapear para hardware alvo.
|
||||
- **Manutenibilidade:** baixa para o modelo de console se virar dependencia
|
||||
acidental de scheduler do SO.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Recomendo seguir com a Opcao A como direcao de arquitetura, mas fechar a
|
||||
decisao em duas camadas:
|
||||
|
||||
1. Contrato obrigatorio agora:
|
||||
- terceira async work lane como recurso runtime;
|
||||
- assets deixam de usar `thread::spawn` por requisicao;
|
||||
- asset loading passa por backlog consultavel/reordenavel;
|
||||
- status, progresso e telemetria de backlog ficam explicitos.
|
||||
|
||||
2. Contrato condicionado para FS:
|
||||
- FS deve ser analisado como consumidor legitimo da mesma lane porque suas
|
||||
operacoes podem envolver IO real e ja sao custosas/nao deterministicas;
|
||||
- a decisao precisa escolher entre incluir FS no v1 ou reservar a lane para
|
||||
FS sem mudar ainda a superficie publica;
|
||||
- memcard precisa ser considerado junto com FS, porque usa a mesma
|
||||
capacidade e backend de persistencia.
|
||||
|
||||
O ponto importante: a terceira core/lane deve ser a unidade de concorrencia.
|
||||
O pool de assets deve existir dentro desse modelo, nao como criacao livre de
|
||||
threads por load.
|
||||
|
||||
## Respostas Consolidadas Ate Aqui
|
||||
|
||||
1. O pool de assets deve ser uma lane serial.
|
||||
- Ha exatamente um job ativo na async work lane.
|
||||
- O pool representa backlog, estados e controle de ordem, nao multiplos
|
||||
workers executando em paralelo.
|
||||
|
||||
2. O backlog de pedidos deve ser semanticamente ilimitado.
|
||||
- Nao existe `queue_full` como status normal do dominio.
|
||||
- Como cada pedido mira um `bank_type/slot` e pedidos novos para o mesmo
|
||||
alvo substituem os anteriores, o backlog efetivo fica limitado pela soma
|
||||
dos slots dos bancos.
|
||||
- O contrato nao precisa expor limite de fila, mas a implementacao deve
|
||||
garantir que metadados de handles cancelados/superseded nao crescam sem
|
||||
coleta.
|
||||
|
||||
3. Asset loading precisa expor consulta e reordenacao do backlog.
|
||||
- Deve existir API publica/runtime para consultar onde um asset esta no
|
||||
backlog.
|
||||
- Deve existir capacidade de adiantar ou atrasar um pedido de asset na fila.
|
||||
- O asset ativo deve expor progresso percentual.
|
||||
- Requests novos para o mesmo `bank_type/slot` devem cancelar pedidos
|
||||
anteriores pendentes para aquele alvo, evitando carregar asset que ja foi
|
||||
substituido antes de executar.
|
||||
- Se o alvo ja estiver carregado com o mesmo `asset_id`, o novo request nao
|
||||
entra no backlog; ele retorna imediatamente pronto com handle disponivel.
|
||||
- Se um novo request substituir o alvo atualmente ativo, a lane deve cancelar
|
||||
em ponto cooperativo quando possivel; se o trabalho nao puder ser
|
||||
interrompido, o resultado antigo deve ser descartado ao final por geracao
|
||||
superseded.
|
||||
- `superseded` significa que um request foi substituido por outro request
|
||||
mais novo para o mesmo `bank_type/slot`. Nao e erro e nao e cancelamento
|
||||
manual; e obsolescencia operacional do pedido antigo.
|
||||
- Handles representam o slot do bank como alvo estavel. Dentro do estado do
|
||||
handle deve existir uma secao de request/backlog para aquele slot,
|
||||
informando se ha pedido pendente/ativo, qual asset foi solicitado,
|
||||
progresso, posicao e geracao.
|
||||
- Handles devem ser capazes de consultar o estado do alvo `bank_type/slot`
|
||||
a qualquer momento. Se nao houver asset valido carregado e tambem nao
|
||||
houver request pendente para aquele alvo, a consulta deve retornar estado
|
||||
explicito de vazio/invalido, nao falhar por ausencia de request ativo.
|
||||
|
||||
4. Decode/materializacao fria rodam na terceira lane.
|
||||
- Leitura e decode de asset podem acontecer fora da lane principal.
|
||||
- O resultado deve voltar como material pronto/staged.
|
||||
|
||||
5. Install/commit em bancos residentes continua na lane principal.
|
||||
- A async lane prepara trabalho.
|
||||
- A lane principal publica/instala em pontos previsiveis por ownership,
|
||||
determinismo e integracao com bancos/render/audio.
|
||||
|
||||
6. FS e memcard entram como consumidores possiveis da mesma lane, mas precisam
|
||||
ser melhor amarrados com a agenda de app home filesystem.
|
||||
- A `DSC-0007` / `AGD-0006` deve ser ajustada para estabelecer melhor a
|
||||
superficie publica e o modelo async/sync de FS.
|
||||
- Esta agenda deve afirmar a existencia da lane para trabalhos async de IO
|
||||
desse tipo e permitir que FS a consuma.
|
||||
- Questoes de API publica de FS, request/poll e semantica de app home devem
|
||||
ficar a cargo da agenda 6.
|
||||
- FS, memcard e assets nao devem operar sobrepostos quando isso gerar
|
||||
concorrencia real de backend; se houver competicao, a fila unica resolve a
|
||||
ordem.
|
||||
|
||||
7. Prioridade quando houver competicao:
|
||||
- memcard commit/write;
|
||||
- FS write/config;
|
||||
- asset visual/audio load;
|
||||
- list/read nao critico.
|
||||
|
||||
8. Status-first continua valendo.
|
||||
- `backend_unavailable`, `canceled`, erro de decode e estados de job sao
|
||||
status operacionais.
|
||||
- Cancelamento por superseding de pedido no mesmo bank/slot e resultado
|
||||
operacional normal, nao fault.
|
||||
- Nao ha `queue_full` no contrato esperado.
|
||||
- Trap permanece para violacao estrutural, como argumento invalido,
|
||||
capability ausente ou handle estruturalmente invalido.
|
||||
|
||||
9. Telemetria minima:
|
||||
- backlog atual;
|
||||
- posicao por asset;
|
||||
- progresso percentual do asset ativo;
|
||||
- jobs submetidos, concluidos, falhos e cancelados;
|
||||
- tempo por job;
|
||||
- percentis por asset enquanto estiver carregando na lane.
|
||||
|
||||
10. Escopo da agenda.
|
||||
- O foco desta agenda e a lane, assets e memcard/game persistence.
|
||||
- FS entra como consumidor permitido da lane de IO, mas as decisoes de API
|
||||
publica de FS pertencem a `AGD-0006`.
|
||||
|
||||
11. API de backlog.
|
||||
- A API inicial sugerida cobre os casos esperados.
|
||||
- `asset.backlog_promote(handle)` deve ser mantido como atalho oficial para
|
||||
`asset.backlog_move(handle, 1)`.
|
||||
- `asset.backlog_demote(handle)` deve ser mantido como atalho oficial para
|
||||
mover o pedido para o fim dos pendentes.
|
||||
- Os atalhos nao criam semantica nova; apenas evitam que o caller calcule
|
||||
posicoes comuns.
|
||||
- O handle deve permitir consulta estavel do slot do bank mesmo quando nao ha
|
||||
asset valido carregado.
|
||||
- O estado do handle deve separar:
|
||||
- estado do slot/residencia atual;
|
||||
- estado do request/backlog atual para aquele slot.
|
||||
- Operacoes que mudam estado, como commit/cancel/reorder, atuam sobre a
|
||||
secao de request/backlog do handle e precisam validar geracao/request atual
|
||||
para nao agir sobre um pedido substituido.
|
||||
|
||||
12. Cancelamento por substituicao.
|
||||
- Quando um request novo chega para o mesmo `bank_type/slot`, o request
|
||||
anterior e marcado imediatamente como `superseded`.
|
||||
- Se o request anterior ainda estiver no backlog, ele sai da fila.
|
||||
- Se o request anterior estiver ativo, a lane tenta cancelar
|
||||
cooperativamente quando a fase atual permitir.
|
||||
- Se a fase ativa nao puder ser interrompida com baixo custo, ela termina e
|
||||
o resultado e descartado ao final porque a geracao do alvo ja mudou.
|
||||
- Como o handle pertence ao slot do bank, ele continua consultavel; sua
|
||||
secao de request deve indicar que a geracao anterior foi `superseded` ou
|
||||
que nao ha request ativo para aquele alvo.
|
||||
|
||||
13. Fases de progresso.
|
||||
- `read/decode/stage` e suficiente como modelo minimo para `GLYPH`, `SOUND`
|
||||
e `SCENE`.
|
||||
- Subfases futuras podem detalhar progresso dentro de `decode` sem mudar o
|
||||
contrato geral.
|
||||
|
||||
14. Percentis.
|
||||
- Percentis devem existir por `bank_type` como telemetria principal.
|
||||
- Percentis por `asset_id` tambem sao uteis, mas podem usar janela pequena
|
||||
ou agregador leve.
|
||||
- Percentis sao atualizados no fechamento do job, nao durante o hot path.
|
||||
|
||||
15. Ajuste esperado na agenda de FS.
|
||||
- `AGD-0006` deve registrar que existe uma async IO lane compartilhavel por
|
||||
FS/memcard/assets.
|
||||
- Esta agenda so decide que FS pode consumir a lane.
|
||||
- A API publica de FS, incluindo request/poll ou sync aparente, pertence a
|
||||
`AGD-0006`.
|
||||
|
||||
## API Inicial Sugerida Para Assets
|
||||
|
||||
Esta agenda ainda nao fecha nomes finais de ABI, mas a direcao inicial sugerida
|
||||
e manter `asset.load/status/commit/cancel` e adicionar uma superficie pequena
|
||||
para backlog:
|
||||
|
||||
1. `asset.backlog_info() -> (status, pending_count, active_handle, active_asset_id, active_bank_type, active_slot, active_progress)`
|
||||
- Consulta o estado geral da lane de assets.
|
||||
- `active_progress` usa escala inteira, preferencialmente `0..10000` para
|
||||
permitir duas casas decimais sem float.
|
||||
|
||||
2. `asset.backlog_position(handle) -> (status, state, position, progress)`
|
||||
- Consulta um pedido especifico.
|
||||
- `position = 0` significa job ativo.
|
||||
- `position > 0` significa posicao no backlog.
|
||||
- `position = -1` pode representar nao enfileirado/pronto/cancelado,
|
||||
dependendo do `state`.
|
||||
|
||||
3. `asset.backlog_move(handle, new_position) -> status`
|
||||
- Move um pedido pendente para uma posicao absoluta.
|
||||
- `new_position = 1` significa primeiro pendente depois do ativo.
|
||||
- Nao interrompe diretamente o job ativo; substituicao do mesmo
|
||||
`bank_type/slot` usa a regra de superseding.
|
||||
|
||||
4. `asset.backlog_promote(handle) -> status`
|
||||
- Atalho para mover o pedido para a frente do backlog pendente.
|
||||
|
||||
5. `asset.backlog_demote(handle) -> status`
|
||||
- Atalho para mover o pedido para o fim do backlog pendente.
|
||||
|
||||
6. `asset.target_status(bank_type, slot) -> (status, asset_id, handle, state, position, progress)`
|
||||
- Consulta por alvo operacional, que e o que realmente controla superseding.
|
||||
- Ajuda quando o caller quer saber "o que esta programado para este slot".
|
||||
|
||||
Estados sugeridos para `state`:
|
||||
|
||||
- `empty`;
|
||||
- `invalid`;
|
||||
- `queued`;
|
||||
- `active`;
|
||||
- `ready`;
|
||||
- `committed`;
|
||||
- `canceled`;
|
||||
- `superseded`;
|
||||
- `error`;
|
||||
- `backend_unavailable`.
|
||||
|
||||
Regra de design: APIs de backlog sao operacionais e status-first. Reordenar um
|
||||
handle inexistente, ja concluido ou ja superseded retorna status operacional
|
||||
apropriado quando o handle e conhecido; violações estruturais continuam Trap.
|
||||
|
||||
Handles sao observaveis e representam slots de banks. Um handle conhecido pode
|
||||
ser consultado mesmo quando o slot alvo nao contem asset valido carregado; nesse
|
||||
caso a consulta deve retornar estado como `empty` ou `invalid`.
|
||||
|
||||
O estado do handle deve conter pelo menos duas partes:
|
||||
|
||||
```text
|
||||
slot_state:
|
||||
loaded_asset_id
|
||||
resident_state
|
||||
|
||||
request_state:
|
||||
requested_asset_id
|
||||
generation
|
||||
queued/active/ready/canceled/superseded/error
|
||||
backlog_position
|
||||
progress
|
||||
```
|
||||
|
||||
Mutacoes seguem regras mais estritas e devem falhar operacionalmente quando a
|
||||
secao de request/backlog do handle nao representa a geracao atual.
|
||||
|
||||
## Progresso e Percentis
|
||||
|
||||
### Progresso percentual
|
||||
|
||||
Sugestao:
|
||||
|
||||
- usar progresso em base inteira `0..10000`;
|
||||
- quando o tamanho total de bytes for conhecido, calcular progresso por fases
|
||||
ponderadas;
|
||||
- quando o decode nao for linear ou nao houver tamanho confiavel, expor
|
||||
progresso por fase com marcos conservadores.
|
||||
|
||||
Modelo inicial de fases:
|
||||
|
||||
```text
|
||||
queued -> 0
|
||||
read -> 0..4000
|
||||
decode -> 4000..9000
|
||||
stage -> 9000..10000
|
||||
ready -> 10000
|
||||
```
|
||||
|
||||
Se uma fase nao consegue reportar progresso interno, ela deve manter o ultimo
|
||||
marco e saltar para o proximo marco ao concluir. Isso evita progresso falso
|
||||
sem perder visibilidade de fase.
|
||||
|
||||
### Percentis por asset
|
||||
|
||||
Sugestao:
|
||||
|
||||
- registrar duracoes por asset no fim de cada job, nao por tick/frame;
|
||||
- manter agregadores pequenos por `asset_id` e por `bank_type`;
|
||||
- calcular percentis a partir de janela/ring buffer pequeno ou histograma
|
||||
barato por bucket de duracao;
|
||||
- nunca atualizar percentis no loop quente de decode por item/pixel;
|
||||
- o job ativo pode expor tempo decorrido e fase atual; percentis sao atualizados
|
||||
apenas no fechamento do job.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- [x] A agenda esta madura para virar decisao normativa ou ainda falta algum
|
||||
caso de asset/memcard/lane?
|
||||
- [x] A estrutura minima de `slot_state` e `request_state` no handle esta
|
||||
completa ou falta algum campo para commit/cancel/reorder seguro?
|
||||
|
||||
## Resolucao
|
||||
|
||||
A agenda esta madura para decisao normativa.
|
||||
|
||||
A decisao deve formalizar:
|
||||
|
||||
- a terceira async work lane serial;
|
||||
- um job ativo por vez;
|
||||
- backlog efetivamente limitado pela unicidade de `bank_type/slot`;
|
||||
- handles como observadores estaveis de slots de bank;
|
||||
- `slot_state` e `request_state` dentro do handle;
|
||||
- cancelamento/superseding por novo request para o mesmo alvo;
|
||||
- load pronto imediato quando o asset ja esta residente no alvo;
|
||||
- decode/materializacao na lane async;
|
||||
- commit/install na lane principal;
|
||||
- memcard como consumidor prioritario da mesma lane;
|
||||
- FS como consumidor permitido, deixando API publica de FS para `AGD-0006`;
|
||||
- progresso por fases e percentis atualizados no fechamento do job.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- `../specs/09-events-and-concurrency.md`
|
||||
- `../specs/15-asset-management.md`
|
||||
- `../specs/16a-syscall-policies.md`
|
||||
- `014-app-home-filesystem-surface-and-semantics.md`
|
||||
- `docs/specs/runtime/09-events-and-concurrency.md`
|
||||
- `docs/specs/runtime/15-asset-management.md`
|
||||
- `docs/specs/runtime/16a-syscall-policies.md`
|
||||
- `discussion/workflow/agendas/AGD-0006-app-home-filesystem-surface-and-semantics.md`
|
||||
|
||||
## Criterio de Saida Desta Agenda
|
||||
## Criterio para Encerrar
|
||||
|
||||
Pode virar PR quando houver decisao escrita sobre:
|
||||
|
||||
- numero e tipo de workers aceitos no baseline;
|
||||
- fila/prioridade de `asset` e `fs`;
|
||||
- proibicao ou aceitacao limitada de `thread::spawn` por request;
|
||||
- modelo de status/telemetria para backlog e saturacao.
|
||||
- existencia e papel da terceira async work lane;
|
||||
- relacao dessa lane com a terceira core no hardware alvo e fallback no host;
|
||||
- desenho do backlog serial de asset loading;
|
||||
- regra de cancelamento/substituicao para requests no mesmo bank/slot;
|
||||
- proibicao de `thread::spawn` por load no caminho normal;
|
||||
- fases de asset load que rodam na lane vs lane principal;
|
||||
- inclusao condicionada de FS/memcard nessa mesma lane;
|
||||
- API de consulta e reordenacao do backlog de assets;
|
||||
- comportamento de request imediato quando o asset ja esta residente no alvo;
|
||||
- regra de bounded backlog por unicidade de `bank_type/slot`;
|
||||
- politica de prioridade entre asset, FS e memcard;
|
||||
- status e telemetria para backlog, progresso, percentis, cancelamento e falha.
|
||||
|
||||
## Discussao
|
||||
|
||||
- 2026-06-28: Agenda atualizada para remover render worker do escopo, assumir
|
||||
uma terceira core/lane para trabalhos assincronos, exigir pool/fila limitada
|
||||
para asset loading e reavaliar o papel de FS/memcard como consumidores da
|
||||
mesma lane.
|
||||
- 2026-06-28: Discussao consolidou que a async work lane deve ser serial, com
|
||||
um job ativo, backlog semanticamente ilimitado, consulta/reordenacao publica
|
||||
de backlog de assets, progresso percentual do asset ativo, decode na lane
|
||||
async, install/commit na lane principal, e FS/memcard como consumidores a
|
||||
alinhar com a agenda de app home filesystem.
|
||||
- 2026-06-28: Acrescentada regra de asset pipe: requests para o mesmo bank/slot
|
||||
devem cancelar pedidos anteriores pendentes para aquele alvo, tratando o
|
||||
pedido mais novo como substituto operacional.
|
||||
- 2026-06-28: Discussao refinou que o alvo canonico e `bank_type/slot`; um
|
||||
asset ja residente deve retornar handle pronto sem entrar no backlog; o
|
||||
backlog efetivo e limitado pela soma dos slots dos bancos; FS fica como
|
||||
consumidor permitido da lane, enquanto API publica de FS permanece na agenda
|
||||
6; progresso deve usar fases conservadoras e percentis devem ser atualizados
|
||||
no fechamento do job, nao no hot path.
|
||||
- 2026-06-28: Open questions restantes foram consolidadas: API de backlog
|
||||
aceita com `promote/demote` como atalhos; superseding marca requests
|
||||
substituidos por outro request para o mesmo `bank_type/slot`; cancelamento do
|
||||
ativo e cooperativo quando barato e descarte por geracao quando nao for;
|
||||
`read/decode/stage` cobre GLYPH/SOUND/SCENE; percentis ficam por `bank_type`
|
||||
e por `asset_id`; API publica de FS permanece em `AGD-0006`.
|
||||
- 2026-06-28: Adicionada a expectativa de que handles possam consultar o alvo
|
||||
`bank_type/slot` a qualquer momento, inclusive quando nao houver asset valido
|
||||
carregado; mutacoes devem continuar protegidas por request/geracao para evitar
|
||||
commit/cancel acidental de pedidos substituidos.
|
||||
- 2026-06-28: Refinado o modelo de handle: o handle pertence ao slot do bank e
|
||||
contem uma secao de estado de request/backlog para aquele slot. Consulta e
|
||||
residencia ficam estaveis por alvo; mutacoes atuam sobre a geracao atual do
|
||||
request dentro do handle.
|
||||
|
||||
@@ -1,409 +0,0 @@
|
||||
---
|
||||
id: AGD-0010
|
||||
ticket: perf-gfx-render-pipeline-and-dirty-regions
|
||||
title: Agenda - [PERF] GFX Render Pipeline and Dirty Regions
|
||||
status: open
|
||||
created: 2026-03-27
|
||||
resolved:
|
||||
decision:
|
||||
tags: []
|
||||
---
|
||||
|
||||
# Agenda - [PERF] GFX Render Pipeline and Dirty Regions
|
||||
|
||||
## Problema
|
||||
|
||||
O renderer `gfx` recompõe a cena inteira a cada frame logico, mesmo quando a mudanca visual e pequena.
|
||||
|
||||
Hoje `render_all()` reconstrói buckets de sprites, escaneia os 512 sprites, redesenha layers e aplica dois passes fullscreen de fade sem politica de invalidacao.
|
||||
|
||||
Ao mesmo tempo, a arquitetura atual ja opera como um framebuffer destrutivo em memoria: draws escrevem diretamente no buffer de trabalho e operacoes posteriores sobrescrevem o que estiver por baixo. A discussao nao e migrar para um modelo tipo GPU, scene graph ou retained rendering.
|
||||
|
||||
Existe ainda um driver de produto importante: o objetivo continua sendo viabilizar hardware handheld proprio com limitacoes reais de orcamento e com economia de memoria o mais agressiva possivel. Isso significa que ganhos de CPU nao podem ser avaliados isoladamente; custo de RAM adicional, buffers extras e estruturas auxiliares entram diretamente no criterio de aceitacao.
|
||||
|
||||
## Dor
|
||||
|
||||
- custo visual basico cresce demais para hardware simples.
|
||||
- pequenos updates pagam preco de full redraw.
|
||||
- fade, HUD e world composition ficam sempre no caminho critico.
|
||||
|
||||
## Hotspots Atuais
|
||||
|
||||
- [gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs#L563)
|
||||
- [gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs#L671)
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Definir ate onde o v1 pode sofisticar o modelo de desenho destrutivo em memoria para reduzir custo e manter previsibilidade, sem migrar para um renderer de estilo GPU.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Perfil real de custo.
|
||||
Medir separadamente:
|
||||
- rebuild de buckets;
|
||||
- rasterizacao de layers;
|
||||
- rasterizacao de sprites;
|
||||
- fades fullscreen;
|
||||
- conversao/copia no host;
|
||||
- apresentacao no host.
|
||||
|
||||
2. Granularidade minima de invalidacao compativel com framebuffer destrutivo.
|
||||
Escolher entre:
|
||||
- dirty flag por frame inteiro;
|
||||
- dirty flags por subsistema (`world`, `hud`, `fade`, `sprites`);
|
||||
- dirty regions restritas e derivadas de primitivas/sprites;
|
||||
- combinacao minima viavel.
|
||||
|
||||
3. Buckets e traversal de sprites.
|
||||
Decidir se os buckets continuam sendo reconstruidos por frame ou se viram estrutura incremental.
|
||||
|
||||
4. Fades.
|
||||
Definir se fade neutro precisa bypass total e se fade parcial pode operar por regiao/camada.
|
||||
|
||||
5. Cache de composicao.
|
||||
Delimitar se layers estaticas/HUD podem manter cache intermediario.
|
||||
|
||||
6. Primitivas e contrato operacional.
|
||||
Definir quais draws devem continuar sendo vistos como escrita destrutiva direta no framebuffer e onde valem aceleracoes internas sem mudar a semantica observavel.
|
||||
|
||||
7. Meta de custo.
|
||||
Fechar qual teto de pixels/trabalho por frame e aceitavel no baseline.
|
||||
|
||||
8. Orcamento de memoria.
|
||||
Definir quais otimizacoes aceitam memoria adicional e quais precisam caber no modelo mais economico possivel para handheld barato.
|
||||
|
||||
## Open Questions de Arquitetura
|
||||
|
||||
1. Quais partes do custo atual estao no `render_all()` e quais partes estao na conversao/apresentacao do host?
|
||||
2. Qual o maior ganho de curto prazo dentro do modelo atual: buckets, fades, HUD, primitivas ou host copy/convert?
|
||||
3. Dirty regions restritas quebram alguma expectativa de determinismo visivel ou sao apenas um detalhe interno de implementacao?
|
||||
4. O HUD deve continuar no mesmo pipeline da world scene?
|
||||
5. Quais primitivas merecem tratamento especial para reduzir overdraw sem mudar a semantica de sobrescrita?
|
||||
6. Qual o teto aceitavel de memoria extra para caches, buffers separados ou estruturas auxiliares no handheld alvo?
|
||||
|
||||
## Problemas de Medio e Grande Porte Identificados
|
||||
|
||||
### 1. Composicao completa do framebuffer a cada frame logico
|
||||
|
||||
`render_all()` recompõe o `back` inteiro por software, mesmo quando a mudanca visual e pequena.
|
||||
|
||||
Impacto:
|
||||
|
||||
- custo cresce com a quantidade de pixels tocados, nao apenas com a quantidade de estado alterado;
|
||||
- layers, sprites e fades disputam o mesmo budget de CPU;
|
||||
- o modelo atual favorece previsibilidade sem ainda ter atalhos internos suficientes.
|
||||
|
||||
### 2. Rasterizacao pixel a pixel de tilemaps
|
||||
|
||||
Cada layer visivel percorre tiles e, para cada tile nao vazio, resolve indices e escreve pixel a pixel no framebuffer.
|
||||
|
||||
Impacto:
|
||||
|
||||
- o custo real esta mais na escrita de pixels do que na manutencao do `TileMap`;
|
||||
- scroll e barato como estado, mas caro na hora de compor a imagem se tudo for repintado;
|
||||
- layers estaticas continuam pagando custo de rasterizacao em toda recomposicao.
|
||||
|
||||
### 3. Rasterizacao pixel a pixel de sprites e escolha por bucket full scan
|
||||
|
||||
Os 512 sprites sao varridos para reconstruir buckets e os sprites ativos sao desenhados pixel a pixel.
|
||||
|
||||
Impacto:
|
||||
|
||||
- quando poucos sprites mudam, ainda existe custo fixo de rebuild dos buckets;
|
||||
- overdraw entre sprites e layers pode explodir o numero de writes no `back`;
|
||||
- a escolha de sprites ativos/prioridade ainda e simples demais para cenarios com alta ocupacao.
|
||||
|
||||
### 4. Fades fullscreen com custo proporcional ao frame inteiro
|
||||
|
||||
`scene fade` e `hud fade` percorrem o framebuffer inteiro quando ativos.
|
||||
|
||||
Impacto:
|
||||
|
||||
- custo grande e previsivel, mas potencialmente desproporcional;
|
||||
- fade neutro ja pode ser bypass, mas fade parcial ainda custa uma passada completa;
|
||||
- dois passes fullscreen no mesmo frame podem virar gargalo antes de layers ou sprites.
|
||||
|
||||
### 5. HUD no mesmo caminho critico da composicao principal
|
||||
|
||||
O HUD e redesenhado como tilemap depois da world scene e antes do `hud fade`.
|
||||
|
||||
Impacto:
|
||||
|
||||
- HUD estatico continua gerando trabalho por frame;
|
||||
- mistura responsabilidades de world/UI no mesmo budget de composicao;
|
||||
- dificulta isolar ganho de cache ou dirtying so para interface.
|
||||
|
||||
### 6. Conversao obrigatoria de RGB565 para RGBA8 no host
|
||||
|
||||
No `RedrawRequested`, o host percorre todo o `front_buffer` e converte para o frame do `pixels`.
|
||||
|
||||
Impacto:
|
||||
|
||||
- ha custo de leitura do framebuffer inteiro e escrita de um segundo buffer inteiro;
|
||||
- esse custo existe mesmo quando o host esta apenas apresentando o mesmo quadro logico;
|
||||
- pode competir com o custo do renderer sem estar visivel na discussao do `gfx`.
|
||||
|
||||
### 7. Pipeline serializado no host desktop
|
||||
|
||||
`tick`, `render_all()`, conversao de formato e apresentacao ocorrem no mesmo fluxo operacional.
|
||||
|
||||
Impacto:
|
||||
|
||||
- o frame time final acumula custo de runtime, composicao, copy/convert e present;
|
||||
- falta desacoplamento para esconder latencia entre producao e apresentacao;
|
||||
- dificulta atribuir gargalo sem instrumentacao por etapa.
|
||||
|
||||
## Estudo Inicial de Possiveis Optimizacoes
|
||||
|
||||
### A. Dirty flags por subsistema em vez de dirty rect generico
|
||||
|
||||
Ideia:
|
||||
|
||||
- flags independentes para `world`, `sprites`, `hud`, `scene_fade`, `hud_fade`, `host_present`.
|
||||
|
||||
Vantagens:
|
||||
|
||||
- preserva a semantica de framebuffer destrutivo;
|
||||
- reduz recomposicao desnecessaria quando so um subsistema mudou;
|
||||
- e muito mais simples de validar do que dirty regions arbitrarias.
|
||||
|
||||
Riscos:
|
||||
|
||||
- exige definir dependencias claras entre world, sprites, HUD e fades;
|
||||
- pode induzir falsos positivos conservadores, o que e aceitavel no v1.
|
||||
|
||||
### B. Rebuild incremental ou condicional dos buckets de sprite
|
||||
|
||||
Ideia:
|
||||
|
||||
- so reconstruir buckets quando algum `GfxSetSprite` mudar atividade, prioridade, banco ou tile;
|
||||
- opcionalmente manter contadores/sinais de mutacao da OAM.
|
||||
|
||||
Vantagens:
|
||||
|
||||
- elimina custo fixo por frame quando OAM permanece estavel;
|
||||
- combina com a ideia de sprites como estado, nao como draw list efemera.
|
||||
|
||||
Riscos:
|
||||
|
||||
- precisa invalidacao correta para evitar bucket desatualizado;
|
||||
- ganho pode ser pequeno se o custo dominante estiver no draw dos sprites, nao no rebuild.
|
||||
|
||||
### C. Separar world e HUD em buffers logicos distintos
|
||||
|
||||
Ideia:
|
||||
|
||||
- manter um buffer da world scene e um buffer do HUD, compondo no final apenas quando necessario.
|
||||
|
||||
Vantagens:
|
||||
|
||||
- HUD estatico deixa de participar da recomposicao da world;
|
||||
- permite cache e fade especificos para cada dominio;
|
||||
- se alinha bem com a separacao conceitual entre cena e interface.
|
||||
|
||||
Riscos:
|
||||
|
||||
- aumenta uso de memoria e pontos de sincronizacao;
|
||||
- precisa manter semantica clara de sobrescrita entre mundo e HUD.
|
||||
- pode ser inviavel no perfil de handheld barato se exigir buffers adicionais permanentes.
|
||||
|
||||
### D. Cache de layer estatica ou composicao parcial da world
|
||||
|
||||
Ideia:
|
||||
|
||||
- layers que nao mudam podem manter imagem intermediaria pronta;
|
||||
- scroll, tile updates ou troca de bank invalidam o cache correspondente.
|
||||
|
||||
Vantagens:
|
||||
|
||||
- reduz rasterizacao repetida de cenario estavel;
|
||||
- aproxima o ganho de hardware tile-based sem abandonar software raster.
|
||||
|
||||
Riscos:
|
||||
|
||||
- cache amplo demais vira complexidade estrutural;
|
||||
- se scroll muda constantemente, o ganho cai bastante.
|
||||
- pode consumir memoria demais para um hardware com orcamento agressivo.
|
||||
|
||||
### E. Otimizacao de fades
|
||||
|
||||
Ideia:
|
||||
|
||||
- bypass total para fade neutro;
|
||||
- opcionalmente aplicar fade apenas sobre buffers relevantes;
|
||||
- estudar LUTs ou blend mais barato por pixel.
|
||||
|
||||
Vantagens:
|
||||
|
||||
- ataca um custo fullscreen claramente delimitado;
|
||||
- baixo risco conceitual.
|
||||
|
||||
Riscos:
|
||||
|
||||
- fade parcial por regiao pode complicar demais o contrato;
|
||||
- LUT ajuda aritmetica, mas nao elimina custo de varrer memoria.
|
||||
|
||||
### F. Melhorias em primitivas e spans de memoria
|
||||
|
||||
Ideia:
|
||||
|
||||
- acelerar `fill_rect`, linhas horizontais/verticais, clears e possiveis blits contiguos;
|
||||
- explorar caminhos de row spans contiguos em vez de loops mais genericos.
|
||||
|
||||
Vantagens:
|
||||
|
||||
- melhora direta do modelo de desenho destrutivo;
|
||||
- baixo risco arquitetural;
|
||||
- cria fundacao para outros atalhos internos.
|
||||
|
||||
Riscos:
|
||||
|
||||
- ganho localizado se o workload dominante vier de tile/sprite compositing;
|
||||
- precisa medir por primitive class.
|
||||
|
||||
### G. Reduzir custo de copy/convert no host
|
||||
|
||||
Ideia:
|
||||
|
||||
- medir separadamente `draw_rgb565_to_rgba8` e `pixels.render()`;
|
||||
- estudar formato mais proximo do host ou conversao mais barata;
|
||||
- evitar redraw host quando nao houver novo front relevante.
|
||||
|
||||
Vantagens:
|
||||
|
||||
- ataca custo fora do `gfx` que ainda entra no frame time total;
|
||||
- pode render ganho imediato no desktop host.
|
||||
|
||||
Riscos:
|
||||
|
||||
- parte do custo depende da stack `pixels/wgpu`, nao apenas do runtime;
|
||||
- alguns ganhos podem ser especificos do host desktop e nao do contrato do console.
|
||||
|
||||
## Restricao de Plataforma
|
||||
|
||||
Qualquer recomendacao desta agenda deve ser filtrada por um criterio adicional:
|
||||
|
||||
- priorizar solucoes que melhorem custo sem multiplicar buffers;
|
||||
- tratar memoria extra como recurso escasso de primeira classe;
|
||||
- preferir flags, metadados pequenos e estruturas incrementais a caches grandes;
|
||||
- evitar solucoes cuja performance dependa de assumir um host desktop mais forte do que o handheld alvo.
|
||||
|
||||
Direcao atual da discussao:
|
||||
|
||||
- nesta etapa, buffers extras devem ficar fora;
|
||||
- o foco deve ser otimizar ao maximo o pipeline existente;
|
||||
- cache intermediario ou novos buffers so entram em estudo depois que as otimizacoes de baixo custo de memoria forem medidas e esgotadas.
|
||||
|
||||
## Sugestao / Recomendacao Atual
|
||||
|
||||
Priorizar o estudo em camadas, nesta ordem:
|
||||
|
||||
1. instrumentar o pipeline por etapa;
|
||||
2. validar dirty flags por subsistema como mecanismo minimo de invalidacao;
|
||||
3. testar rebuild condicional de buckets e bypass/isolamento de fades;
|
||||
4. otimizar primitivas e caminhos contiguos de escrita no framebuffer atual;
|
||||
5. estudar separacao world/HUD e cache de layer apenas se os dados justificarem e o teto de memoria permitir;
|
||||
5. tratar copy/convert do host como frente paralela de otimizacao, nao como substituto da analise do `gfx`.
|
||||
|
||||
## Achados Consolidados Ate Aqui
|
||||
|
||||
1. O contrato base continua sendo framebuffer destrutivo em memoria.
|
||||
Draws escrevem diretamente no buffer de trabalho e operacoes posteriores sobrescrevem o que estiver por baixo. A agenda nao aponta para migracao a um renderer tipo GPU, retained mode ou compositor sofisticado.
|
||||
|
||||
2. O `present()` atual nao parece ser o problema principal.
|
||||
No `gfx`, `present()` faz swap de buffers, nao copia completa de pixels.
|
||||
|
||||
3. O custo suspeito esta na recomposicao e na apresentacao, nao na manutencao do estado logico.
|
||||
Escritas de `TileMap`, scroll e `GfxSetSprite` sao pequenas e pontuais; o custo potencialmente dominante esta em rasterizar pixels, aplicar fades fullscreen e converter o framebuffer para o host.
|
||||
|
||||
4. Os maiores suspeitos atuais de custo sao:
|
||||
- rasterizacao de layers;
|
||||
- rasterizacao de sprites;
|
||||
- fades fullscreen;
|
||||
- conversao `RGB565 -> RGBA8` no host;
|
||||
- `pixels.render()` / apresentacao no host.
|
||||
|
||||
5. O pipeline atual deve ser otimizado antes de considerar buffers extras.
|
||||
A direcao aceita da discussao e esgotar primeiro flags pequenas, bypasses, melhorias de primitive paths e ajustes incrementais no pipeline existente.
|
||||
|
||||
6. Restricao de plataforma pesa tanto quanto CPU.
|
||||
Como o alvo e um handheld proprio com limitacoes de orcamento e memoria, solucoes que consumam RAM adicional significativa devem ficar fora desta fase.
|
||||
|
||||
7. A instrumentacao minima desejada para retomar o estudo ficou definida.
|
||||
Quando houver workload representativo, queremos medir ao menos:
|
||||
- `render_all_total_us`
|
||||
- `bucket_rebuild_us`
|
||||
- `layer_raster_us`
|
||||
- `sprite_raster_us`
|
||||
- `scene_fade_us`
|
||||
- `hud_raster_us`
|
||||
- `hud_fade_us`
|
||||
- `host_convert_us`
|
||||
- `host_present_us`
|
||||
|
||||
8. A retencao de metricas deve ser barata e orientada a analise posterior.
|
||||
A preferencia atual e por acumuladores e ring buffer pequeno de snapshots, sem logging pesado por frame no hot path.
|
||||
|
||||
9. Ring buffer no `TileMap` nao e prioridade nesta fase.
|
||||
O custo suspeito nao esta na manutencao da grade logica do mapa, e sim na composicao da janela visivel no framebuffer. Mudar a estrutura do mapa so faria sentido se o gargalo principal estivesse em streaming/atualizacao estrutural do cenario, o que nao e a hipotese atual.
|
||||
|
||||
10. A direcao de otimizacao mais promissora e padronizar copias massivas para o framebuffer atual.
|
||||
Em vez de atacar apenas tilemaps com loops pixel a pixel, a discussao passa a favorecer um padrao geral de blit/copia massiva com:
|
||||
- calculo previo de offsets e spans;
|
||||
- fast paths para casos contiguos;
|
||||
- trabalho por linha/chunk em vez de trabalho atomizado por pixel quando possivel;
|
||||
- reaproveitamento dessa infraestrutura para tilemaps, sprites e outras operacoes de desenho destrutivo.
|
||||
|
||||
11. Migrar o `back` para `RGBA8888` nao e direcao aceita neste momento.
|
||||
Isso aumentaria custo de memoria e largura de banda no alvo handheld, alem de deslocar a otimizacao para o host desktop. O contrato interno continua preferencialmente em `RGB565`, mesmo considerando fades e uma futura pipeline de lights.
|
||||
|
||||
## Nova Direcao Tecnica Em Estudo
|
||||
|
||||
Quando esta agenda for reaberta, a linha principal de investigacao deve considerar:
|
||||
|
||||
- manter o `TileMap` simples como estado logico;
|
||||
- assumir que a janela visivel provavelmente continuara sendo recomposta na maior parte dos frames;
|
||||
- concentrar a otimizacao em como essa recomposicao escreve no `back`;
|
||||
- desenhar uma infraestrutura compartilhada de copias massivas/blits para o framebuffer atual;
|
||||
- usar essa infraestrutura nao apenas para tilemaps, mas como base comum para raster de sprites e outros caminhos de desenho.
|
||||
|
||||
Pergunta orientadora da reabertura:
|
||||
|
||||
- como transformar o renderer de um pipeline de writes atomizados por pixel em um pipeline com fast paths de spans/chunks, sem perder a semantica de framebuffer destrutivo e sem pagar memoria extra relevante?
|
||||
|
||||
## Status de Standby
|
||||
|
||||
Esta agenda deve ficar em espera ate existir um game ou workload real que exercite de forma representativa:
|
||||
|
||||
- tilemaps com scroll e composicao de world;
|
||||
- sprites em quantidade suficiente para testar buckets e overdraw;
|
||||
- HUD ativo;
|
||||
- fades;
|
||||
- apresentacao completa no host.
|
||||
|
||||
Antes disso, qualquer conclusao sobre gargalo ou prioridade de otimizacao tende a ser prematura.
|
||||
|
||||
## Proximo Gatilho Para Reabrir
|
||||
|
||||
Reabrir esta agenda quando houver:
|
||||
|
||||
- um game jogavel ou cena de teste que percorra o pipeline completo;
|
||||
- dados de workload mais proximos do uso real;
|
||||
- necessidade concreta de justificar uma rodada de instrumentacao e profiling.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- `../specs/04-gfx-peripheral.md`
|
||||
- `../specs/11-portability-and-cross-platform-execution.md`
|
||||
|
||||
## Criterio de Saida Desta Agenda
|
||||
|
||||
Pode virar PR quando houver decisao escrita sobre:
|
||||
|
||||
- filosofia explicita de framebuffer destrutivo como contrato base;
|
||||
- plano de instrumentacao para localizar o custo dominante do pipeline;
|
||||
- nivel minimo de invalidacao no v1;
|
||||
- politica de rebuild de buckets de sprites;
|
||||
- bypass/cache de fade e HUD;
|
||||
- politica para otimizar primitivas sem mudar a semantica observavel;
|
||||
- meta de custo para o render pipeline.
|
||||
Reference in New Issue
Block a user