Add priority set / get and set_visible / is_visible to maps (#563)

Adds `.priority()`, `.set_priority()` and `.is_visible()` and replace
`show` and `hide` with `.set_visible()` in `RegularMap`, `AffineMap` and
`InfiniteScrolledMap`.

- [x] Changelog updated / no changelog update needed

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Added `.priority()`, `.set_priority()` and `.is_visible()` to `RegularMap`, `AffineMap` and `InfiniteScrolledMap`.
+- Replaced `.show()` and `.hide()` with `.set_visible()`in `RegularMap`, `AffineMap` and `InfiniteScrolledMap`.
+
 ## [0.18.1] - 2024/02/06
 
 ### Added

agb/examples/affine_background.rs

@@ -31,7 +31,7 @@ fn main(mut gba: agb::Gba) -> ! {
     }
 
     bg.commit(&mut vram);
-    bg.show();
+    bg.set_visible(true);
 
     let mut rotation = num!(0.);
     let rotation_increase: Num<i32, 16> = num!(0.01);

agb/examples/animated_background.rs

@@ -38,7 +38,7 @@ fn main(mut gba: agb::Gba) -> ! {
     }
 
     bg.commit(&mut vram);
-    bg.show();
+    bg.set_visible(true);
 
     let mut i = 0;
     loop {

agb/examples/chicken.rs

@@ -71,7 +71,7 @@ fn main(mut gba: agb::Gba) -> ! {
         );
     }
 
-    background.show();
+    background.set_visible(true);
     background.commit(&mut vram);
 
     let object = gba.display.object.get_managed();

agb/examples/dynamic_tiles.rs

@@ -50,7 +50,7 @@ fn main(mut gba: agb::Gba) -> ! {
     }
 
     bg.commit(&mut vram);
-    bg.show();
+    bg.set_visible(true);
 
     loop {
         vblank.wait_for_vblank();

agb/examples/mixer_32768.rs

@@ -39,7 +39,7 @@ fn main(mut gba: Gba) -> ! {
     writer.commit();
 
     bg.commit(&mut vram);
-    bg.show();
+    bg.set_visible(true);
 
     let timer_controller = gba.timers.timers();
     let mut timer = timer_controller.timer2;

agb/examples/stereo_sound.rs

@@ -39,7 +39,7 @@ fn main(mut gba: Gba) -> ! {
     writer.commit();
 
     bg.commit(&mut vram);
-    bg.show();
+    bg.set_visible(true);
 
     let timer_controller = gba.timers.timers();
     let mut timer = timer_controller.timer2;

agb/examples/text_render.rs

@@ -53,7 +53,7 @@ fn main(mut gba: agb::Gba) -> ! {
     writer.commit();
 
     bg.commit(&mut vram);
-    bg.show();
+    bg.set_visible(true);
 
     let mut frame = 0;
 

agb/src/display/example_logo.rs

@@ -8,7 +8,7 @@ pub fn display_logo(map: &mut RegularMap, vram: &mut VRamManager) {
     map.fill_with(vram, &agb_logo::test_logo);
 
     map.commit(vram);
-    map.show();
+    map.set_visible(true);
 }
 
 #[cfg(test)]

agb/src/display/font.rs

@@ -314,14 +314,14 @@ mod tests {
             writeln!(&mut writer, "World!").unwrap();
             writer.commit();
             bg.commit(&mut vram);
-            bg.show();
+            bg.set_visible(true);
 
             // Test writing with same renderer after showing background
             let mut writer = renderer.writer(1, 2, &mut bg, &mut vram);
             writeln!(&mut writer, "This is a font rendering example").unwrap();
             writer.commit();
             bg.commit(&mut vram);
-            bg.show();
+            bg.set_visible(true);
 
             crate::test_runner::assert_image_output("examples/font/font-test-output.png");
             renderer.clear(&mut vram);

agb/src/display/tiled/infinite_scrolled_map.rs

@@ -6,7 +6,7 @@ use super::{
 };
 
 use crate::{
-    display,
+    display::{self, Priority},
     fixnum::{Rect, Vector2D},
 };
 
@@ -69,7 +69,7 @@ use crate::{
 ///
 /// backdrop.set_pos(&mut vram, (3, 5).into());
 /// backdrop.commit(&mut vram);
-/// backdrop.show();
+/// backdrop.set_visible(true);
 /// # }
 /// ```
 pub struct InfiniteScrolledMap<'a> {
@@ -389,14 +389,32 @@ impl<'a> InfiniteScrolledMap<'a> {
         PartialUpdateStatus::Done
     }
 
-    /// Makes the map visible
-    pub fn show(&mut self) {
-        self.map.show();
+    /// Sets wether the map is visible  
+    /// Use [is_visible](Self::is_visible) to get the value
+    pub fn set_visible(&mut self, visible: bool) {
+        self.map.set_visible(visible);
     }
 
-    /// Hides the map
-    pub fn hide(&mut self) {
-        self.map.hide();
+    /// Checks whether the map is not marked as hidden  
+    /// Use [set_visible](Self::set_visible) to set the value
+    #[must_use]
+    pub fn is_visible(&self) -> bool {
+        self.map.is_visible()
+    }
+
+    /// Sets the map priority  
+    /// This require to call [commit](Self::commit) in order to apply the value  
+    /// Use [priority](Self::priority) to get the value
+    pub fn set_priority(&mut self, priority: Priority) {
+        self.map.set_priority(priority);
+    }
+
+    /// Returns the latest map priority set  
+    /// This will only be the currently applied priority if you called [commit](Self::commit) before calling this function  
+    /// Use [set_priority](Self::set_priority) to set the value
+    #[must_use]
+    pub fn priority(&self) -> Priority {
+        self.map.priority()
     }
 
     /// Copies data to vram. Needs to be called during vblank if possible

agb/src/display/tiled/map.rs

@@ -47,8 +47,8 @@ trait TiledMapPrivate: TiledMapTypes {
 /// it is 'sealed' so you cannot implement this yourself.
 pub trait TiledMap: TiledMapTypes {
     fn clear(&mut self, vram: &mut VRamManager);
-    fn show(&mut self);
-    fn hide(&mut self);
+    fn set_visible(&mut self, visible: bool);
+    fn is_visible(&self) -> bool;
     fn commit(&mut self, vram: &mut VRamManager);
     fn size(&self) -> Self::Size;
 }
@@ -70,16 +70,22 @@ where
         }
     }
 
-    fn show(&mut self) {
+    /// Sets wether the map is visible  
+    /// Use [is_visible](TiledMap::is_visible) to get the value
+    fn set_visible(&mut self, visible: bool) {
         let mode = DISPLAY_CONTROL.get();
-        let new_mode = mode | (1 << (self.background_id() + 0x08)) as u16;
+        let new_mode = if visible {
+            mode | (1 << (self.background_id() + 0x08)) as u16
+        } else {
+            mode & !(1 << (self.background_id() + 0x08)) as u16
+        };
         DISPLAY_CONTROL.set(new_mode);
     }
 
-    fn hide(&mut self) {
-        let mode = DISPLAY_CONTROL.get();
-        let new_mode = mode & !(1 << (self.background_id() + 0x08)) as u16;
-        DISPLAY_CONTROL.set(new_mode);
+    /// Checks whether the map is not marked as hidden  
+    /// Use [set_visible](TiledMap::set_visible) to set the value
+    fn is_visible(&self) -> bool {
+        DISPLAY_CONTROL.get() & (1 << (self.background_id() + 0x08)) > 0
     }
 
     fn commit(&mut self, vram: &mut VRamManager) {
@@ -266,6 +272,21 @@ impl RegularMap {
         *self.tiles_dirty() = true;
     }
 
+    /// Returns the latest map priority set  
+    /// This will only be the currently applied priority if you called [commit](TiledMap::commit) before calling this function  
+    /// Use [set_priority](Self::set_priority) to set the value
+    #[must_use]
+    pub fn priority(&self) -> Priority {
+        self.priority
+    }
+
+    /// Sets the map priority  
+    /// This require to call [commit](TiledMap::commit) in order to apply the value  
+    /// Use [priority](Self::priority) to get the value
+    pub fn set_priority(&mut self, priority: Priority) {
+        self.priority = priority;
+    }
+
     #[must_use]
     pub fn scroll_pos(&self) -> Vector2D<i16> {
         self.scroll
@@ -386,6 +407,17 @@ impl AffineMap {
         self.transform = transformation.into();
     }
 
+    // Gets the map priority
+    #[must_use]
+    pub fn priority(&self) -> Priority {
+        self.priority
+    }
+
+    /// Sets the map priority
+    pub fn set_priority(&mut self, priority: Priority) {
+        self.priority = priority;
+    }
+
     fn bg_affine_matrix(&self) -> MemoryMapped<AffineMatrixBackground> {
         unsafe { MemoryMapped::new(0x0400_0000 + 0x10 * self.background_id()) }
     }

agb/src/lib.rs

@@ -94,7 +94,7 @@
 ///     }
 /// }
 /// bg.commit(&mut vram);
-/// bg.show();
+/// bg.set_visible(true);
 /// # }
 /// ```
 ///

examples/combo/src/lib.rs

@@ -78,7 +78,7 @@ fn get_game(gba: &mut agb::Gba) -> Game {
 
     bg.set_pos(&mut vram, (0, 0).into());
     bg.commit(&mut vram);
-    bg.show();
+    bg.set_visible(true);
 
     let mut position: Vector2D<Num<i32, 8>> = (0, 0).into();
     let mut game_idx = 0;
@@ -109,7 +109,7 @@ fn get_game(gba: &mut agb::Gba) -> Game {
         }
     };
 
-    bg.hide();
+    bg.set_visible(false);
     bg.clear(&mut vram);
     bg.commit(&mut vram);
 

examples/hyperspace-roll/src/background.rs

@@ -85,12 +85,12 @@ pub fn show_title_screen(background: &mut RegularMap, vram: &mut VRamManager, sf
     background.set_scroll_pos((0i16, 0).into());
     vram.set_background_palettes(backgrounds::PALETTES);
 
-    background.hide();
+    background.set_visible(false);
 
     background.fill_with(vram, &backgrounds::title);
     background.commit(vram);
     sfx.frame();
-    background.show();
+    background.set_visible(true);
 }
 
 pub struct StarBackground<'a> {
@@ -141,13 +141,8 @@ impl<'a> StarBackground<'a> {
         self.background2.commit(vram);
     }
 
-    pub fn hide(&mut self) {
-        self.background1.hide();
-        self.background2.hide();
-    }
-
-    pub fn show(&mut self) {
-        self.background1.show();
-        self.background2.show();
+    pub fn set_visible(&mut self, visible: bool) {
+        self.background1.set_visible(visible);
+        self.background2.set_visible(visible);
     }
 }

examples/hyperspace-roll/src/battle.rs

@@ -592,11 +592,11 @@ pub(crate) fn battle_screen(
         agb.sfx.frame();
         agb.vblank.wait_for_vblank();
         help_background.commit(&mut agb.vram);
-        help_background.show();
+        help_background.set_visible(true);
 
         if current_battle_state.enemy.health == 0 {
             agb.sfx.ship_explode();
-            help_background.hide();
+            help_background.set_visible(false);
             crate::background::load_help_text(&mut agb.vram, help_background, 3, (0, 0));
             crate::background::load_help_text(&mut agb.vram, help_background, 3, (0, 1));
             return BattleResult::Win;
@@ -604,7 +604,7 @@ pub(crate) fn battle_screen(
 
         if current_battle_state.player.health == 0 {
             agb.sfx.ship_explode();
-            help_background.hide();
+            help_background.set_visible(false);
             crate::background::load_help_text(&mut agb.vram, help_background, 3, (0, 0));
             crate::background::load_help_text(&mut agb.vram, help_background, 3, (0, 1));
             return BattleResult::Loss;

examples/hyperspace-roll/src/customise.rs

@@ -292,9 +292,9 @@ pub(crate) fn customise_screen(
                             &mut agb.vram,
                         );
                     }
-                    descriptions_map.show();
+                    descriptions_map.set_visible(true);
                 } else {
-                    descriptions_map.hide();
+                    descriptions_map.set_visible(false);
                 }
 
                 let (x, y) = upgrade_position(cursor.upgrade);
@@ -307,7 +307,7 @@ pub(crate) fn customise_screen(
                 } else if input.is_just_pressed(Button::A)
                     && player_dice.dice[cursor.dice].faces[cursor.face] != upgrades[cursor.upgrade]
                 {
-                    descriptions_map.hide();
+                    descriptions_map.set_visible(false);
 
                     modified.push(Cursor {
                         dice: cursor.dice,
@@ -347,12 +347,12 @@ pub(crate) fn customise_screen(
         agb.obj.commit();
         descriptions_map.commit(&mut agb.vram);
         help_background.commit(&mut agb.vram);
-        help_background.show();
+        help_background.set_visible(true);
         agb.star_background.commit(&mut agb.vram);
     }
 
-    descriptions_map.hide();
-    help_background.hide();
+    descriptions_map.set_visible(false);
+    help_background.set_visible(false);
     crate::background::load_help_text(&mut agb.vram, help_background, 3, (0, 0));
     crate::background::load_help_text(&mut agb.vram, help_background, 3, (0, 1));
     descriptions_map.clear(&mut agb.vram);

examples/hyperspace-roll/src/lib.rs

@@ -171,7 +171,7 @@ pub fn main(mut gba: agb::Gba) -> ! {
             let mut score_display = NumberDisplay::new((216, 9).into());
             score_display.set_value(Some(save::load_high_score()), &agb.obj);
             agb.obj.commit();
-            agb.star_background.hide();
+            agb.star_background.set_visible(false);
 
             let mut input = agb::input::ButtonController::new();
             loop {
@@ -187,13 +187,13 @@ pub fn main(mut gba: agb::Gba) -> ! {
 
         agb.obj.commit();
 
-        help_background.hide();
+        help_background.set_visible(false);
         help_background.clear(&mut agb.vram);
         help_background.commit(&mut agb.vram);
         agb.sfx.frame();
 
         background::load_palettes(&mut agb.vram);
-        agb.star_background.show();
+        agb.star_background.set_visible(true);
 
         loop {
             dice = customise::customise_screen(

examples/the-dungeon-puzzlers-lament/src/game.rs

@@ -102,7 +102,7 @@ struct Construction<'a, 'b> {
 
 impl<'a, 'b> Drop for Construction<'a, 'b> {
     fn drop(&mut self) {
-        self.background.hide();
+        self.background.set_visible(false);
     }
 }
 
@@ -115,7 +115,7 @@ impl<'a, 'b> Construction<'a, 'b> {
         let game = GameState::new(level);
         game.load_level_background(background, vram_manager);
         background.commit(vram_manager);
-        background.show();
+        background.set_visible(true);
         Self { background, game }
     }
 
@@ -237,18 +237,10 @@ impl<'a, 'b> Game<'a, 'b> {
         self.phase.render(loader, oam)
     }
 
-    pub fn hide_background(&mut self) {
+    pub fn set_background_visibility(&mut self, visible: bool) {
         match &mut self.phase {
-            GamePhase::Construction(construction) => construction.background.hide(),
-            GamePhase::Execute(execute) => execute.construction.background.hide(),
-            _ => {}
-        }
-    }
-
-    pub fn show_background(&mut self) {
-        match &mut self.phase {
-            GamePhase::Construction(construction) => construction.background.show(),
-            GamePhase::Execute(execute) => execute.construction.background.show(),
+            GamePhase::Construction(construction) => construction.background.set_visible(visible),
+            GamePhase::Execute(execute) => execute.construction.background.set_visible(visible),
             _ => {}
         }
     }
@@ -408,8 +400,8 @@ impl<'a, 'b> Pausable<'a, 'b> {
         {
             self.paused = self.paused.change();
             match self.paused {
-                Paused::Paused => self.game.hide_background(),
-                Paused::Playing => self.game.show_background(),
+                Paused::Paused => self.game.set_background_visibility(false),
+                Paused::Playing => self.game.set_background_visibility(true),
             }
         }
 

examples/the-dungeon-puzzlers-lament/src/lib.rs

@@ -98,7 +98,7 @@ pub fn entry(mut gba: agb::Gba) -> ! {
     backgrounds::load_ui(&mut ui_bg, &mut vram);
 
     ui_bg.commit(&mut vram);
-    ui_bg.show();
+    ui_bg.set_visible(true);
 
     let (unmanaged, sprite_loader) = gba.display.object.get_unmanaged();
 
@@ -126,9 +126,9 @@ pub fn entry(mut gba: agb::Gba) -> ! {
     loop {
         if current_level >= level::Level::num_levels() {
             current_level = 0;
-            ui_bg.hide();
-            level_bg.hide();
-            ending_bg.show();
+            ui_bg.set_visible(false);
+            level_bg.set_visible(false);
+            ending_bg.set_visible(true);
             loop {
                 if g.frame(
                     &mut (),
@@ -138,8 +138,8 @@ pub fn entry(mut gba: agb::Gba) -> ! {
                     break;
                 }
             }
-            ui_bg.show();
-            ending_bg.hide();
+            ui_bg.set_visible(true);
+            ending_bg.set_visible(false);
         } else {
             if current_level > maximum_level {
                 maximum_level = current_level;

examples/the-hat-chooses-the-wizard/src/lib.rs

@@ -656,14 +656,9 @@ impl<'a, 'b> PlayingLevel<'a, 'b> {
         }
     }
 
-    fn show_backgrounds(&mut self) {
-        self.background.background.show();
-        self.background.foreground.show();
-    }
-
-    fn hide_backgrounds(&mut self) {
-        self.background.background.hide();
-        self.background.foreground.hide();
+    fn set_backgrounds_visibility(&mut self, visible: bool) {
+        self.background.background.set_visible(visible);
+        self.background.foreground.set_visible(visible);
     }
 
     fn clear_backgrounds(&mut self, vram: &mut VRamManager) {
@@ -812,7 +807,7 @@ pub fn main(mut agb: agb::Gba) -> ! {
     let mut sfx = sfx::SfxPlayer::new(&mut mixer);
 
     world_display.commit(&mut vram);
-    world_display.show();
+    world_display.set_visible(true);
 
     splash_screen::show_splash_screen(
         splash_screen::SplashScreen::Start,
@@ -823,7 +818,7 @@ pub fn main(mut agb: agb::Gba) -> ! {
 
     loop {
         world_display.commit(&mut vram);
-        world_display.show();
+        world_display.set_visible(true);
 
         vram.set_background_palettes(tile_sheet::PALETTES);
 
@@ -850,7 +845,7 @@ pub fn main(mut agb: agb::Gba) -> ! {
             );
 
             world_display.commit(&mut vram);
-            world_display.show();
+            world_display.set_visible(true);
 
             sfx.frame();
             vblank.wait_for_vblank();
@@ -918,9 +913,9 @@ pub fn main(mut agb: agb::Gba) -> ! {
 
             object.commit();
 
-            level.show_backgrounds();
+            level.set_backgrounds_visibility(true);
 
-            world_display.hide();
+            world_display.set_visible(false);
 
             loop {
                 match level.update_frame(&mut sfx, &mut vram, &object) {
@@ -945,7 +940,7 @@ pub fn main(mut agb: agb::Gba) -> ! {
                 object.commit();
             }
 
-            level.hide_backgrounds();
+            level.set_backgrounds_visibility(false);
             level.clear_backgrounds(&mut vram);
         }
 

examples/the-hat-chooses-the-wizard/src/splash_screen.rs

@@ -34,7 +34,7 @@ pub fn show_splash_screen(
 
     map.commit(vram);
     vram.set_background_palettes(splash_screens::PALETTES);
-    map.show();
+    map.set_visible(true);
 
     loop {
         input.update();
@@ -51,6 +51,6 @@ pub fn show_splash_screen(
         vblank.wait_for_vblank();
     }
 
-    map.hide();
+    map.set_visible(false);
     map.clear(vram);
 }

examples/the-purple-night/src/lib.rs

@@ -92,9 +92,9 @@ impl<'a> Level<'a> {
         foreground.commit(vram);
         clouds.commit(vram);
 
-        backdrop.show();
-        foreground.show();
-        clouds.show();
+        backdrop.set_visible(true);
+        foreground.set_visible(true);
+        clouds.set_visible(true);
 
         let slime_spawns = tilemap::SLIME_SPAWNS_X
             .iter()