# libfmod

[![Crates.io Version](https://img.shields.io/crates/v/libfmod.svg)](https://crates.io/crates/libfmod)
[![LICENSE](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![MSRV](https://img.shields.io/badge/rustc-1.77.0+-ab6000.svg)](https://blog.rust-lang.org/2024/03/21/Rust-1.77.0.html)

A Rust bindings for [FMOD Engine](https://fmod.com/).
FFI wrapped in Rust code to make them safe, more idiomatic
and abstract away uncomfortable manual C interface using.

### Installation

```toml
[dependencies]
libfmod = "~2.222"
```

Choose one of FMOD supported versions:

| libfmod | FMOD    | Status | End of life |
|---------|---------|--------|-------------|
| 2.222   | 2.02.22 | active |             | 
| 2.206   | 2.02.06 | frozen | 2024-09-03  |

Active: new features, bugfixes, and security fixes are accepted, new crates are still released.

Frozen: no further changes can be pushed to it.

#### FMOD Development Libraries

FMOD development libraries can't be integrated and distributed as part of this crate.
You should download and install it considering your platform from:
https://www.fmod.com/download

**Windows (MSVC)**

You should manually provide FMOD development libraries for MSVC linker.
Copy following files from default FMOD Engine installation folder
`C:\Program Files (x86)\FMOD SoundSystem\FMOD Studio API Windows\`:

```bash
.\api\core\lib\x64\fmod.dll
.\api\core\lib\x64\fmod_vc.lib
.\api\studio\lib\x64\fmodstudio.dll
.\api\studio\lib\x64\fmodstudio_vc.lib
```

To one of the folders where Rust can find these libraries:

```bash
.\target\debug\deps\
%USERPROFILE%\.rustup\toolchains\stable-x86_64-pc-windows-msvc\lib\rustlib\x86_64-pc-windows-msvc\lib
```

⚠️ When you're shipping your application make sure to copy FMOD *.dll to the same directory that your *.exe is in.

**Linux / macOS**

Before you can use libfmod, FMOD libraries must be installed on your computer.
The standard locations for dynamic libraries on unix are `/usr/local/lib` and `/usr/lib`.

You may also place the files in a non-standard location in your file system, but you must create symbolic links to that
location this way:

```bash
ln -s ~/FMOD/api/core/lib/libfmod.dylib /usr/local/lib/libfmod.dylib
ln -s ~/FMOD/api/studio/lib/libfmodstudio.dylib /usr/local/lib/libfmodstudio.dylib
```

You may also place the files in location in which Rust searches for dynamic libraries by default:

```bash
./target/debug/
./target/debug/deps/
~/.rustup/toolchains/<your_toolchain>/lib/
~/lib/
```

⚠️ When you're shipping your application make sure to copy FMOD libraries to the same directory that your executable is
in.

**Why no build options?**

* FMOD does not allow static linking
* The crate not implement dynamic loading, only dynamic linking
* There is no simple way to control how Rust search for libraries

So, we can provide some configuration (e.g "FMOD_SDK" location variable), but this is not useful
because you still have to install the FMOD libraries as described above.

### Features

You can enable or disable crate features depending on your needs:

- `flags`*(default)* provides C-style flags with ergonomic Rust API based
  on [bitflags](https://crates.io/crates/bitflags) crate
- `logging` links logging version of FMOD libraries (fmodL.dll, fmodstudioL.dll, etc)

### Getting Started

The simplest way to get started is to initialize the FMOD system, load a sound, and play it.
Playing a sound does not block the application, all functions execute immediately, so we should poll for the sound to
finish.

```rust
use libfmod::{Error, System, Init, Mode};

fn test_playing_sound() -> Result<(), Error> {
    let system = System::create()?;
    system.init(512, Init::NORMAL, None)?;
    let sound = system.create_sound("./path/to/my/sound.ogg", Mode::DEFAULT, None)?;
    let channel = system.play_sound(sound, None, false)?;
    while channel.is_playing()? {
        // do something else
    }
    system.release()
}
```

See more examples in [tests](libfmod/tests) folder.

### Contributing

This library is generated by [libfmod-gen](libfmod-gen) and can't be changed manually.

But understanding how a generator works can be quite challenging. So you could make changes of [libfmod](libfmod)
manually to show in pull request how the final code should look.