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

Agnosticismo de GFX: O overlay deve ser tratado como uma "película" transparente aplicada pelo Host Desktop sobre o resultado final da renderização.
Isolamento de Processamento: Nenhuma instrução de desenho ou formatação de strings do overlay deve ocorrer dentro do runtime.
Acesso via API: O Host acessará os dados de telemetria através de uma API dedicada (baseada no modelo push-based da DEC-0005).
Interface de Controle: O acionamento permanece via tecla F1 como um toggle, gerenciado pela camada de Host.
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)

3.1 KiB Raw Blame History