Macro include_background_gfx

include_background_gfx!() { /* proc-macro */ }

This macro is used to convert a png, bmp or aseprite file into a format usable by the Game Boy Advance.

Suppose you have a file in examples/water_tiles.png which contains some tiles you’d like to use.

You import them using:

#![no_std]
#![no_main]
agb::include_background_gfx!(water_tiles, tiles => "examples/water_tiles.png");

This will generate something along the lines of the following:

// module name comes from the first argument, name of the constant from the arrow
mod water_tiles {
    pub static tiles = /* ... */;
}

And tiles will be an instance of TileData

You can import multiple files at once, and the palette data will be combined so they can all be visible.

Examples

Assume the tiles are loaded as above

In src/main.rs:

#![no_std]
#![no_main]
use agb::{
    display::{
        tiled::{RegularBackgroundSize, TileFormat, TileSet, TileSetting, Tiled0, TiledMap, VRamManager},
        Priority,
    },
    include_background_gfx,
};

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

let tileset = &water_tiles::tiles.tiles;

vram.set_background_palettes(water_tiles::PALETTES);

let mut bg = gfx.background(Priority::P0, RegularBackgroundSize::Background32x32, tileset.format());

for y in 0..20u16 {
    for x in 0..30u16 {
        bg.set_tile(
            &mut vram,
            (x, y),
            tileset,
            water_tiles::tiles.tile_settings[0],
        );
    }
}
bg.commit(&mut vram);
bg.set_visible(true);

Including from the out directory is supported through the $OUT_DIR token.

include_background_gfx!(generated_background, "000000", DATA => "$OUT_DIR/generated_background.aseprite");

You can also make the exported background a public module which will allow other modules access them. The following will declare water_tiles as a pub mod rather than a mod.

#![no_std]
#![no_main]
agb::include_background_gfx!(pub water_tiles, tiles => "examples/water_tiles.png");

Including from the out directory is supported through the $OUT_DIR token.

include_background_gfx!(generated_background, "000000", DATA => "$OUT_DIR/generated_background.aseprite");