Macro agb::include_gfx

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

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

The macro expects to be linked to a toml file which contains a metadata about the image and a link to the png or bmp itself. See the examples below for a full definition of the format.

The manifest file format

The following is an example of the toml file you would need to create. Generally you will find this in the gfx folder in the same level as the src folder (see the examples).

Suppose that the following is in examples/water_tiles.toml.

version = "1.0"

[image.tiles]
filename = "water_tiles.png"
tile_size = "8x8"

You then import this using:

#![no_std]
#![no_main]
agb::include_gfx!("examples/water_tiles.toml");

This will generate something along the lines of the following:

// module name comes from the name of the toml file, so `water_tiles` in this case because it is
// called `water_tiles.toml`
mod water_tiles {
    const tiles = /* ... */;
}

And tiles will be an instance of TileData

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_gfx,
};

agb::include_gfx!("examples/water_tiles.toml");

let tileset = TileSet::new(water_tiles::water_tiles.tiles, TileFormat::FourBpp);

vram.set_background_palettes(water_tiles::PALETTES);

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

for y in 0..20u16 {
    for x in 0..30u16 {
        bg.set_tile(
            &mut vram,
            (x, y).into(),
            &tileset,
            TileSetting::new(0, false, false, 0),
        );
    }
}
bg.commit(&mut vram);
bg.show();