Struct agb::display::tiled::InfiniteScrolledMap

pub struct InfiniteScrolledMap<'a> { /* private fields */ }

The infinite scrolled map allows you to create a game space larger than a single GBA background. The abstraction allows only for static tiles, but it is possible to animate the tiles if needed.

When you create a new infinite scrolled map, you need to provide a background which it will render itself onto and a function which takes a Vector2D<i32> position and returns which tile should be rendered there.

The passed function should handle being out of bounds, as the scrolled map does buffer around the edges slightly.

Note that nothing is copied to video memory until you call .commit(), and you must call .clear() before dropping the infinite scrolled map or you will leak video RAM.

Example

extern crate alloc;

use alloc::boxed::Box;

use agb::display::tiled::{
    InfiniteScrolledMap,
    TileSetting,
    RegularBackgroundSize,
    TileSet,
    TileFormat,
};
use agb::display::Priority;

mod tilemap {
   pub const BACKGROUND_MAP: &[usize] = &[ // Probably load this from a file
   pub const WIDTH: i32 = // set it to some width
}

agb::include_background_gfx!(water_tiles, tiles => "examples/water_tiles.png");

let (gfx, mut vram) = gba.display.video.tiled0();

let tile_data = water_tiles::tiles;

let mut backdrop = InfiniteScrolledMap::new(
    gfx.background(Priority::P2, RegularBackgroundSize::Background32x32, TileFormat::FourBpp),
    Box::new(|pos| {
        (
            &tile_data.tiles,
            tile_data.tile_settings[*tilemap::BACKGROUND_MAP
                    .get((pos.x + tilemap::WIDTH * pos.y) as usize)
                    .unwrap_or(&0)]
        )
    }),
);

// ...

backdrop.set_pos(&mut vram, (3, 5).into());
backdrop.commit(&mut vram);
backdrop.show();

Implementations

impl<'a> InfiniteScrolledMap<'a>

pub fn new( map: MapLoan<'a, RegularMap>, tile: Box<dyn Fn(Vector2D<i32>) -> (&'a TileSet<'a>, TileSetting) + 'a> ) -> Self

Creates a new infinite scrolled map wrapping the provided background using the given function to position tiles.

This will not actually render anything until either .init() or .init_partial() is called to set up VRam and this is then committed.

pub fn init( &mut self, vram: &mut VRamManager, pos: Vector2D<i32>, between_updates: &mut impl FnMut() )

Initialises the map and fills it, calling the between_updates occasionally to allow you to ensure that music keeps playing without interruption.

Example

let start_position = agb::fixnum::Vector2D::new(10, 10);
backdrop.init(&mut vram, start_position, &mut || {
    vblank.wait_for_vblank();
    mixer.frame();
});

pub fn init_partial( &mut self, vram: &mut VRamManager, pos: Vector2D<i32> ) -> PartialUpdateStatus

Does a partial initialisation of the background, rendering 2 rows. This is because initialisation can take quite a while, so you will need to call this method a few times to ensure that you update the entire frame.

Returns PartialUpdateStatus::Done if complete, and PartialUpdateStatus::Continue if you need to call this a few more times to fully update the screen.

It is recommended you use .init() instead of this method

Example

let start_position = agb::fixnum::Vector2D::new(10, 10);
while backdrop.init_partial(&mut vram, start_position) == PartialUpdateStatus::Continue {
    vblank.wait_for_vblank();
    mixer.frame();
}

pub fn set_pos( &mut self, vram: &mut VRamManager, new_pos: Vector2D<i32> ) -> PartialUpdateStatus

Set the top left corner of the map. You may need to call this method multiple times if PartialUpdateStatus::Continue is returned.

pub fn show(&mut self)

Makes the map visible

pub fn hide(&mut self)

Hides the map

pub fn commit(&mut self, vram: &mut VRamManager)

Copies data to vram. Needs to be called during vblank if possible

pub fn clear(&mut self, vram: &mut VRamManager)

Clears the underlying map. You must call this before the scrolled map goes out of scope or you will leak VRam.

pub const fn background(&self) -> BackgroundID