---
id: AGD-0012
ticket: perf-host-debug-overlay-isolation
title: Agenda - [PERF] Host Debug Overlay Isolation
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---

# Agenda - [PERF] Host Debug Overlay Isolation

## Problema

O overlay de debug ainda usa o pipeline emulado de `gfx` e injeta custo visual no caminho normal do host.

Hoje o host formata strings por frame, desenha texto via `gfx` e faz `present()` extra para sobrepor telemetria.

## Dor

- debug ligado altera custo do render path que deveria estar sendo medido.
- overlay de desenvolvimento distorce a leitura de performance do console.
- handheld barato nao deveria pagar composicao de HUD tecnico no mesmo pipeline do jogo.

## Hotspots Atuais

- [runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs#L126)
- [runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs#L381)

## Alvo da Discussao

Isolar o overlay de debug do custo medido do console sem perder utilidade para desenvolvimento.

## O Que Precisa Ser Definido

1. Lugar de composicao.
   Decidir se o overlay:
   - continua no `gfx` emulado;
   - sobe para camada host nativa;
   - vira surface separada de debug.

2. Politica de strings/glyphs.
   Definir se texto e reconstruido por frame ou cacheado.

3. Custo em modo debug.
   Delimitar qual overhead e aceitavel quando overlay estiver ativo.

4. Efeito na telemetria.
   Fechar se a telemetria deve incluir ou excluir explicitamente o custo do overlay.

## Open Questions de Arquitetura

1. O overlay precisa ser representativo do hardware final ou apenas ferramenta de desktop?
2. Vale um modo "perf puro" onde overlay nunca toca no framebuffer do console?
3. O host deve oferecer toggles separados para stats, logs e overlay visual?

## Dependencias

- `../specs/10-debug-inspection-and-profiling.md`
- `../specs/11-portability-and-cross-platform-execution.md`

## Criterio de Saida Desta Agenda

Pode virar PR quando houver decisao escrita sobre:

- onde o overlay e composto;
- politica de cache de texto/glyphs;
- como o custo do overlay aparece na telemetria;
- overhead maximo aceitavel em modo debug.