Integrate render_all with Scene Cache and Camera

This commit is contained in:
2026-04-14 07:28:00 +01:00
parent 1ad7554762
commit d5d63d79c0
8 changed files with 1147 additions and 1 deletions
@@ -0,0 +1,117 @@
---
id: PLN-0017
ticket: render-all-scene-cache-and-camera-integration
title: Plan - FrameComposer Core and Hardware Ownership
status: accepted
created: 2026-04-14
completed:
tags: [gfx, runtime, render, hardware, frame-composer]
---
## Objective
Introduce `FrameComposer` as a first-class hardware-side subsystem and move canonical frame orchestration ownership out of `Gfx`.
## Background
`DEC-0014` locks `FrameComposer` as the canonical frame orchestration service. The first implementation step is to create the owning type, place it in `hardware/drivers`, and make `Hardware` aggregate it next to `Gfx` without yet completing the full render-path migration.
## Scope
### Included
- Create the `FrameComposer` type in `crates/console/prometeu-drivers`.
- Define the minimal owned state shape:
- active scene binding state;
- camera / viewport state;
- optional cache;
- optional resolver;
- owned `SpriteController`.
- Aggregate `FrameComposer` inside `Hardware`.
- Expose the minimum driver-facing surface required for subsequent plans.
### Excluded
- full sprite-model migration
- full scene binding implementation
- cache refresh application
- render-path retirement of `Gfx.render_all()`
## Execution Steps
### Step 1 - Introduce the `FrameComposer` module and owned state
**What:**
Create `FrameComposer` as a concrete driver-side subsystem.
**How:**
- Add a new module such as `crates/console/prometeu-drivers/src/frame_composer.rs`.
- Define a `FrameComposer` struct with explicit placeholders for:
- `active_scene_id`
- `active_scene`
- `scene_status`
- `camera_x_px`
- `camera_y_px`
- `SceneViewportCache`
- `SceneViewportResolver`
- `SpriteController`
- Keep scene/cache/resolver fields optional where no-scene operation is required.
**File(s):**
- `crates/console/prometeu-drivers/src/frame_composer.rs`
- `crates/console/prometeu-drivers/src/lib.rs`
### Step 2 - Aggregate `FrameComposer` in `Hardware`
**What:**
Make `Hardware` own `FrameComposer` alongside `Gfx`.
**How:**
- Extend `Hardware` with a `frame_composer` field.
- Wire construction so `FrameComposer` receives the shared bank access it needs for later plans.
- Keep ownership boundaries explicit: `FrameComposer` prepares frame state, `Gfx` remains backend.
**File(s):**
- `crates/console/prometeu-drivers/src/hardware.rs`
- `crates/console/prometeu-drivers/src/memory_banks.rs`
### Step 3 - Define the minimum public driver-facing surface
**What:**
Give the driver layer a stable initial surface for `FrameComposer`.
**How:**
- Expose minimal constructor and accessor paths.
- Do not yet overdesign HAL-facing traits.
- Ensure the code compiles with no implicit dependence on `Gfx.render_all()` ownership for frame state.
**File(s):**
- `crates/console/prometeu-drivers/src/frame_composer.rs`
- `crates/console/prometeu-drivers/src/hardware.rs`
- `crates/console/prometeu-drivers/src/lib.rs`
## Test Requirements
### Unit Tests
- `FrameComposer` can be constructed without a bound scene.
- `Hardware` successfully constructs with both `gfx` and `frame_composer`.
### Integration Tests
- Shared bank access needed by `FrameComposer` is available through hardware construction.
### Manual Verification
- Inspect the resulting type ownership and confirm scene/sprite state is no longer being newly introduced into `Gfx`.
## Acceptance Criteria
- [ ] `FrameComposer` exists as a dedicated driver-side subsystem.
- [ ] `Hardware` aggregates `FrameComposer` next to `Gfx`.
- [ ] `FrameComposer` has explicit owned placeholders for scene/camera/cache/resolver/sprites.
- [ ] The build remains green with the new ownership structure in place.
## Dependencies
- Source decision: `DEC-0014`
## Risks
- Introducing `FrameComposer` with too much behavior too early can blur later migration steps.
- Introducing too little owned state can leave ownership ambiguous and force rework in later plans.
@@ -0,0 +1,127 @@
---
id: PLN-0018
ticket: render-all-scene-cache-and-camera-integration
title: Plan - SpriteController and Frame Emission Model
status: accepted
created: 2026-04-14
completed:
tags: [gfx, runtime, render, sprites, frame-composer]
---
## Objective
Replace the slot-first sprite model with a `FrameComposer`-owned `SpriteController` that emits sprites per frame instead of relying on `Sprite.active` and caller-provided indices.
## Background
`DEC-0014` removes `Sprite.active` from the canonical operational model and locks sprite submission to a frame-emission model owned by `SpriteController`.
## Scope
### Included
- Introduce `SpriteController`.
- Remove the operational dependence on `Sprite.active`.
- Remove caller-owned sprite indices from the canonical submission path.
- Add layer + priority ordering with FIFO tie-breaking.
- Preserve the capacity cap of `512` sprites per frame.
### Excluded
- HUD integration
- scene binding
- cache refresh logic
## Execution Steps
### Step 1 - Redefine the sprite operational model
**What:**
Move canonical sprite submission semantics from slot-first to frame-emission.
**How:**
- Update `Sprite` and adjacent APIs so the canonical path no longer depends on `active`.
- Keep layer numeric and aligned with the scene layer reference type.
- Preserve `priority` as the within-layer ordering field.
**File(s):**
- `crates/console/prometeu-hal/src/sprite.rs`
- any adjacent driver-side sprite helpers
### Step 2 - Implement `SpriteController`
**What:**
Create the owned sprite subsystem under `FrameComposer`.
**How:**
- Add a `SpriteController` type with:
- storage capacity `512`
- frame counter
- per-layer buckets
- stable FIFO semantics for equal priority
- Add `begin_frame()` behavior that clears counters and buckets.
- Add `emit_sprite(...)` behavior that appends to the next internal slot.
**File(s):**
- `crates/console/prometeu-drivers/src/frame_composer.rs`
- optional dedicated `sprite_controller.rs`
### Step 3 - Handle overflow and logging semantics
**What:**
Implement overflow behavior without turning it into a hard runtime failure.
**How:**
- Ignore sprites emitted after capacity is reached.
- Leave explicit room for system logging / telemetry.
- Do not add a special reset API beyond the normal frame lifecycle.
**File(s):**
- `crates/console/prometeu-drivers/src/frame_composer.rs`
- related telemetry/log hooks if needed
### Step 4 - Remove stale slot-first sprite entrypoints
**What:**
Retire the old “set sprite by explicit index” path from the canonical model.
**How:**
- Identify the current caller-facing `Gfx` sprite mutation surface.
- Migrate it toward `FrameComposer`-owned submission.
- Keep transitional shims only if required to preserve buildability for the next plan.
**File(s):**
- `crates/console/prometeu-drivers/src/gfx.rs`
- `crates/console/prometeu-hal/src/gfx_bridge.rs`
- `crates/console/prometeu-drivers/src/frame_composer.rs`
## Test Requirements
### Unit Tests
- `begin_frame()` resets sprite count and buckets.
- `emit_sprite(...)` appends without caller-provided index.
- lower `priority` renders first within a layer.
- equal `priority` resolves FIFO by registration order.
- overflow drops excess sprites without panicking.
### Integration Tests
- `FrameComposer` can emit sprites and provide ordered sprite state for rendering.
### Manual Verification
- Confirm no canonical submission path requires `Sprite.active` or explicit slot index anymore.
## Acceptance Criteria
- [ ] `SpriteController` exists under `FrameComposer`.
- [ ] `Sprite.active` is no longer required by the canonical frame path.
- [ ] Caller-provided sprite indices are retired from the canonical submission path.
- [ ] Layer/priority/FIFO ordering is implemented and tested.
- [ ] Overflow is ignored with space left for logging.
## Dependencies
- Depends on `PLN-0017`
- Source decision: `DEC-0014`
## Risks
- Keeping compatibility shims too long can leave the codebase in a dual sprite model.
- Removing index-based APIs too early may break callsites before `FrameComposer` integration is ready.
@@ -0,0 +1,127 @@
---
id: PLN-0019
ticket: render-all-scene-cache-and-camera-integration
title: Plan - Scene Binding, Camera, and Scene Status
status: accepted
created: 2026-04-14
completed:
tags: [gfx, runtime, render, scene, camera, frame-composer]
---
## Objective
Implement the `FrameComposer` scene-binding contract, minimal camera state, and explicit scene-availability status without yet completing the cache-refresh render path.
## Background
`DEC-0014` locks scene activation around `bind_scene(scene_bank_id)` with `SceneBankPoolAccess`, pointer-based access only, and `scene_bank_id + Arc<SceneBank>` retained inside `FrameComposer`.
## Scope
### Included
- scene bind/unbind contract
- active scene identity and shared reference storage
- scene availability status
- minimal camera state (`i32`, top-left viewport)
### Excluded
- applying cache refreshes
- full render-path migration
- HUD behavior
## Execution Steps
### Step 1 - Add scene binding state to `FrameComposer`
**What:**
Implement the canonical bind/unbind surface.
**How:**
- Add `bind_scene(scene_bank_id)` and `unbind_scene()`.
- Resolve scenes from `SceneBankPoolAccess`.
- Store both:
- `scene_bank_id`
- `Arc<SceneBank>`
- Replace prior scene binding completely on a new bind.
**File(s):**
- `crates/console/prometeu-drivers/src/frame_composer.rs`
- `crates/console/prometeu-drivers/src/memory_banks.rs`
### Step 2 - Add explicit scene status
**What:**
Expose scene availability through status, not just implicit option checks.
**How:**
- Define a scene status enum or equivalent status object.
- Distinguish at least:
- no scene bound
- bound and available
- bound but not renderable if such intermediate state is needed
- Ensure no-scene rendering remains valid.
**File(s):**
- `crates/console/prometeu-drivers/src/frame_composer.rs`
- optional HAL-facing status surface if needed later
### Step 3 - Add camera contract
**What:**
Implement the V1 camera ownership inside `FrameComposer`.
**How:**
- Add `set_camera(x, y)`.
- Store camera coordinates as `i32`.
- Treat them as top-left viewport coordinates in world space.
- Keep all advanced camera behavior out of scope.
**File(s):**
- `crates/console/prometeu-drivers/src/frame_composer.rs`
### Step 4 - Tie cache/resolver lifetime to scene binding
**What:**
Align cache/resolver lifetime with the active scene contract.
**How:**
- Cache and resolver remain `None` / absent when no scene is bound.
- On bind:
- create or reinitialize cache/resolver.
- On unbind:
- discard cache/resolver and invalidate the world path.
**File(s):**
- `crates/console/prometeu-drivers/src/frame_composer.rs`
## Test Requirements
### Unit Tests
- bind stores `scene_bank_id + Arc<SceneBank>`.
- unbind clears active scene and cache.
- scene status reflects no-scene and active-scene states.
- camera coordinates are stored as top-left pixel-space values.
### Integration Tests
- `FrameComposer` can resolve a scene from the pool and survive no-scene operation.
### Manual Verification
- Confirm scene access remains pointer-based and no scene copies are introduced.
## Acceptance Criteria
- [ ] `FrameComposer` binds scenes by bank id through `SceneBankPoolAccess`.
- [ ] Active binding stores both scene id and shared scene reference.
- [ ] Scene status is explicit.
- [ ] Camera contract is implemented as `i32` top-left viewport coordinates.
- [ ] Cache/resolver lifetime follows scene bind/unbind.
## Dependencies
- Depends on `PLN-0017`
- Source decision: `DEC-0014`
## Risks
- Weak scene-status semantics can make no-scene behavior ambiguous in later render integration.
- If cache/resolver lifetime is not tied cleanly to binding, stale world state can leak across scene transitions.
@@ -0,0 +1,124 @@
---
id: PLN-0020
ticket: render-all-scene-cache-and-camera-integration
title: Plan - Cache Refresh and render_frame Path
status: accepted
created: 2026-04-14
completed:
tags: [gfx, runtime, render, cache, resolver, frame-composer]
---
## Objective
Connect `FrameComposer` to `SceneViewportResolver`, apply cache refreshes inside `FrameComposer`, and establish `render_frame()` as the canonical composition path for world + sprites + fades.
## Background
`DEC-0014` requires that cache refresh policy remain inside `FrameComposer` and that `FrameComposer.render_frame()` become the canonical frame entry while `Gfx` remains only the low-level execution backend.
## Scope
### Included
- apply `CacheRefreshRequest`s in `FrameComposer`
- connect camera/scene state to resolver updates
- use cache-backed world rendering in the frame path
- keep valid no-scene rendering (`sprites + fades`)
### Excluded
- HUD integration
- final retirement cleanup of legacy callsites
## Execution Steps
### Step 1 - Apply resolver refreshes inside `FrameComposer`
**What:**
Move cache-refresh orchestration fully into `FrameComposer`.
**How:**
- On active-scene frames:
- call resolver update with current camera and scene
- consume returned `CacheRefreshRequest`s
- apply them to `SceneViewportCache`
- Keep `Gfx` unaware of refresh semantics.
**File(s):**
- `crates/console/prometeu-drivers/src/frame_composer.rs`
### Step 2 - Define `render_frame()` as the canonical frame path
**What:**
Introduce the new frame service on `FrameComposer`.
**How:**
- Add `render_frame()` to `FrameComposer`.
- If a scene is active and renderable:
- prepare resolver update
- refresh cache
- call the cache-backed world path in `Gfx`
- If no scene is active:
- call the no-scene path for `sprites + fades`
**File(s):**
- `crates/console/prometeu-drivers/src/frame_composer.rs`
- `crates/console/prometeu-drivers/src/gfx.rs`
### Step 3 - Keep `Gfx` as backend only
**What:**
Narrow `Gfx` to backend-oriented composition responsibilities.
**How:**
- Ensure `Gfx` consumes prepared state from `FrameComposer`.
- Do not let `Gfx` regain ownership of cache refresh or scene orchestration.
- Keep low-level helpers for cache-backed copy paths, sprite drawing, and fades in `Gfx`.
**File(s):**
- `crates/console/prometeu-drivers/src/gfx.rs`
### Step 4 - Cover scene and no-scene frame paths
**What:**
Protect the two canonical frame modes.
**How:**
- Add tests for:
- active-scene world composition
- no-scene `sprites + fades`
- scene transition through unbind/rebind
- cache refresh behavior staying inside `FrameComposer`
**File(s):**
- `crates/console/prometeu-drivers/src/frame_composer.rs`
- `crates/console/prometeu-drivers/src/gfx.rs`
## Test Requirements
### Unit Tests
- `render_frame()` with no scene produces valid no-scene composition.
- `render_frame()` with a scene applies resolver refreshes before composition.
- cache refresh requests are applied by `FrameComposer`, not `Gfx`.
### Integration Tests
- scene bind + camera set + sprite emission + `render_frame()` produces the expected composed frame.
### Manual Verification
- Verify that no-scene frames still render sprites/fades without crashes or hidden clears.
## Acceptance Criteria
- [ ] `FrameComposer.render_frame()` exists and is the canonical frame path.
- [ ] Cache refreshes are applied inside `FrameComposer`.
- [ ] World rendering consumes the cache-backed path.
- [ ] No-scene `sprites + fades` behavior remains valid.
- [ ] `Gfx` remains backend-only for this path.
## Dependencies
- Depends on `PLN-0017`, `PLN-0018`, and `PLN-0019`
- Source decision: `DEC-0014`
## Risks
- If refresh application leaks into `Gfx`, the ownership split from `DEC-0014` collapses.
- If no-scene behavior is not tested explicitly, scene integration can accidentally make scene binding mandatory.
@@ -0,0 +1,118 @@
---
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.
## 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
- 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.
### 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.
## 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.