adjustments over frame composer contract - agnostic tile size
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

This commit is contained in:
2026-04-15 08:42:46 +01:00
parent d5d63d79c0
commit 98d2d81882
7 changed files with 100 additions and 2 deletions
@@ -54,6 +54,7 @@ Create `FrameComposer` as a concrete driver-side subsystem.
- `SceneViewportResolver`
- `SpriteController`
- Keep scene/cache/resolver fields optional where no-scene operation is required.
- Do not introduce any fixed `16x16` assumption into owned state; tile-size-sensitive behavior must derive from bound scene metadata.
**File(s):**
- `crates/console/prometeu-drivers/src/frame_composer.rs`
@@ -93,6 +94,7 @@ Give the driver layer a stable initial surface for `FrameComposer`.
### Unit Tests
- `FrameComposer` can be constructed without a bound scene.
- `Hardware` successfully constructs with both `gfx` and `frame_composer`.
- Construction and owned state shape do not encode `16x16` as an implicit world-path invariant.
### Integration Tests
- Shared bank access needed by `FrameComposer` is available through hardware construction.
@@ -115,3 +117,4 @@ Give the driver layer a stable initial surface for `FrameComposer`.
- 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.
- Encoding `16x16` into the initial owned-state shape would create a contract violation that later plans would have to unwind.
@@ -15,6 +15,7 @@ Implement the `FrameComposer` scene-binding contract, minimal camera state, and
## 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`.
The same decision also requires `FrameComposer` to remain tile-size agnostic and to preserve canonical per-layer `tile_size`, including `8x8`.
## Scope
@@ -90,6 +91,7 @@ Align cache/resolver lifetime with the active scene contract.
- create or reinitialize cache/resolver.
- On unbind:
- discard cache/resolver and invalidate the world path.
- Any initialization must derive layer math from the bound scene tile sizes instead of assuming `16x16`.
**File(s):**
- `crates/console/prometeu-drivers/src/frame_composer.rs`
@@ -101,6 +103,7 @@ Align cache/resolver lifetime with the active scene contract.
- 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.
- bind/unbind remains valid for scenes whose layers use `8x8` tiles.
### Integration Tests
- `FrameComposer` can resolve a scene from the pool and survive no-scene operation.
@@ -115,6 +118,7 @@ Align cache/resolver lifetime with the active scene contract.
- [ ] Scene status is explicit.
- [ ] Camera contract is implemented as `i32` top-left viewport coordinates.
- [ ] Cache/resolver lifetime follows scene bind/unbind.
- [ ] Scene bind/cache/resolver setup preserves canonical per-layer tile sizes, including `8x8`.
## Dependencies
@@ -15,6 +15,7 @@ Connect `FrameComposer` to `SceneViewportResolver`, apply cache refreshes inside
## 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.
`DEC-0014` also requires the world path to remain tile-size agnostic, with explicit support for `8x8`, `16x16`, and `32x32` scene-layer tile sizes.
## Scope
@@ -41,6 +42,7 @@ Move cache-refresh orchestration fully into `FrameComposer`.
- consume returned `CacheRefreshRequest`s
- apply them to `SceneViewportCache`
- Keep `Gfx` unaware of refresh semantics.
- Ensure resolver and refresh math follow the bound layer `tile_size` values rather than any fixed `16x16` default.
**File(s):**
- `crates/console/prometeu-drivers/src/frame_composer.rs`
@@ -58,6 +60,7 @@ Introduce the new frame service on `FrameComposer`.
- call the cache-backed world path in `Gfx`
- If no scene is active:
- call the no-scene path for `sprites + fades`
- World rendering must remain valid when the active scene uses `8x8` tiles.
**File(s):**
- `crates/console/prometeu-drivers/src/frame_composer.rs`
@@ -87,6 +90,7 @@ Protect the two canonical frame modes.
- no-scene `sprites + fades`
- scene transition through unbind/rebind
- cache refresh behavior staying inside `FrameComposer`
- active-scene composition with `8x8` tile-size layers
**File(s):**
- `crates/console/prometeu-drivers/src/frame_composer.rs`
@@ -98,9 +102,11 @@ Protect the two canonical frame modes.
- `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`.
- `render_frame()` with an `8x8` scene uses resolver/cache math derived from layer tile size rather than a `16x16` assumption.
### Integration Tests
- scene bind + camera set + sprite emission + `render_frame()` produces the expected composed frame.
- scene bind + camera set + `8x8` scene + `render_frame()` produces the expected composed frame.
### Manual Verification
- Verify that no-scene frames still render sprites/fades without crashes or hidden clears.
@@ -112,6 +118,7 @@ Protect the two canonical frame modes.
- [ ] World rendering consumes the cache-backed path.
- [ ] No-scene `sprites + fades` behavior remains valid.
- [ ] `Gfx` remains backend-only for this path.
- [ ] The world path is explicitly covered for `8x8` scenes without `16x16`-specific assumptions.
## Dependencies
@@ -122,3 +129,4 @@ Protect the two canonical frame modes.
- 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.
- If tests cover only `16x16`, a latent compositor regression against canonical `8x8` scenes can ship unnoticed.
@@ -15,6 +15,7 @@ Retire `Gfx.render_all()` from the canonical flow, migrate callsites to `FrameCo
## 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
@@ -68,6 +69,7 @@ Protect the new service model against fallback to the old renderer path.
- 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()`.
@@ -96,6 +98,7 @@ Confirm the migration did not break unrelated systems.
### 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.
@@ -106,6 +109,7 @@ Confirm the migration did not break unrelated systems.
- [ ] `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
@@ -116,3 +120,4 @@ Confirm the migration did not break unrelated systems.
- 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.