Decision - [PERF] Host Debug Overlay Isolation

Status

Accepted

Contexto

O overlay de debug do PROMETEU, utilizado para exibir telemetria, logs e métricas em tempo real, está atualmente acoplado ao pipeline de renderização emulado (gfx) e ao processamento do runtime. Isso resulta em:

Distorção de Performance: O custo de formatar strings e realizar chamadas de desenho para o HUD técnico é contabilizado como ciclos do jogo, invalidando medições de certificação.
Acoplamento Indevido: O pipeline gfx emulado processa elementos visuais (HUD) que não existem no hardware original.
Complexidade no Host: O Host precisa lidar com a injeção dessas informações no buffer de emulação.

Decisao

Fica decidido que o overlay de debug será movido integralmente para a camada Host Desktop (prometeu-host-desktop-winit), operando de forma 100% isolada do runtime e do pipeline de gfx emulado.

Isolamento de Pipeline: O overlay técnico deve ser tratado como uma "película" (layer) transparente aplicada pelo Host sobre o resultado final da renderização (pós-upscaling).
Isolamento de Processamento: Nenhuma instrução de desenho ou formatação de strings relacionada ao overlay deve ocorrer dentro do runtime ou durante os ciclos emulados.
Acesso via API: O Host acessará os dados necessários para o overlay através de uma API de telemetria passiva (baseada em atômicos, conforme definido na DEC-0005).
Acionamento via F1: O controle de visibilidade (toggle) do overlay é de responsabilidade exclusiva do Host, acionado pela tecla F1.

Rationale

Pureza de Medição: Ao remover o processamento do overlay do runtime, garantimos que 100% dos ciclos medidos pertencem à lógica do cartucho e periféricos emulados.
Desempenho no Hardware Alvo: Como o overlay é exclusivo de Desktop, dispositivos handheld/consoles de baixo custo não devem pagar o preço de implementação ou ramificações lógicas para lidar com HUD técnico.
Qualidade Visual: Utilizar o Host para renderizar o HUD permite o uso de fontes TrueType nítidas e Alpha Blending real, melhorando drasticamente a legibilidade para o desenvolvedor sem afetar a fidelidade da emulação.

Invariantes / Contrato

Zero Overhead no Runtime: A presença ou ausência do overlay não deve alterar o contador de ciclos consumidos por frame no runtime.
Agnosticismo de GFX: O framebuffer emulado deve conter apenas os pixels gerados pelo cartucho, sem HUD técnico "queimado" na imagem.
Composição Assíncrona/Passiva: O Host não deve bloquear o runtime para coletar dados para o overlay; a leitura deve ser feita a partir de buffers de telemetria já expostos.

Impactos

Host (Desktop Winit): Exige a implementação de uma camada de renderização nativa (ex: egui ou composição direta via pixels/winit) que suporte transparência.
Runtime API: Deve expor campos de telemetria (FPS, Memory Usage, Cycles) via API para consumo pelo Host.
Especificações: Atualização dos capítulos de Portabilidade e Debug para refletir o isolamento.

Referencias

AGD-0012: [PERF] Host Debug Overlay Isolation (Agenda de Origem).
DEC-0005: [PERF] Push-based Telemetry Model (Modelo de acesso aos dados).

Propagacao Necessaria

Remover hotspots de desenho de texto no runner.rs do host.
Implementar o novo sistema de HUD no host usando bibliotecas nativas.
Atualizar a documentação técnica em docs/specs/runtime/.

3.7 KiB Raw Blame History