Crate gme

Game Music Emu Rust

This crate contains Rust bindings for Game Music Emu. It is pretty barebones at the moment and does not cover everything, but eventually it will have bindings for most of the functions in gme.h.

Conditional Compilation

Just like the regular version of Game Music Emu, you can choose which emulators are included by adding features to your Cargo.toml.

For example, if you only want to use Nintendo and Game Boy emulators, you’d write:

gme = { version = 0.1, default-features = false, features = ["gbs", "nsf"]

See Cargo.toml for all available features. The build logic is in build.rs. You can call gme::type_list() at runtime for a list of emulators you compiled with.

Usage Through Native Functions

Functions from gme.h are exposed at the root level, and can be viewed in native.rs. Most of them require an EmuHandle, which holds the pointer to a MusicEmu instance in the C++ code.

You can get an EmuHandle simply like this:

let handle = gme::new_emu(gme::EmuType::Nsf, 44100);

You can also get a handle by loading a file. This is a convenience function that will create an instance with the file data already loaded.

let handle = gme::open_file("test.nsf", 44100).ok().unwrap();

Once you have the handle, you can access any of the functions with it:

let track_count = gme::track_count(&handle);
gme::start_track(&handle, 0);

EmuHandles are reference counted and the MusicEmu instance they reference is automatically freed when they are dropped.

Usage Through Wrapper

Instead of using native functions, you can use the GameMusicEmu struct, which provides a wrapper around the functions that take an EmuHandle. You can use it like this:

use gme::{EmuType, GameMusicEmu};

let emu = GameMusicEmu::new(EmuType::Nsf, 44100);
emu.load_file("test.nsf");
emu.start_track(0);

The GameMusicEmu struct will eventually be extended to be more than just a wrapper.

Structs

EmuHandle

Holds a pointer to a MusicEmu instance in the C++ code. It automatically frees the instance when dropped.

GameMusicEmu

Provides a wrapper around native functions that take an EmuHandle

Enums

EmuType

All supported emulator types

Functions

identify_header

Determine likely EmuType based on first four bytes of file.

load_data

Load music file from memory into emulator. Makes a copy of data passed.

new_emu

Creates an EmuHandle with the specified EmuType

open_data

Creates a new EmuHandle and loads it with data. Makes a copy of the data.

play

Generate count 16-bit signed samples into buffer. Output is in stereo.

start_track

Start a track, where 0 is the first track

track_count

Number of tracks available

type_list

Returns all of the supported EmuTypes. This is based on the features the crate is compiled with.