145 lines
8.1 KiB
Markdown
145 lines
8.1 KiB
Markdown
---
|
|
id: PLN-0008
|
|
ticket: perf-host-debug-overlay-isolation
|
|
title: PR/Plan - Host Overlay Native Composition Alignment
|
|
status: in_progress
|
|
created: 2026-04-10
|
|
completed:
|
|
tags: [performance, host, gfx, telemetry]
|
|
---
|
|
|
|
## Objective
|
|
|
|
Bring the desktop debug overlay implementation back into compliance with `DEC-0007`, `DEC-0009`, and `DEC-0010` by keeping the overlay in the host layer while rendering it in a dedicated host module and separate host layer, outside the emulated hardware framebuffer and outside `hardware.gfx`.
|
|
|
|
## Background
|
|
|
|
`DEC-0007` requires the debug overlay to be a host-only layer composed after the emulated frame is complete. `DEC-0009` further clarifies that `fill_rect` and `draw_text` remain part of the emulated machine contract, but the host overlay must not depend on them and must live in a dedicated host module and separate host layer. `DEC-0010` fixes the semantics of the visible `LOGS` metric so the Host overlay reads the last completed frame value instead of a transient intra-frame counter.
|
|
|
|
The current `HostRunner` still calls `hardware.gfx.fill_rect()` and `hardware.gfx.draw_text()` for the overlay, which means the HUD is still being injected into the emulated graphics path even though its data source already comes from `AtomicTelemetry`.
|
|
|
|
`PLN-0007` completed the telemetry migration, so the remaining gap is no longer data access. The remaining gap is presentation architecture in the desktop host.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- Remove all overlay rendering calls that write through `hardware.gfx`.
|
|
- Introduce a desktop-host-native overlay composition path in `prometeu-host-desktop-winit`.
|
|
- Implement the overlay in a dedicated host module instead of ad hoc logic inside `runner.rs`.
|
|
- Keep overlay visibility and lifecycle fully controlled by the desktop host.
|
|
- Continue reading inspection data through `AtomicTelemetry::snapshot()` and host-side log access.
|
|
- Expose `LOGS` to the overlay as the last completed logical frame value.
|
|
- Update runtime specifications so they explicitly state that the overlay is host-native and not part of the emulated machine framebuffer.
|
|
- Add verification that enabling the overlay does not mutate emulated pixels.
|
|
|
|
### Excluded
|
|
- Adding overlays to non-desktop hosts.
|
|
- Reopening the telemetry model or changing `TelemetryFrame` semantics.
|
|
- Reworking unrelated presentation, frame pacing, debugger transport, or certification behavior.
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Extract overlay responsibilities into a dedicated host module
|
|
|
|
**What:**
|
|
Move overlay formatting, layout, and drawing responsibilities out of `runner.rs` and into a dedicated host module.
|
|
|
|
**How:**
|
|
Create a dedicated module such as `overlay.rs` that owns host overlay data preparation, panel layout, simple bars, and text rendering. `runner.rs` should orchestrate visibility and presentation only. The new module must never call emulated graphics primitives.
|
|
|
|
**File(s):**
|
|
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
|
|
- `crates/host/prometeu-host-desktop-winit/src/stats.rs`
|
|
- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
|
|
|
|
### Step 2 - Compose the overlay in a separate host layer
|
|
|
|
**What:**
|
|
Ensure the overlay is rendered in a separate host layer/surface and never blitted into the emulated framebuffer.
|
|
|
|
**How:**
|
|
Preserve the `F1` toggle in `HostRunner`, keep telemetry reads on the host side, and present the overlay after the emulated frame is already ready for display. The implementation may transport the emulated framebuffer into the host presentation surface, but the overlay must remain a separate host composition step and must not write back into `hardware.gfx`.
|
|
|
|
**File(s):**
|
|
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
|
|
- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
|
|
|
|
### Step 3 - Add regression coverage for framebuffer purity
|
|
|
|
**What:**
|
|
Add tests or deterministic checks that prove the overlay no longer modifies emulated graphics output.
|
|
|
|
**How:**
|
|
Cover the overlay toggle and composition boundary with focused host tests where practical. At minimum, add a test seam or helper that lets the host render path be exercised without requiring overlay drawing through `hardware.gfx`. If a full automated framebuffer assertion is not practical yet, add a narrow unit test around the new composition entry point plus manual verification instructions that compare raw emulated output with overlay enabled and disabled.
|
|
|
|
**File(s):**
|
|
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
|
|
- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
|
|
- `crates/host/prometeu-host-desktop-winit/src/tests.rs` or existing test module location
|
|
|
|
### Step 4 - Align log metric semantics with frame-end snapshots
|
|
|
|
**What:**
|
|
Ensure the visible `LOGS` metric represents the last completed frame instead of a transient in-flight counter.
|
|
|
|
**How:**
|
|
Persist the completed-frame log count into `AtomicTelemetry` before resetting the transient `LogService` counter. Keep certification evaluation and host overlay consumption aligned on that persisted frame-end value.
|
|
|
|
**File(s):**
|
|
- `crates/console/prometeu-hal/src/log/log_service.rs`
|
|
- `crates/console/prometeu-hal/src/telemetry.rs`
|
|
- `crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs`
|
|
- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
|
|
|
|
### Step 5 - Update normative documentation
|
|
|
|
**What:**
|
|
Align specs and workflow artifacts with the corrected execution path.
|
|
|
|
**How:**
|
|
Update the runtime debug and portability specifications to explicitly say the overlay is desktop-host-native, post-upscaling, and outside the emulated framebuffer. Keep the discussion workflow aligned by referencing this corrective plan during execution and closure.
|
|
|
|
**File(s):**
|
|
- `docs/specs/runtime/10-debug-inspection-and-profiling.md`
|
|
- `docs/specs/runtime/11-portability-and-cross-platform-execution.md`
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
- Host overlay toggle logic remains host-owned and does not require `hardware.gfx` text drawing.
|
|
- New host-native overlay composition entry point can format and present telemetry without mutating the emulated framebuffer abstraction.
|
|
- Simple bars and text layout are owned by the dedicated host overlay module.
|
|
|
|
### Integration Tests
|
|
- `cargo check` for `prometeu-host-desktop-winit`, `prometeu-system`, and any touched supporting crate.
|
|
- If automated host rendering tests are feasible, verify an emulated frame buffer dump is identical with overlay off and overlay on before the host-only composition stage.
|
|
|
|
### Manual Verification
|
|
- Run the desktop host, toggle `F1`, and confirm the overlay appears and disappears correctly.
|
|
- Capture or inspect the emulated framebuffer path and confirm no HUD pixels are written into machine output.
|
|
- Confirm telemetry values still update through `AtomicTelemetry`.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] No desktop overlay code writes through `hardware.gfx.fill_rect`, `hardware.gfx.draw_text`, or equivalent emulated-machine drawing APIs.
|
|
- [ ] `fill_rect` and `draw_text` remain intact as part of the emulated graphics contract and are not repurposed for host overlay rendering.
|
|
- [ ] The desktop overlay remains controlled by `HostRunner` and uses host-side telemetry snapshots.
|
|
- [ ] The visible overlay is composed in a separate host layer after the emulated frame and is not burned into the emulated framebuffer.
|
|
- [ ] Runtime telemetry remains gated by inspection state and continues to function for overlay consumption.
|
|
- [ ] The visible `LOGS` metric represents the last completed logical frame.
|
|
- [ ] Specs describe the overlay as host-native and outside the emulated hardware contract.
|
|
|
|
## Dependencies
|
|
|
|
- `DEC-0007` accepted and unchanged.
|
|
- `DEC-0008` accepted and unchanged.
|
|
- `DEC-0009` accepted and unchanged.
|
|
- `DEC-0010` accepted and unchanged.
|
|
- Existing `AtomicTelemetry` host snapshot path remains available.
|
|
|
|
## Risks
|
|
|
|
- Desktop-native text and alpha composition may require extra host rendering plumbing that is more complex than the previous `hardware.gfx` path.
|
|
- Without an explicit test seam, it is easy to accidentally reintroduce overlay writes into the emulated graphics path during future host refactors.
|
|
- Host composition cost may rise slightly, but that cost is acceptable as long as it remains outside runtime cycle accounting.
|