# Game Music Emu Rust
[![Game Music Emu Crate](https://img.shields.io/crates/v/gme.svg)](https://crates.io/crates/gme)
[![Game Music Emu Documentation](https://docs.rs/gme/badge.svg)](https://docs.rs/gme)

This crate contains Rust bindings for [Game Music Emu](https://bitbucket.org/mpyne/game-music-emu/wiki/Home). 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](./src/gme/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](Cargo.toml) for all available features. The build logic is in [build.rs](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](./src/gme/gme.h) are exposed at the root level, and can be viewed in [native.rs](src/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:
```rust
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.

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

```

Once you have the handle, you can access any of the functions with it:
```rust
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:
```rust
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

* **[Jay Pavlina](https://github.com/JayPavlina)** - *Initial work*

See also the list of [contributors](https://github.com/your/project/contributors) who participated in this project.

## License

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

Game Music Emu is licensed under LGPLv2.1. See its [license](src/gme/license.txt) for details.

## Acknowledgments

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