74 lines
3.1 KiB
Markdown
74 lines
3.1 KiB
Markdown
---
|
|
id: AGD-0012
|
|
ticket: perf-host-debug-overlay-isolation
|
|
title: Agenda - [PERF] Host Debug Overlay Isolation
|
|
status: open
|
|
created: 2026-03-27
|
|
resolved:
|
|
decision:
|
|
tags: []
|
|
---
|
|
|
|
# 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](/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.
|