Skip to content

Commit

Permalink
c2wwise rewrite, fixes #123, #126, and #127 (#130)
Browse files Browse the repository at this point in the history 
* c2wwise rewrite, fixes #126

* Fix edge case when no dac~ was in the patch, change includes layout, prevent Heavy from overriding "inline" keyword on Windows

* Add support for 5.1, 7.1, and 7.1.4 channel configurations

* Update Wwise docs

* Fix regression that failed on compiled output-less plugins

* Update Wwise docs

* Fix code style issue

* Wwise docs: clarify build example

* Wwise docs: remove temporary info

* Update Wwise docs

---------

Co-authored-by: ech <lol>
  • Loading branch information
@eu-ch
eu-ch authored Nov 27, 2023
1 parent e5ba75d commit 71c0b3f
Show file tree
Hide file tree
Showing 56 changed files with 1,094 additions and 3,183 deletions.
221 changes: 76 additions & 145 deletions docs/03.gen.wwise.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,198 +2,129 @@

## Version Support

`hvcc` will generate a Wwise plugin project that links against a particular Wwise SDK version.
`hvcc` will generate a Wwise plugin project that can be built with Audiokinetic's build system, see [Using the Development Tools](https://www.audiokinetic.com/en/library/edge/?source=SDK&id=effectplugin_tools.html). This system can generate project files for all supported platforms, as well as package the plugin for distribution with Wwise Launcher. Please refer to the official documentation for more details.

The default is currently `2017.2.2.6553`, however if it's necessary to link against a different Wwise SDK, change the value of `wwise_sdk_version` in the c2wwise generator (found [here](https://github.com/Wasted-Audio/hvcc/blob/master/generators/c2wwise/c2wwise.py#L58)) to the required SDK version string.
## Feature Overview

## Source Generator or FX Unit
Heavy currently supports the following Wwise features:

- Source or Effect plugins
- Using uncompressed audio to build samplers
- Input parameters are RTPC-controllable
- Output parameters can set RTPC in Wwise
- Output events can post arbitrary events in Wwise from the plugin

The type of plugin that **heavy** generates is dynamically determined depending on the [I/O channel configuration](02.getting_started.md#audio-input-output).
![Feature overview](img/docs_wwise_overview.png)

## Source Generator or FX Unit

If an `[adc~]` object exists in the patch the generated plugin with be an FX unit. Otherwise it'll be a source generator plugin.
The type of plugin that **heavy** generates is dynamically determined depending on the [I/O channel configuration](02.getting_started.md#audio-input-output). If an `[adc~]` object exists in the patch the generated plugin with be an FX unit. Otherwise it'll be a source generator plugin.

## RTPCs

The Wwise target supports both [input and output parameters](02.getting_started.md#exposing-parameters).

![rtpcs](img/docs_wwise_params.png)
![](img/docs_wwise_params.png)

### Input Parameters

Exposing an input parameter will automatically generate a Slider UI in the plugin interface, that can then be connected to RTPCs from your game.

### Output Parameters

Sending a `single float value` to an output parameters will in turn cause the corresponding Global RTPC of the same name to be set.

This is useful for letting the plugins control other behaviours within the game system.

**Note**: it's important that the naming of the output parameter and the global RTPC set up in Wwise are exactly the same.

The example patch below describes a simple envelope follower:

![authoring_plugin](img/docs_wwise_env.png)

## Authoring Plugin Installation

### Authoring Assets

The Authoring plugin is what shows up in the Wwise Authoring interface, you can assign this plugin to Sound SFX objects and hook up RTPCs to its parameters.

### Runtime Assets

The runtime components are used by the Wwise integration engine, these are the files that will be actually used by your game or application. We provide both a dynamic plugin that can be easily loaded into development engines like Unity and Unreal, as well a static library that can be compiled directly into the Wwise Integration.
Sending a `single float value` to an output parameters will in turn cause the corresponding RTPC of the same name to be set. It will be set on the same game object. **Note**: it's important that the naming of the output parameter and the global RTPC set up in Wwise are exactly the same.

### Windows Authoring 32bit
The example patch below describes a simple envelope follower that can be used to modulate other parameters of the same voice:

Take the following files found in the `Wwise Win32` target:
![Envelope follower with an output RTPC](img/docs_wwise_env.png)

* `HV_{PATCH_NAME}_WwiseSourceAuthPlugin.dll`
* `HV_{PATCH_NAME}_WwiseSourceAuthPlugin.xml`
### Posting Wwise Events from the Plugin

And place them in the following location:
Sending any message to an output event will post a Wwise event with the same name on the same game object. This can be used, for example, to trigger events in Wwise in response to RTPC changes, or to implement a generative event triggering system.

* `C:\Program Files (x86)\Audiokinetic\Wwise 2017.1.0.6302\Authoring\Win32\Release\bin\plugins`
Note, in some situations, Heavy may only be able to send one output message per tick, e.g. posting an event and setting an RTPC at the same time won't be possible. To work around this, you can spread these actions apart with a `[delay 1]` node, for example.

### Windows Authoring 64bit
### Multi-channel plugins

Take the following files found in the `Wwise Win64` target:
The plugin supports the following channel configurations:

* `HV_{PATCH_NAME}_WwiseSourceAuthPlugin.dll`
* `HV_{PATCH_NAME}_WwiseSourceAuthPlugin.xml`
- AK_SPEAKER_SETUP_MONO
- AK_SPEAKER_SETUP_STEREO
- AK_SPEAKER_SETUP_5POINT1
- AK_SPEAKER_SETUP_7POINT1
- AK_SPEAKER_SETUP_DOLBY_7_1_4

And place them in one of the following locations:
An appropriate configuration will be selected at compile time based on the number of inputs and outputs in a patch (e.g. `[adc~ 1 2 3 4 5 6]` will create a 5.1 plugin). As this information is compiled in, the plugins can only be used on busses with corresponding channel configurations and will print an error if used elsewhere. To work around this, you can enforce bus channel configuration in the 'General Settings' tab.

* `C:\Program Files (x86)\Audiokinetic\Wwise 2017.1.0.6302\Authoring\x64\Release\bin\plugins`
## Example: Building Your Plugin on Windows

### Mac OSX Authoring
### Installing Visual Studio and Required Components

The Wwise Authoring application for Mac OSX uses a Wine wrapper and therefore requires plugin binaries compiled for Windows.
To build Authoring and Engine plugins on Windows you’ll need:

Take the following files found in the `Wwise Win32` target:
- If using Visual Studio 2019:
- Desktop development with C++ workload
- MSVC v142 - VS 2019 C++ x64/x86 build tools
- C++ ATL for latest v142 build tools (x86 & x64)
- C++ MFC for latest v142 build tools (x86 & x64)
- Windows Universal CRT SDK
- Windows 10 SDK (10.0.19041.0)
- Different version can be specified in a generated
PremakePlugin.lua file
- If using Visual Studio 2022
- Requirements are the same as for 2019, but components of version v143 must be installed instead
- *Note:* Wwise of version at least 2022.1.5 is required to build plugins with this version of Visual Studio
- Wwise 2022 or later
- Version 2021 should work, too, but it wasn't tested
- SDKs with required deployment platforms must be installed through
Wwise Launcher

* `HV_{PATCH_NAME}_WwiseSourceAuthPlugin.dll`
* `HV_{PATCH_NAME}_WwiseSourceAuthPlugin.xml`
### Converting a Pure Data Patch to C++ Code

And place them in the following location:
Let's say we've got a Pd patch HvccTestFX71.pd which was saved on a Desktop. These commands will generate code for this patch and place it in *Hvcc_Out_Dir* directory:

* `/Applications/Audiokinetic/Wwise 2017.1.0.6302/Wwise.app/Contents/SharedSupport/Wwise2016/support/wwise/drive_c/Program Files/Audiokinetic/Wwise/Authoring/Win32/Release/bin/plugins/`

After installing the plugins the Wine cache will need to be refreshed, in a command-line application like Terminal run the following commands:

```bash
cd "/Applications/Audiokinetic/Wwise 2017.1.0.6302/Wwise.app/Contents/SharedSupport/Wwise2017/"
```

```bash
CX_ROOT="/Applications/Audiokinetic/Wwise 2017.1.0.6302/Wwise.app/Contents/SharedSupport/Wwise2017/" WINEPREFIX="/Applications/Audiokinetic/Wwise 2017.1.0.6302/Wwise.app/Contents/SharedSupport/Wwise2017/support/wwise/" ./bin/wineprefixcreate --snapshot
```cmd
cd C:\Users\login\Desktop
hvcc HvccTestFX71.pd -o Hvcc_Out_Dir -g wwise -n HvccTestFX71
```

Note: for different versions of Wwise make sure to edit the command text to include the relevant version string (`Wwise 2017.1.0.6302`).

## Adding a Source Plugin

![source_plugin](img/docs_wwise_source_plug.gif)

## Unity Integration

### Setting up the projects

First create a new Wwise project, add a Source plugin to a game object, create an Event to trigger it and add it to a Soundbank.

Then create a new Unity project, add the Wwise Unity integration package, reference your Wwise authoring application and previously created project.

Add an empty GameObject to your scene, add an AKBank and AKEvent object and initialise them with ones created in your Wwise project.

After following the instructions below to install the plugin, make sure your soundbanks have been generated and press play in the Unity editor.

### Windows 32bit
### Building C++ Code

From the `Wwise Windows 32bit` target take the following file:
Heavy generates a project compatible with Audiokinetic's [Development Tools](https://www.audiokinetic.com/en/library/edge/?source=SDK&id=effectplugin_tools.html), which can build the plugins for all supported platforms, see the documentation for more details. **Important:** Please close any running Wwise Authoring instance as it'll prevent the plugin from being built.

* `HV_{PATCH_NAME}_WwiseSourcePlugin.dll`
Change into the generated directory:

And place it in the following directory:

* `{UNITY_PROJECT}/Assets/Wwise/Deployment/Plugins/Windows/x86/DSP/`

### Windows 64bit

From the `Wwise Windows 64bit` target take the following file:

* `HV_{PATCH_NAME}_WwiseSourcePlugin.dll`

And place it in the following directory:

* `{UNITY_PROJECT}/Assets/Wwise/Deployment/Plugins/Windows/x86_64/DSP/`

### Mac OSX

From the `Wwise macOS 64bit` target take the following file from the `/osx/x86_64/Release/` directory:

* `libHV_{PATCH_NAME}_WwiseSourcePlugin.bundle`

And place it in the following directory:

* `{UNITY_PROJECT}/Assets/Wwise/Deployment/Plugins/Mac/DSP/`

*Note: the Mac OSX builds are 64bit only.*

### iOS

From the `Wwise iOS armv7a` target take the downloaded files:

* `libHV_{PATCH_NAME}_WwiseSourcePluginFactory.h`
* `libHV_{PATCH_NAME}_WwiseSourcePlugin.a`

And place it in the following directory:

* `{UNITY_PROJECT}/Assets/Wwise/Deployment/Plugins/iOS/DSP/`

## Compiling the Plugin

Each platform has its own way of compiling the plugins.

### Mac OSX

An Xcode project exists in the `unity/xcode` directory and the plugin may be built manually. It can also be compiled directly from the commandline.

```bash
$ cd unity/xcode
$ xcodebuild -project Hv_heavy_WwiseSourcePlugin.xcodeproj -target Hv_heavy_WwiseSourcePlugin -arch x86_64
```cmd
cd Hvcc_Out_Dir\wwise
```

The results are placed in `unity/build/macos/x86_64/Release`.

### iOS
Generate Visual Studio project files; note, WWISEROOT environment variable can be set from Wwise Launcher by clicking on *Set Environment Variables* button in front of an installed Wwise entry:

An Xcode project exists in the `unity/xcode` directory and the plugin may be built manually. It can also be compiled directly from the commandline.

```bash
$ cd unity/xcode
$ xcodebuild -project Hv_heavy_WwiseSourcePlugin.xcodeproj -target Hv_heavy_WwiseSourcePlugin -arch armv7s
```cmd
python %WWISEROOT%\Scripts\Build\Plugins\wp.py premake Authoring
python %WWISEROOT%\Scripts\Build\Plugins\wp.py premake Windows_vc160
```

The results are placed in `unity/build/macos/armv7s/Release`.

### Linux
Build Authoring and Engine plugins in Release configurations; for Visual Studio 2022 replace vc160 with vc170:

```bash
$ cd unity/linux
$ make -j
```cmd
python %WWISEROOT%\Scripts\Build\Plugins\wp.py build -c Release -x x64 -t vc160 Authoring
python %WWISEROOT%\Scripts\Build\Plugins\wp.py build -c Release -x x64 -t vc160 Windows_vc160
```

The results are placed in `unity/build/linux/x86_64/release`.
At this point, the plugins should be placed in correct SDK directories and be ready for use in the Authoring app.

### Windows
### Optional: Packaging the Binaries for Wwise Launcher

A Visual Studio 2015 project exists in the `unity/vs2015` directory and the plugin may be built manually. It can also be compiled directly from the commandline.
We can go a step further and package the plugins into a bundle that can be installed conveniently from Wwise Launcher.

```bash
$ cd unity/vs2015
$ "C:/Program Files (x86)/MSBuild/14.0/Bin/MSBuild.exe" /property:Configuration=Release /property:Platform=x64 /t:Rebuild Hv_heavy_WwiseSourcePlugin.sln /m
```cmd
python %WWISEROOT%\Scripts\Build\Plugins\wp.py package --version 2022.1.0.1 Authoring
python %WWISEROOT%\Scripts\Build\Plugins\wp.py package --version 2022.1.0.1 Windows_vc160
python %WWISEROOT%\Scripts\Build\Plugins\wp.py generate-bundle --version 2022.1.0.1
mkdir Bundle
copy /y bundle.json Bundle
copy /y *.tar.xz Bundle
```

The results are placed in `unity/build/win/x64/Release`.

Plugins for x86 may also be built by specifying `/property:Platform=x86`.
The *Bundle* directory now contains a packaged plugin you can install through Wwise Launcher, see Wwise Version -> Manage Plug-ins -> Install from directory / Install from archive.
Binary file added docs/img/docs_wwise_overview.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit 71c0b3f

Please sign in to comment.