---
id: AGD-0012
ticket: perf-host-debug-overlay-isolation
title: Agenda - [PERF] Host Debug Overlay Isolation
status: done
created: 2026-03-27
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.

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

## 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).

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

## Perguntas em Aberto
- Nenhuma. As questões sobre acesso via API e acionamento via F1 foram resolvidas durante a discussão.

## 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)*