50 lines
3.1 KiB
Markdown
50 lines
3.1 KiB
Markdown
---
|
|
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)*
|