Crate agb_tracker

Expand description

§agb_tracker

agb_tracker is a library for playing tracker music on the Game Boy Advance (GBA) using the agb library.

The default mechanism for playing background music using agb is to include a the entire music as a raw sound file. However, this can get very large (>8MB) for only a few minutes of music, taking up most of your limited ROM space.

Using a tracker, you can store many minutes of music in only a few kB of ROM which makes the format much more space efficient at the cost of some CPU.

This library uses about 20-30% of the GBA’s CPU time per frame, for 4 channels but most of that is agb’s mixing. The main step function uses around 2000 cycles (<1%).

§Example

#![no_std]
#![no_main]

use agb::{Gba, sound::mixer::Frequency};
use agb_tracker::{include_xm, Track, Tracker};

static DB_TOFFE: Track = include_xm!("examples/db_toffe.xm");

#[agb::entry]
fn main(mut gba: Gba) -> ! {
    let vblank_provider = agb::interrupt::VBlank::get();

    let mut mixer = gba.mixer.mixer(Frequency::Hz32768);
    mixer.enable();

    let mut tracker = Tracker::new(&DB_TOFFE);

    loop {
        tracker.step(&mut mixer);
        mixer.frame();

        vblank_provider.wait_for_vblank();
    }
}

Note that currently you have to select 32768Hz as the frequency for the mixer. This restriction will be lifted in a future version.

§Concepts

The main concept of the agb_tracker crate is to move as much of the work to build time as possible to make the actual playing as fast as we can. The passed tracker file gets parsed and converted into a simplified format which is then played while the game is running.

In theory, the format the tracker file gets converted into is agnostic to the base format. Currently, only XM is implemented, however, more formats could be added in future depending on demand.

Macros§

include_midi
Import a midi file. Only available if you have the midi feature enabled (enabled by default). This is currently experimental, and many types of MIDI file or MIDI features are not supported.
include_xm
Import an XM file. Only available if you have the xm feature enabled (enabled by default).

Structs§