image-gameboy

A simple Rust crate for converting images into the Game Boy's 2 bits-per-pixel (2bpp) tile format. Built to work seamlessly with the image crate.

Features

🧩 Provides the into_gb2bpp() extension method on DynamicImage
🎮 Outputs binary tile data in the Game Boy-compatible 2bpp format
🖼️ Supports grayscale images with dimensions divisible by 8
🔗 Easy to integrate in asset pipelines for Game Boy homebrew or ROM hacking

Usage

Add to your `Cargo.toml`

[dependencies]
image = "0.25"
image-gameboy = "0.1"

Example

use image::io::Reader as ImageReader;
use image_gameboy::GameBoy2bpp;

fn main() {
    let img = ImageReader::open("assets/sprite.png")
        .unwrap()
        .decode()
        .unwrap();

    let gb_data = img.into_gb2bpp();

    std::fs::write("sprite.2bpp", gb_data).unwrap();
}

What is Game Boy 2bpp?

The original Game Boy used a tile-based graphics system where each 8×8 tile is represented by 16 bytes:

2 bytes per row (8 rows total)
Each pixel uses 2 bits (4 grayscale levels)
The bits are split across two “bitplanes” (least and most significant bits)

This crate generates exactly that format from any grayscale image.

Notes

Input images must be grayscale and have dimensions divisible by 8
Each pixel is quantized to one of 4 grayscale levels:
- 0..=63 → 3 (darkest)
- 64..=127 → 2
- 128..=191 → 1
- 192..=255 → 0 (lightest)

License

Licensed under the MIT License or Apache 2.0.

image-gameboy 0.1.0