128 lines
3.6 KiB
Markdown
128 lines
3.6 KiB
Markdown
---
|
|
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.
|