70 lines
2.4 KiB
Markdown
70 lines
2.4 KiB
Markdown
---
|
|
id: PLN-0082
|
|
ticket: render-frame-packet-boundary
|
|
title: Frame Publication and Present Boundary
|
|
status: open
|
|
created: 2026-05-25
|
|
ref_decisions: [DEC-0030]
|
|
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Source decision: `DEC-0030`.
|
|
|
|
Move `present()` and surface publication behind the render-surface implementation boundary so runtime producers no longer publish buffers directly.
|
|
|
|
## Target
|
|
|
|
Only the render-surface implementation publishes RGBA8888 output; logical producers and `RenderManager` hand off closed submissions through a boundary.
|
|
|
|
## Scope
|
|
|
|
- Identify all direct `present()` and surface publication callsites.
|
|
- Define the render-surface adapter boundary.
|
|
- Route publication through the adapter from `RenderManager`.
|
|
- Keep desktop `pixels` publication as a host implementation detail.
|
|
- Preserve frame pacing and invalidation behavior.
|
|
|
|
## Out of Scope
|
|
|
|
- New backend registry.
|
|
- GPU implementation.
|
|
- Render thread.
|
|
- Dirty regions.
|
|
- Visual transition design.
|
|
|
|
## Execution Sequence
|
|
|
|
1. Inventory `present()`, framebuffer publication, and host invalidation callsites.
|
|
2. Add or refine a render-surface trait/adapter that consumes `RenderSubmission`.
|
|
3. Move host desktop publication below that adapter.
|
|
4. Update runtime frame loop to publish only through `RenderManager` and the adapter.
|
|
5. Remove direct publication from composer, `gfx2d`, `gfxui`, Shell, and Game producers.
|
|
6. Verify frame pacing and host invalidation still occur at the correct boundary.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Logical render domains cannot call `present()` or publish buffers directly.
|
|
- Host desktop publication remains functional below the render-surface boundary.
|
|
- `RenderManager` owns the policy for selecting the latest complete submission.
|
|
- Existing frame pacing behavior is not regressed.
|
|
|
|
## Tests / Validation
|
|
|
|
- Add unit tests for render-surface handoff.
|
|
- Add integration tests proving producers cannot publish directly.
|
|
- Run host desktop render/pacing tests.
|
|
- Inspect `rg -n "present\\(|publish|pixels" crates` for boundary violations.
|
|
|
|
## Risks
|
|
|
|
- Publication and invalidation may be coupled in current host code; preserve timing semantics while moving ownership.
|
|
- A too-broad adapter can become a backend registry prematurely.
|
|
|
|
## Affected Artifacts
|
|
|
|
- Runtime render manager modules
|
|
- Host desktop render surface modules
|
|
- Frame pacing tests
|