Bitmap Font for GBA/AGB

Renderer for bitmap fonts on the GBA using the agb framework

Font converter

Use the AGB Font Converter to convert images to fonts

Usage

In Cargo.toml gba_agb_font_renderer = "0.3.0"

Loading a font

Two font types are available: FullFont (all 256 code points) and PrintableFont (95 printable ASCII chars, 0x20–0x7E). Load them at compile time with the corresponding macro:

use gba_agb_font_renderer::prelude::*;

// Full 256-char font from ROM (default)
let font = full_font!(include_bytes!("my_font.bin"));

// Printable ASCII font, placed in IWRAM for faster blitting
// (~8× fewer waitstates per pixel row — only worthwhile for printable fonts ~3 KB)
let font = printable_font!(include_bytes!("my_font.bin"), iwram);

// Full 256-char font placed in EWRAM
let font = full_font!(include_bytes!("my_font.bin"), ewram);

Rendering text

wrap_at is a maximum line width in pixels (relative to pos). Pass None to disable wrapping.

use gba_agb_font_renderer::prelude::*;
use agb::fixnum::vec2;

let mut renderer = TextRenderer::default();
renderer.draw_text(b"Hello, world!", &font, &mut bg, vec2(8, 16), Some(200), 0);

Typewriter effect

TypewriterRenderer reveals text one chunk at a time. Call update() once per frame and draw() to blit newly revealed characters.

use gba_agb_font_renderer::prelude::*;
use agb::fixnum::vec2;

// 1 character revealed every 2 frames, wrap at 200px
let mut tw = TypewriterRenderer::new(1, 2, Some(200));
tw.load_text(b"Hello, world!", vec2(8, 16));

loop {
    tw.update();
    tw.draw(&font, &mut bg, 0);
    if tw.is_complete() { break; }
    vblank.wait_for_vblank();
}

To clear the text area before loading new text:

tw.clear(&font, &mut bg, 0);
tw.load_text(b"New message", vec2(8, 16));

Font binary format

Two modes are supported, selected by the mode byte at offset 0.

Common header

Mode 0 — printable ASCII (95 glyphs)

Mode 1 — all-256 (256 glyphs)

Pixel data

Stored as u32 values, each holding 8 pixels at 4 bits per pixel (4bpp). Each glyph row occupies (glyph_width + 7) / 8 u32s. Palette index 0 is transparent.