implements PLN-0041 scene glyph runtime resolution

This commit is contained in:
2026-04-24 11:08:39 +01:00
parent 26686c288c
commit 0d6ff430a0
14 changed files with 368 additions and 109 deletions
@@ -1,3 +1,4 @@
use crate::asset::GlyphAssetSlotIndex;
use crate::memory_banks::SceneBankPoolAccess;
use prometeu_hal::GfxBridge;
use prometeu_hal::glyph::Glyph;
@@ -116,6 +117,7 @@ impl SpriteController {
pub struct FrameComposer {
scene_bank_pool: Arc<dyn SceneBankPoolAccess>,
glyph_slot_index: GlyphAssetSlotIndex,
viewport_width_px: usize,
viewport_height_px: usize,
active_scene_id: Option<usize>,
@@ -133,9 +135,11 @@ impl FrameComposer {
viewport_width_px: usize,
viewport_height_px: usize,
scene_bank_pool: Arc<dyn SceneBankPoolAccess>,
glyph_slot_index: GlyphAssetSlotIndex,
) -> Self {
Self {
scene_bank_pool,
glyph_slot_index,
viewport_width_px,
viewport_height_px,
active_scene_id: None,
@@ -187,6 +191,8 @@ impl FrameComposer {
return false;
};
let _ = self.resolve_glyph_slots(&scene, scene_bank_id, "bind_scene");
let (cache, resolver) =
Self::build_scene_runtime(self.viewport_width_px, self.viewport_height_px, &scene);
self.active_scene_id = Some(scene_bank_id);
@@ -242,15 +248,19 @@ impl FrameComposer {
let ordered_sprites = self.ordered_sprites();
gfx.load_frame_sprites(&ordered_sprites);
if let (Some(scene), Some(cache), Some(resolver)) =
(self.active_scene.as_deref(), self.cache.as_mut(), self.resolver.as_mut())
{
if let Some(scene) = self.active_scene.as_deref() {
let scene_bank_id = self.active_scene_id.expect("active scene id must exist");
let resolved_glyph_slots =
self.resolve_glyph_slots(scene, scene_bank_id, "render_frame");
let (Some(cache), Some(resolver)) = (self.cache.as_mut(), self.resolver.as_mut()) else {
panic!("SCENE runtime invariant broken: active scene without cache/resolver");
};
let update = resolver.update(scene, self.camera_x_px, self.camera_y_px);
Self::apply_refresh_requests(cache, scene, &update.refresh_requests);
// `FrameComposer` owns only canonical game-frame composition.
// Deferred `gfx.*` primitives are drained later by a separate
// overlay/debug stage outside this service boundary.
gfx.render_scene_from_cache(cache, &update);
gfx.render_scene_from_cache(cache, &update, &resolved_glyph_slots);
return;
}
@@ -284,6 +294,23 @@ impl FrameComposer {
)
}
fn resolve_glyph_slots(
&self,
scene: &SceneBank,
scene_bank_id: usize,
phase: &str,
) -> [usize; 4] {
std::array::from_fn(|layer_index| {
let layer = &scene.layers[layer_index];
self.glyph_slot_index.glyph_slot_for_asset(layer.glyph_asset_id).unwrap_or_else(|| {
panic!(
"SCENE dependency fatal during {}: scene_bank_id={}, layer={}, glyph_asset_id={}",
phase, scene_bank_id, layer_index, layer.glyph_asset_id
)
})
})
}
fn apply_refresh_requests(
cache: &mut SceneViewportCache,
scene: &SceneBank,
@@ -316,23 +343,25 @@ mod tests {
GlyphBankPoolAccess, GlyphBankPoolInstaller, MemoryBanks, SceneBankPoolInstaller,
};
use prometeu_hal::color::Color;
use prometeu_hal::asset::AssetId;
use prometeu_hal::glyph_bank::{GlyphBank, TileSize};
use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer};
use prometeu_hal::tile::Tile;
use prometeu_hal::tilemap::TileMap;
use std::panic::{AssertUnwindSafe, catch_unwind};
fn make_scene() -> SceneBank {
make_scene_with_palette(1, 1, TileSize::Size8)
}
fn make_scene_with_palette(
glyph_bank_id: u8,
glyph_asset_id: AssetId,
palette_id: u8,
tile_size: TileSize,
) -> SceneBank {
let layer = SceneLayer {
active: true,
glyph_bank_id,
glyph_asset_id,
tile_size,
parallax_factor: ParallaxFactor { x: 1.0, y: 0.5 },
tilemap: TileMap {
@@ -353,6 +382,16 @@ mod tests {
SceneBank { layers: std::array::from_fn(|_| layer.clone()) }
}
fn make_glyph_slot_index(bindings: &[(AssetId, usize)]) -> GlyphAssetSlotIndex {
let index = GlyphAssetSlotIndex::new();
let mut slots = [None; 16];
for (asset_id, slot) in bindings {
slots[*slot] = Some(*asset_id);
}
index.rebuild_from_slots(&slots);
index
}
fn make_glyph_bank(tile_size: TileSize, palette_id: u8, color: Color) -> GlyphBank {
let size = tile_size as usize;
let mut bank = GlyphBank::new(tile_size, size, size);
@@ -365,7 +404,12 @@ mod tests {
#[test]
fn frame_composer_starts_unbound_with_empty_owned_state() {
let frame_composer = FrameComposer::new(320, 180, Arc::new(MemoryBanks::new()));
let frame_composer = FrameComposer::new(
320,
180,
Arc::new(MemoryBanks::new()),
make_glyph_slot_index(&[]),
);
assert_eq!(frame_composer.viewport_size(), (320, 180));
assert_eq!(frame_composer.active_scene_id(), None);
@@ -384,7 +428,7 @@ mod tests {
let banks = Arc::new(MemoryBanks::new());
banks.install_scene_bank(3, Arc::new(make_scene()));
let frame_composer = FrameComposer::new(320, 180, banks);
let frame_composer = FrameComposer::new(320, 180, banks, make_glyph_slot_index(&[(1, 0)]));
let scene =
frame_composer.scene_bank_slot(3).expect("scene bank slot 3 should be resident");
@@ -400,7 +444,8 @@ mod tests {
let expected_scene =
banks.scene_bank_slot(3).expect("scene bank slot 3 should be resident");
let mut frame_composer = FrameComposer::new(320, 180, banks);
let mut frame_composer =
FrameComposer::new(320, 180, banks, make_glyph_slot_index(&[(1, 0)]));
assert!(frame_composer.bind_scene(3));
@@ -419,7 +464,8 @@ mod tests {
let banks = Arc::new(MemoryBanks::new());
banks.install_scene_bank(1, Arc::new(make_scene()));
let mut frame_composer = FrameComposer::new(320, 180, banks);
let mut frame_composer =
FrameComposer::new(320, 180, banks, make_glyph_slot_index(&[(1, 0)]));
assert!(frame_composer.bind_scene(1));
frame_composer.unbind_scene();
@@ -433,7 +479,12 @@ mod tests {
#[test]
fn set_camera_stores_top_left_pixel_coordinates() {
let mut frame_composer = FrameComposer::new(320, 180, Arc::new(MemoryBanks::new()));
let mut frame_composer = FrameComposer::new(
320,
180,
Arc::new(MemoryBanks::new()),
make_glyph_slot_index(&[]),
);
frame_composer.set_camera(-12, 48);
@@ -445,7 +496,8 @@ mod tests {
let banks = Arc::new(MemoryBanks::new());
banks.install_scene_bank(0, Arc::new(make_scene()));
let mut frame_composer = FrameComposer::new(320, 180, banks);
let mut frame_composer =
FrameComposer::new(320, 180, banks, make_glyph_slot_index(&[(1, 0)]));
assert!(frame_composer.bind_scene(0));
let cache = frame_composer.cache().expect("cache should exist for bound scene");
@@ -454,7 +506,12 @@ mod tests {
#[test]
fn missing_scene_binding_falls_back_to_no_scene_state() {
let mut frame_composer = FrameComposer::new(320, 180, Arc::new(MemoryBanks::new()));
let mut frame_composer = FrameComposer::new(
320,
180,
Arc::new(MemoryBanks::new()),
make_glyph_slot_index(&[]),
);
assert!(!frame_composer.bind_scene(7));
@@ -463,6 +520,28 @@ mod tests {
assert!(frame_composer.resolver().is_none());
}
#[test]
fn bind_scene_panics_when_scene_dependency_is_not_resident() {
let banks = Arc::new(MemoryBanks::new());
banks.install_scene_bank(0, Arc::new(make_scene()));
let mut frame_composer =
FrameComposer::new(320, 180, banks, make_glyph_slot_index(&[]));
let panic = catch_unwind(AssertUnwindSafe(|| frame_composer.bind_scene(0)))
.expect_err("bind_scene should panic when dependency is missing");
let message = if let Some(message) = panic.downcast_ref::<String>() {
message.clone()
} else if let Some(message) = panic.downcast_ref::<&str>() {
(*message).to_string()
} else {
String::new()
};
assert!(message.contains("SCENE dependency fatal during bind_scene"));
assert!(message.contains("glyph_asset_id=1"));
}
#[test]
fn sprite_controller_begin_frame_resets_sprite_count_and_buckets() {
let mut controller = SpriteController::new();
@@ -582,7 +661,12 @@ mod tests {
#[test]
fn frame_composer_emits_ordered_sprites_for_rendering() {
let mut frame_composer = FrameComposer::new(320, 180, Arc::new(MemoryBanks::new()));
let mut frame_composer = FrameComposer::new(
320,
180,
Arc::new(MemoryBanks::new()),
make_glyph_slot_index(&[]),
);
frame_composer.begin_frame();
assert!(frame_composer.emit_sprite(Sprite {
@@ -621,7 +705,12 @@ mod tests {
banks.install_glyph_bank(1, Arc::new(make_glyph_bank(TileSize::Size8, 3, Color::WHITE)));
let mut frame_composer =
FrameComposer::new(16, 16, Arc::clone(&banks) as Arc<dyn SceneBankPoolAccess>);
FrameComposer::new(
16,
16,
Arc::clone(&banks) as Arc<dyn SceneBankPoolAccess>,
make_glyph_slot_index(&[]),
);
frame_composer.begin_frame();
assert!(frame_composer.emit_sprite(Sprite {
glyph: Glyph { glyph_id: 0, palette_id: 3 },
@@ -652,7 +741,12 @@ mod tests {
banks.install_scene_bank(0, Arc::new(make_scene_with_palette(0, 2, TileSize::Size8)));
let mut frame_composer =
FrameComposer::new(16, 16, Arc::clone(&banks) as Arc<dyn SceneBankPoolAccess>);
FrameComposer::new(
16,
16,
Arc::clone(&banks) as Arc<dyn SceneBankPoolAccess>,
make_glyph_slot_index(&[(0, 0)]),
);
assert!(frame_composer.bind_scene(0));
let mut gfx = Gfx::new(16, 16, Arc::clone(&banks) as Arc<dyn GlyphBankPoolAccess>);
@@ -683,7 +777,12 @@ mod tests {
banks.install_scene_bank(1, Arc::new(make_scene_with_palette(1, 2, TileSize::Size8)));
let mut frame_composer =
FrameComposer::new(16, 16, Arc::clone(&banks) as Arc<dyn SceneBankPoolAccess>);
FrameComposer::new(
16,
16,
Arc::clone(&banks) as Arc<dyn SceneBankPoolAccess>,
make_glyph_slot_index(&[(0, 0), (1, 1)]),
);
let mut gfx = Gfx::new(16, 16, Arc::clone(&banks) as Arc<dyn GlyphBankPoolAccess>);
gfx.scene_fade_level = 31;
gfx.hud_fade_level = 31;
@@ -716,4 +815,36 @@ mod tests {
gfx.present();
assert_eq!(gfx.front_buffer()[0], Color::BLUE.raw());
}
#[test]
fn render_frame_panics_when_dependency_disappears_after_bind() {
let banks = Arc::new(MemoryBanks::new());
banks.install_glyph_bank(0, Arc::new(make_glyph_bank(TileSize::Size8, 1, Color::RED)));
banks.install_scene_bank(0, Arc::new(make_scene_with_palette(1, 1, TileSize::Size8)));
let glyph_slot_index = make_glyph_slot_index(&[(1, 0)]);
let mut frame_composer = FrameComposer::new(
16,
16,
Arc::clone(&banks) as Arc<dyn SceneBankPoolAccess>,
glyph_slot_index.clone(),
);
assert!(frame_composer.bind_scene(0));
glyph_slot_index.rebuild_from_slots(&[None; 16]);
let mut gfx = Gfx::new(16, 16, Arc::clone(&banks) as Arc<dyn GlyphBankPoolAccess>);
let panic = catch_unwind(AssertUnwindSafe(|| frame_composer.render_frame(&mut gfx)))
.expect_err("render_frame should panic when dependency disappears");
let message = if let Some(message) = panic.downcast_ref::<String>() {
message.clone()
} else if let Some(message) = panic.downcast_ref::<&str>() {
(*message).to_string()
} else {
String::new()
};
assert!(message.contains("SCENE dependency fatal during render_frame"));
assert!(message.contains("glyph_asset_id=1"));
}
}