prometeu-runtime/discussion/workflow/agendas/AGD-0012-perf-host-debug-overlay-isolation.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0012	perf-host-debug-overlay-isolation	Agenda - [PERF] Host Debug Overlay Isolation	open	2026-03-27

Agenda - [PERF] Host Debug Overlay Isolation

Problema

O overlay de debug ainda usa o pipeline emulado de gfx e injeta custo visual no caminho normal do host.

Hoje o host formata strings por frame, desenha texto via gfx e faz present() extra para sobrepor telemetria.

Dor

• 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.

Hotspots Atuais

• runner.rs
• runner.rs

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.