65 lines
3.3 KiB
Markdown
65 lines
3.3 KiB
Markdown
---
|
|
id: PLN-0006
|
|
ticket: perf-host-debug-overlay-isolation
|
|
title: PR/Plan - [PERF] Host Debug Overlay Isolation
|
|
status: open
|
|
created: 2026-04-10
|
|
updated: 2026-04-10
|
|
decisions: [DEC-0007]
|
|
tags: [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).
|