Release 0.1.3

- Linux build & run support
- Modularize and cleanup build script
- Vorbis playback support
- Cargo features for static linking of Wwise plugins
- Fix unsafe memory accesses when converting to AkOsChar* and char*
- Example refactored to be platform agnostic
- Example demonstrates static/dynamic plugin registration for Vorbis compression (static), AkMeterFX (static) and AkRoomVerbFX (dynamic)

Author: dtaralla

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rrise"
-version = "0.1.0"
+version = "0.1.3"
 edition = "2018"
 authors = ["David Taralla <davidtaralla@gmail.com> & Contributors to the Rrise project"]
 description = "A rust binding for Wwise"
@@ -13,19 +13,53 @@ license-file = "LICENSE"
 
 [dependencies]
 ctrlc = { version = "3.2.1", optional = true }
+simple_logger = { version = "2.1.0", optional = true }
+paste = "1.0.7"
+log = "0.4.16"
 
 [build-dependencies]
 bindgen = "0.59.2"
 cc = "1.0.73"
+paste = "1.0.7"
 
 [target.'cfg(windows)'.build-dependencies.winreg]
 version = "0.10.1"
 
-[[example]]
-name = "windows_sample"
-required-features = ["ctrlc"]
-
 [lib]
 name = "rrise"
 path = "src/rrise.rs"
 crate-type = ["dylib", "rlib"]
+
+[features]
+default = ["AkVorbisDecoder", "AkMeterFX"]
+AkVorbisDecoder = []
+AkOpusDecoder = ["AkOggOpusDecoder", "AkWemOpusDecoder"] # KNOWN LIMITATION: link error if you use it
+AkAudioInputSource = []
+AkCompressorFX = []
+AkDelayFX = []
+AkExpanderFX = []
+AkFlangerFX = []
+AkGainFX = []
+AkGuitarDistortionFX = []
+AkHarmonizerFX = []
+AkMatrixReverbFX = []
+AkMeterFX = []
+AkParametricEQFX = []
+AkPeakLimiterFX = []
+AkPitchShifterFX = []
+AkRecorderFX = []
+AkRoomVerbFX = []
+AkSilenceSource = []
+AkSineSource = []
+AkStereoDelayFX = []
+AkSynthOneSource = []
+AkTimeStretchFX = []
+AkToneSource = []
+AkTremoloFX = []
+# Internal features, don't enable independantly!
+AkOggOpusDecoder = []
+AkWemOpusDecoder = []
+
+[[example]]
+name = "looping_event"
+required-features = ["ctrlc", "simple_logger"]

README.md

@@ -18,32 +18,94 @@ or architectural choices, please reach out to improve the crate!
 
 Pull requests are more than welcome: **they are encouraged**!
 
-## Features
-Currently, this crate can do very little, and only on Windows platforms:
-- Windows 10+ support
-- Initialize/Update/Terminate a minimal sound engine
+## Capabilities
+- Build & run on Windows 10+
+- Build & run on WSL/Linux (on distros where Wwise is supported)
+- (AD)PCM & Vorbis playback
+- Initialize/Update/Terminate a sound engine
 - Post simple events (no callback/external source support yet)
 - Default streaming manager leveraging Wwise's sample streaming manager
-- Profiling from the Wwise authoring tool.
-- Minimal example showcasing how to initialize the sound engine, interact with it and terminate it.
+- Profiling from the Wwise authoring tool
+- Minimal example showcasing how to initialize the sound engine, post an event and terminate it
+- Dynamic & static linking of Wwise plugins through cargo features
+
+### Logging
+Rrise uses the [log](https://docs.rs/log/latest/log/index.html) crate for all its logging needs. Refer to `log`'s 
+docs for how to use it.
+
+The provided `looping_event` example installs a [simple_log](https://docs.rs/simple_logger) to get Rrise logs to 
+display in the console.
+
+### Wwise Plugins
+You can [choose](https://www.audiokinetic.com/library/edge/?source=SDK&id=soundengine_integration_plugins.html) to 
+either link statically or dynamically to the Wwise plugins.
+
+Note that some plugins like _AkMeter_ can only be statically linked and are not available for dynamic linking.
+
+See [this page](https://www.audiokinetic.com/library/edge/?source=SDK&id=goingfurther_builds.html#wwise_sdk_lib_dependency_requirements_plugins)
+for a list of plugins supported by Wwise, per platform.
+
+#### Dynamic linking
+This is the default behavior. Wwise plugins like _AkRoomVerb_, _AkMeter_, _Motion_ etc. will be loaded at runtime from 
+their respective shared library as needed.
+
+Any project relying on dynamic linking for some plugins needs to also deploy their respective *licensed* shared 
+libraries along the final executable (you can do this with a 
+[build script](https://doc.rust-lang.org/cargo/reference/build-scripts.html) for instance).
+
+You can find these shared libraries in `$WWISESDK/[platform]/[config]/bin`.
+
+#### Static linking
+You might want to statically link some Wwise plugins instead of loading them at runtime from a shared libary. In 
+this case, you can leverage Rrise's cargo features to enable static linking of such plugins.
+
+For example, if you want to statically link the _AkRoomVerb_ plugin, just build with the `AkRoomVerbFX` feature 
+enabled. When your project runs, you can check that the static version of the plugin was loaded in the debug log:
+```
+AkRoomVerbFX has been statically loaded successfully
+```
+**Note:** If you already built your project once, you need to make Rrise's build script rerun to enable static 
+linking of your features. You can change the value of the `RRISE_RERUN_BUILD` environment variable before building to 
+force a rerun of Rrise's build script. You can also force a full rebuild with `cargo clean & cargo build 
+--features=The,Plugin,List`. 
+
+### Known issues & limitations
+- Issue when linking AkOpusDecoder: Opus is currently unavailable.
+- `wwconfig` cfg flag doesn't seem to be forwarded to the build scripts?
+- If you dynamically link Wwise effect plugins (default behavior), there is an issue on Windows where if the path given
+to `AkInitSettings::with_plugin_dll_path` contains spaces, the DLLs in that folder won't be discoverable by Wwise.
+- On Linux, when connecting the profiler, you will get those messages in the console (they seem totally harmless):
+```
+.../SDK/Linux_x64/Profile/bin/libDefaultConversions.so: cannot open shared object file: No such file or directory
+.../SDK/Linux_x64/Profile/bin/libAkSoundEngineDLL.so: cannot open shared object file: No such file or directory
+```
 
 ## Requirements
+- The `bindgen` crate [requirements](https://github.com/rust-lang/rust-bindgen/blob/master/book/src/requirements.md)
 - A licensed (free, trial, commercial,...) version of Wwise installed
   - Wwise itself
   - Wwise SDK (C++)
-  - Wwise support for any Visual Studio 20XX deployment platform
-  - Make sure the `WWISESDK` environment is set to the SDK folder of your Wwise installation
-- MSVC[^1]
+- **On Windows: `MSVC`**[^1]
   - Windows 10 SDK
   - Build tools (same as Rust, for the `cc` crate)
-  - `cl.exe` must be in the PATH (current limitation of the build script)
-- The `bindgen` crate [requirements](https://github.com/rust-lang/rust-bindgen/blob/master/book/src/requirements.md)
+  - `cl.exe` must be in the PATH[^2]
+  - Wwise support for any Visual Studio 20XX deployment platform
+  - Make sure the `WWISESDK` environment variable is set to the SDK folder of your Wwise installation
+- **On Linux: `clang`**
+  - `g++` (for `libstdc++`)
+  - Copy the SDK folder from a Windows[^3] install of Wwise on your Linux workstation (for instance in /opt/wwise)
+    - Make sure the `WWISESDK` environment variable is set to that folder
+
 [^1]: Not tested on other compilers like MinGW or Clang
+[^2]: Current limitation of the build script. I want to improve MSVC path discovery in the future to remove this 
+requirement.
+[^3]: AudioKinetic doesn't provide direct downloads to their SDK: you can only install it through their launcher. 
+However, this launcher being only available on Windows and MacOS, you'll need to install it on a VM or similar before 
+you can work with this crate on Linux.
 
 ## Short-term roadmap
-- Add support for Linux/WSL
+- Make Opus playback available
 - Spatial module basic API and example
-- Modularize with features (especially profiling)
 - Add callback and user data support for PostEvent
 - Review/Improve architecture
 
@@ -52,4 +114,5 @@ Wwise and the Wwise logo are trademarks of Audiokinetic Inc., registered in the
 
 This project is in no way affiliated to Audiokinetic.
 
-You still need a licensed version of Wwise installed to compile and run this project.
+You still need a licensed version of Wwise installed to compile and run this project. You need a valid Wwise license 
+to distribute any project based on this crate.