[PERF] Host Debug Overlay Isolation
This commit is contained in:
@@ -2,72 +2,48 @@
|
||||
id: AGD-0012
|
||||
ticket: perf-host-debug-overlay-isolation
|
||||
title: Agenda - [PERF] Host Debug Overlay Isolation
|
||||
status: open
|
||||
status: done
|
||||
created: 2026-03-27
|
||||
resolved:
|
||||
decision:
|
||||
tags: []
|
||||
resolved: 2026-04-10
|
||||
decision: DEC-0007
|
||||
tags: [performance, host, gfx]
|
||||
---
|
||||
|
||||
# Agenda - [PERF] Host Debug Overlay Isolation
|
||||
|
||||
## Contexto
|
||||
O overlay de debug é uma ferramenta exclusiva para o ambiente **Desktop** (`prometeu-host-desktop-winit`). Ele visa fornecer telemetria em tempo real para desenvolvedores sem impactar a fidelidade da emulação ou o desempenho medido do hardware final (handhelds/consoles de baixo custo), onde este overlay não existirá.
|
||||
|
||||
## Problema
|
||||
Atualmente, o overlay de debug está indevidamente acoplado ao pipeline de `gfx` emulado e ao processamento do runtime.
|
||||
- **Distorção de Performance:** O custo de renderizar o HUD técnico (formatação de strings e draw calls extras) é contabilizado como custo do jogo.
|
||||
- **Acoplamento de Pipeline:** O pipeline de `gfx` precisa processar elementos que não pertencem à lógica da máquina virtual.
|
||||
- **Hotspots:** `runner.rs` realiza `present()` extra e manipulação de texto no loop principal.
|
||||
|
||||
O overlay de debug ainda usa o pipeline emulado de `gfx` e injeta custo visual no caminho normal do host.
|
||||
## Pontos Críticos
|
||||
- **Fato:** O overlay é uma necessidade de desenvolvimento Desktop, não uma funcionalidade da máquina `prometeu`.
|
||||
- **Risco:** Qualquer processamento de overlay dentro do runtime `prometeu` invalida a pureza dos ciclos medidos para certificação.
|
||||
- **Tradeoff:** Mover o overlay para o Host exige acesso assíncrono ou passivo aos dados de telemetria.
|
||||
- **Hipótese:** Um overlay 100% nativo no Host (Winit/Pixels) usando fontes TrueType terá custo desprezível e legibilidade superior.
|
||||
|
||||
Hoje o host formata strings por frame, desenha texto via `gfx` e faz `present()` extra para sobrepor telemetria.
|
||||
## Opções
|
||||
- **Opção A (Recomendada):** Camada Host Nativa. O `HostRunner` renderiza o HUD em uma surface separada ou faz um *compositing* nativo após o upscaling do framebuffer do console.
|
||||
- **Opção B:** Overlay via IPC/Sidecar. Ferramenta externa de inspeção (descartada por complexidade visual).
|
||||
- **Opção C:** Manter no `gfx` emulado com otimização (descartada por não resolver o acoplamento).
|
||||
|
||||
## Dor
|
||||
## Sugestão / Recomendação
|
||||
1. **Agnosticismo de GFX:** O overlay deve ser tratado como uma "película" transparente aplicada pelo Host Desktop sobre o resultado final da renderização.
|
||||
2. **Isolamento de Processamento:** Nenhuma instrução de desenho ou formatação de strings do overlay deve ocorrer dentro do runtime.
|
||||
3. **Acesso via API:** O Host acessará os dados de telemetria através de uma API dedicada (baseada no modelo push-based da `DEC-0005`).
|
||||
4. **Interface de Controle:** O acionamento permanece via tecla **F1** como um *toggle*, gerenciado pela camada de Host.
|
||||
5. **Composição via Host:** Utilizar bibliotecas nativas do Host para renderizar o HUD com fontes TrueType nítidas e Alpha Blending real.
|
||||
|
||||
- debug ligado altera custo do render path que deveria estar sendo medido.
|
||||
- overlay de desenvolvimento distorce a leitura de performance do console.
|
||||
- handheld barato nao deveria pagar composicao de HUD tecnico no mesmo pipeline do jogo.
|
||||
## Perguntas em Aberto
|
||||
- Nenhuma. As questões sobre acesso via API e acionamento via F1 foram resolvidas durante a discussão.
|
||||
|
||||
## Hotspots Atuais
|
||||
|
||||
- [runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs#L126)
|
||||
- [runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs#L381)
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Isolar o overlay de debug do custo medido do console sem perder utilidade para desenvolvimento.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Lugar de composicao.
|
||||
Decidir se o overlay:
|
||||
- continua no `gfx` emulado;
|
||||
- sobe para camada host nativa;
|
||||
- vira surface separada de debug.
|
||||
|
||||
2. Politica de strings/glyphs.
|
||||
Definir se texto e reconstruido por frame ou cacheado.
|
||||
|
||||
3. Custo em modo debug.
|
||||
Delimitar qual overhead e aceitavel quando overlay estiver ativo.
|
||||
|
||||
4. Efeito na telemetria.
|
||||
Fechar se a telemetria deve incluir ou excluir explicitamente o custo do overlay.
|
||||
|
||||
## Open Questions de Arquitetura
|
||||
|
||||
1. O overlay precisa ser representativo do hardware final ou apenas ferramenta de desktop?
|
||||
Não, como é HUD técnico, pode e deve ser renderizado pelo Host nativo para melhor legibilidade.
|
||||
2. Vale um modo "perf puro" onde overlay nunca toca no framebuffer do console?
|
||||
Sim. O isolamento garante que o `gfx` emulado esteja 100% livre para o jogo durante a medição.
|
||||
3. O host deve oferecer toggles separados para stats, logs e overlay visual?
|
||||
Sim. O `HostRunner` deve expor controles granulares via `inspection_active`.
|
||||
4. Como melhorar a legibilidade e estética (Glyphs/Transparência)?
|
||||
Migrar a renderização do HUD para o Host Nativo (Winit/Pixels), permitindo o uso de fontes TrueType (monospaced) nítidas e Alpha Blending real para transparência no fundo do painel.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- `../specs/10-debug-inspection-and-profiling.md`
|
||||
- `../specs/11-portability-and-cross-platform-execution.md`
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
1. **Migração para Camada Host Nativa:** Renderizar o HUD de debug em uma surface separada ou via pipeline nativo do Host (depois do upscaling do framebuffer do console).
|
||||
2. **Fontes TrueType (Mono):** Substituir os glyphs bitmapped rudimentares por uma fonte nativa de alta qualidade e nítida.
|
||||
3. **Composição Alpha:** Permitir fundo semi-transparente para o overlay para não bloquear a visão do jogo.
|
||||
4. **Acionamento Explícito:** Host deve gerenciar `inspection_active: true` no runtime apenas quando o HUD ou Debugger estiverem ativos.
|
||||
## Critério para Encerrar
|
||||
A agenda é considerada encerrada quando:
|
||||
- Houver consenso sobre o isolamento total do pipeline de `gfx`.
|
||||
- O método de acesso aos dados (API) estiver definido.
|
||||
- O controle de interface (F1) estiver estabelecido.
|
||||
*(Critérios atingidos em 2026-04-10)*
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
# AGD-0021: Full Migration to Atomic Telemetry
|
||||
|
||||
## Contexto
|
||||
Durante a implementação do isolamento do overlay de debug no Host Desktop (DEC-0007), foi introduzido o `AtomicTelemetry` para permitir acesso assíncrono e sem locks aos dados de performance. Por motivos de cautela inicial, os campos legados `telemetry_current` e `telemetry_last` foram mantidos no `VirtualMachineRuntime` para compatibilidade com processos de certificação e logs internos.
|
||||
|
||||
## Problema
|
||||
A manutenção de dois sistemas paralelos de telemetria gera redundância de código, aumenta a superfície de erro e consome ciclos de CPU desnecessários para atualizar dados que já estão disponíveis de forma mais eficiente via atômicos. A "compatibilidade" pretendida não justifica o débito técnico de manter estruturas duplicadas.
|
||||
|
||||
## Pontos Críticos
|
||||
- **Fato:** `AtomicTelemetry` já provê todos os dados necessários (ciclos, memória, logs).
|
||||
- **Risco:** Remoção de `telemetry_last` pode quebrar ferramentas que dependem de snapshots estáticos por frame se não houver um substituto claro de snapshot via atômicos.
|
||||
- **Tradeoff:** A migração exige refatorar o `VirtualMachineRuntime` e possivelmente o `LogService` para convergirem em uma única fonte de verdade.
|
||||
- **Hipótese:** Um snapshot derivado do `AtomicTelemetry` ao final de cada frame é suficiente para substituir o `telemetry_last` legado sem perda de precisão.
|
||||
|
||||
## Opções
|
||||
- **Opção A (Recomendada):** Migração total e remoção dos campos legados. O `AtomicTelemetry` torna-se a única fonte de verdade. Onde snapshots estáveis são necessários, eles são extraídos via `AtomicTelemetry::snapshot()`.
|
||||
- **Opção B:** Manter redundância (Descartada pelo usuário).
|
||||
|
||||
## Sugestão / Recomendação
|
||||
1. Remover `telemetry_current` e `telemetry_last` do `VirtualMachineRuntime`.
|
||||
2. Refatorar o loop de execução para atualizar exclusivamente o `AtomicTelemetry`.
|
||||
3. Garantir que o `LogService` e outras auditorias consumam dados do novo modelo.
|
||||
4. Atualizar as especificações para refletir o modelo único.
|
||||
|
||||
## Perguntas em Aberto
|
||||
1. Existe algum uso específico de `telemetry_last` em ferramentas externas (não mapeadas) que dependem do layout de memória antigo? (Assumimos que não para este escopo).
|
||||
|
||||
## Criterio para Encerrar
|
||||
- Remoção completa dos campos no código.
|
||||
- Compilação e execução bem-sucedida do Host Desktop com o novo modelo único.
|
||||
- Atualização da documentação normativa.
|
||||
Reference in New Issue
Block a user