Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
3
0
Fork 0
Code Pull Requests 1 Activity
prometeu-runtime/discussion/workflow/plans/PLN-0006-perf-host-debug-overlay-isolation.md

3.3 KiB
Raw Blame History

id ticket title status created updated decisions tags
PLN-0006 perf-host-debug-overlay-isolation PR/Plan - [PERF] Host Debug Overlay Isolation open 2026-04-10 2026-04-10
DEC-0007
performance
host
gfx

PR/Plan - [PERF] Host Debug Overlay Isolation

Briefing

Implementação do isolamento total do overlay de debug no Host Desktop (prometeu-host-desktop-winit), removendo o acoplamento com o runtime e o pipeline de gfx emulado.

Decisions de Origem

  • DEC-0007: [PERF] Host Debug Overlay Isolation.
  • DEC-0005: [PERF] Push-based Telemetry Model (base para extração de dados).

Alvo

  • crates/host/prometeu-host-desktop-winit: Implementação da camada nativa de HUD.
  • crates/runtime: Exposição de campos de telemetria via API.
  • docs/specs/runtime: Atualização das especificações de debug e portabilidade.

Escopo

  • Spec Work:
    • Atualizar docs/specs/runtime/10-debug-inspection-and-profiling.md para remover menções ao HUD emulado.
    • Atualizar docs/specs/runtime/11-portability-and-cross-platform-execution.md para reforçar a separação de responsabilidades (Host-side HUD).
  • Code Work:
    • Expansão da API de telemetria no runtime para incluir todos os dados necessários (Cycles, Memory, Logs).
    • Remoção do código de desenho de texto legado no runner.rs.
    • Integração de biblioteca nativa (ex: egui ou composição via pixels) para renderização do novo overlay no Host.
    • Implementação do toggle via tecla F1 no HostRunner.

Fora de Escopo

  • Implementação de overlay visual em outros hosts (mobile, handheld).
  • Alterações na lógica de emulação central (loop de execução).

Plano de Execucao

  1. Fase 1: Especificações (Spec)
    • Revisar e atualizar os arquivos de especificação (10-debug e 11-portability).
  2. Fase 2: Runtime Telemetry API (Code)
    • Garantir que todos os campos de telemetria estejam expostos via atômicos/push-based conforme DEC-0005.
  3. Fase 3: Host HUD Implementation (Code)
    • Integrar o novo motor de HUD no prometeu-host-desktop-winit.
    • Conectar os dados da API de telemetria à visualização do HUD.
  4. Fase 4: Cleanup (Code)
    • Remover hotspots de formatação de strings e draw calls do overlay antigo no Host.

Criterios de Aceite

  • O overlay de debug é ativado/desativado via tecla F1.
  • O overlay utiliza fontes TrueType (monospaced) nítidas e fundo semi-transparente.
  • O framebuffer emulado não contém pixels do HUD (composição nativa pós-upscaling).
  • O custo de ciclos do runtime é idêntico com o overlay ligado ou desligado.

Tests / Validacao

  • Verificação Visual: Confirmar a qualidade das fontes e a transparência do novo HUD.
  • Benchmarking: Comparar os ciclos consumidos por frame com e sem o HUD ativo para provar isolamento.
  • Teste de Regressão: Garantir que o F1 toggle não afeta a estabilidade do loop de emulação.

Riscos

  • Overhead no Host: A renderização nativa (ex: egui) pode introduzir overhead no Host Desktop em máquinas muito fracas (geralmente aceitável em Desktop).
  • Sincronização de Telemetria: Pequeno atraso visual entre o frame renderizado e os dados exibidos se a coleta for puramente assíncrona (aceitável para telemetria de debug).