gme 0.1.1

Rust bindings for Game Music Emu
Documentation

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.

Getting Started

Add the following to your Cargo.toml.

gme = "0.1"

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.

Authors

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Game Music Emu is licensed under LGPLv2.1. See its license for details.

Acknowledgments

  • Shay Green for creating Game Music Emu
  • Michael Pyne for maintaining Game Music Emu