68 lines
2.8 KiB
Markdown
68 lines
2.8 KiB
Markdown
---
|
|
id: PLN-0073
|
|
ticket: render-frame-packet-boundary
|
|
title: Render Contract Specs
|
|
status: done
|
|
created: 2026-05-25
|
|
ref_decisions: [DEC-0030]
|
|
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Source decision: `DEC-0030`.
|
|
|
|
Publish canonical English spec language for the logical render pipeline boundary before code migration. The specs must make `RenderManager`, domain buffers, typed `RenderSubmission`, app-mode routing, render-surface publication, latest-complete-submission policy, and fade removal explicit.
|
|
|
|
## Target
|
|
|
|
Canonical specs describe the DEC-0030 render contract well enough that HAL, runtime, host, firmware, and PBS work can proceed without reopening architecture.
|
|
|
|
## Scope
|
|
|
|
- Define the logical flow from mutable domain buffers to closed `RenderSubmission` to render-surface publication.
|
|
- Define `RenderManager` as runtime coordination, not a host renderer.
|
|
- Define `RenderSubmission` with `frame_id`, `app_mode`, and typed Game 2D or Shell UI packet.
|
|
- Define `composer.*`, `gfx2d.*`, and `gfxui.*` as separate ABI domains.
|
|
- Specify latest-complete-submission-wins backpressure.
|
|
- Remove fade from canonical render contracts.
|
|
|
|
## Out of Scope
|
|
|
|
- Rust implementation.
|
|
- PBS stdlib implementation.
|
|
- Pixel output changes.
|
|
- Backend registry, GPU backend, render thread, 3D pipeline, or debug console design.
|
|
|
|
## Execution Sequence
|
|
|
|
1. Inventory existing render, graphics, framebuffer, composer, and syscall specs.
|
|
2. Replace old primitive `gfx.*` ABI language with the DEC-0030 domain split.
|
|
3. Add sections for `RenderManager`, domain buffers, submission closure, immutability, and publication.
|
|
4. Add app-mode and capability routing language for Game and Shell.
|
|
5. Remove normative fade fields, syscalls, and packet references from render specs.
|
|
6. Cross-link impacted specs for HAL, runtime, host, firmware, and PBS propagation.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Specs are in English and reference `DEC-0030`.
|
|
- No canonical render spec presents direct framebuffer mutation as the logical render API.
|
|
- No canonical render spec keeps fade as a packet field, syscall, or ABI habit.
|
|
- Specs distinguish logical pipeline production from render-surface implementation.
|
|
|
|
## Tests / Validation
|
|
|
|
- Run repository documentation/spec validation if available.
|
|
- Inspect `rg -n "fade|gfx\\.\\*|RenderSubmission|RenderManager|present\\(" specs discussion/workflow/decisions/DEC-0030-logical-render-pipeline-command-boundary.md`.
|
|
- Run `discussion validate` if discussion references change.
|
|
|
|
## Risks
|
|
|
|
- Existing specs may use `gfx.*` as both author API and ABI name; preserve author clarity while changing ABI names.
|
|
- Removing fade text can accidentally delete transition requirements; move those requirements to `RenderManager` language.
|
|
|
|
## Affected Artifacts
|
|
|
|
- `specs/`
|
|
- `discussion/workflow/decisions/DEC-0030-logical-render-pipeline-command-boundary.md`
|