124 lines
4.1 KiB
Markdown
124 lines
4.1 KiB
Markdown
---
|
|
id: PLN-0021
|
|
ticket: render-all-scene-cache-and-camera-integration
|
|
title: Plan - Service Retirement, Callsite Migration, and Regression Coverage
|
|
status: accepted
|
|
created: 2026-04-14
|
|
completed:
|
|
tags: [gfx, runtime, render, migration, regression]
|
|
---
|
|
|
|
## Objective
|
|
|
|
Retire `Gfx.render_all()` from the canonical flow, migrate callsites to `FrameComposer.render_frame()`, and add the regression coverage needed to lock the new service model.
|
|
|
|
## Background
|
|
|
|
`DEC-0014` is explicit that `Gfx.render_all()` must be retired and that `FrameComposer.render_frame()` becomes the canonical frame orchestration entrypoint. This final plan removes the old canonical service shape and validates the migration end-to-end.
|
|
The same decision also requires the new canonical path to preserve scene-layer tile sizes such as `8x8`, not just `16x16`.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- retire `Gfx.render_all()` from the canonical path
|
|
- migrate frame-loop callsites
|
|
- align bridge surfaces as needed
|
|
- add regression coverage for the final service model
|
|
|
|
### Excluded
|
|
- HUD integration
|
|
- future certification behavior for sprite overflow
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Migrate frame-loop callsites
|
|
|
|
**What:**
|
|
Switch runtime frame execution from `Gfx.render_all()` to `FrameComposer.render_frame()`.
|
|
|
|
**How:**
|
|
- Identify all canonical callsites that currently trigger `Gfx.render_all()`.
|
|
- Update them to go through `FrameComposer`.
|
|
- Preserve present/swap behavior after the render call.
|
|
|
|
**File(s):**
|
|
- `crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs`
|
|
- any additional runtime frame-loop callsites
|
|
|
|
### Step 2 - Retire `Gfx.render_all()` from the canonical service surface
|
|
|
|
**What:**
|
|
Remove the old frame service as the operational entry.
|
|
|
|
**How:**
|
|
- Remove or deprecate `render_all()` from `Gfx` and `GfxBridge` as the canonical render entry.
|
|
- Keep only backend-oriented helpers that `FrameComposer` calls.
|
|
- Ensure the naming and public path converge to Rust-style `render_frame()`.
|
|
|
|
**File(s):**
|
|
- `crates/console/prometeu-hal/src/gfx_bridge.rs`
|
|
- `crates/console/prometeu-drivers/src/gfx.rs`
|
|
|
|
### Step 3 - Add end-to-end regression coverage
|
|
|
|
**What:**
|
|
Protect the new service model against fallback to the old renderer path.
|
|
|
|
**How:**
|
|
- Add tests that prove:
|
|
- frame-loop code calls `FrameComposer.render_frame()`
|
|
- no-scene frames remain valid
|
|
- active-scene frames render through cache-backed composition
|
|
- active-scene frames remain valid for canonical `8x8` scenes
|
|
- sprite emission and ordering survive the full path
|
|
- Add assertions or test failures for accidental continued reliance on `Gfx.render_all()`.
|
|
|
|
**File(s):**
|
|
- runtime tests
|
|
- driver tests
|
|
- bridge tests where needed
|
|
|
|
### Step 4 - Validate full repository behavior
|
|
|
|
**What:**
|
|
Confirm the migration did not break unrelated systems.
|
|
|
|
**How:**
|
|
- Run the repository validation command required by current practice.
|
|
- Keep regression evidence attached to the plan execution.
|
|
|
|
**File(s):**
|
|
- repository-wide CI / validation entrypoints
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
- `Gfx` no longer exposes `render_all()` as the canonical operational frame path.
|
|
|
|
### Integration Tests
|
|
- runtime tick path renders through `FrameComposer.render_frame()`.
|
|
- no-scene and active-scene frame modes both remain valid.
|
|
- runtime tick path remains valid when the active scene uses `8x8` tiles.
|
|
|
|
### Manual Verification
|
|
- Run the repository CI path and confirm the final integrated service model is green.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] Frame-loop callsites use `FrameComposer.render_frame()`.
|
|
- [ ] `Gfx.render_all()` is retired from the canonical service path.
|
|
- [ ] Regression coverage protects against fallback to the old model.
|
|
- [ ] Repository validation passes after the migration.
|
|
- [ ] Regression coverage includes the canonical `8x8` world-path case.
|
|
|
|
## Dependencies
|
|
|
|
- Depends on `PLN-0017`, `PLN-0018`, `PLN-0019`, and `PLN-0020`
|
|
- Source decision: `DEC-0014`
|
|
|
|
## Risks
|
|
|
|
- Removing `render_all()` too early can strand intermediate callsites.
|
|
- Leaving it in place as a canonical path for too long can create a dual-service model that is harder to remove later.
|
|
- Migrating callsites without `8x8` regression coverage can falsely validate only the legacy `16x16` path.
|