Wwise SDK 2021.1.5
To use SoundFrame, you will need the following files:
include/AK/SoundFrame/SF.h and include/AK/SoundFrame/SFObjects.h
These files need to be included for the SoundFrame client.
This file is the debug library for the SoundFrame client.
This file is the release library for the SoundFrame client.
The following sample is also available:
These files are related to the SoundFrame Test sample application.
The following example is the basic code structure of the SoundFrame client:
Caution: In order for SoundFrame to receive messages from the Wwise authoring tool,
While the client holds SoundFrame, it can use it to interact with Wwise in the following ways:
- Working with Wwise Objects.
- Working with Attenuation.
- Working with the Sound Engine API.
- Working with SoundBanks in SoundFrame.
SoundFrame gives you the power to integrate Wwise objects into your applications. With SoundFrame, you can perform tasks such as event playback, switch assignation, and environment setting. The following Wwise objects can be used with SoundFrame:
- Dialogue Events
- Game Parameters
- Environmental Effects.
When using Wwise objects in your applications, it is important to know how to reference them. There are two ways to reference a Wwise object:
- By name: The preferred way for a game that uses SoundBanks containing strings.
- By AudioEngine ID: The preferred way for a game that uses SoundBanks without strings.
When you want to integrate Wwise objects into your applications, you can enable this functionality using either of the following methods:
Send to SoundFrame command in Wwise (for events only)
Listen to Notif_Push notifications in your
Drag and Drop
Use ISoundFrame::GetDnDType and the various drag and drop process methods in your drag-and-drop handlers.
When your projects include attenuation, it is useful to see the maximum attenuation values that are defined in Wwise displayed in your applications. With SoundFrame, you can display attenuation values and also register for notifications when these values are modified in Wwise.
From SoundFrame's perspective, attenuation is a property of a sound object (refer to ISoundObject for more information). To display attenuation values in your application:
- From an event, follow the path: IEvent > IActionList > IAction > ISoundObject.
After you have adapted your application to properly display attenuation values, it is preferable that you register for attenuation change notifications.
To register for attenuation change notifications:
- Call AK::SoundFrame::ISoundFrame::ListenAttenuation.
You will then receive notifications of type Notif_Changed in
AK::SoundFrame::IClient::OnSoundObjectNotif when attenuation values are modified in Wwise.
To unregister from attenuation change notifications:
- Call AK::SoundFrame::ISoundFrame::ListenAttenuation with empty parameters. The attenuation notifications will no longer be sent.
SoundFrame gives you access to most of the Sound Engine API. This enables you to play back Events as well as modify States, Switches, RTPCs, Triggers, and environments in your application. This API lets you simulate real game scenarios directly in Wwise without requiring a working game engine or even having to generate SoundBanks.
If you want users to be able to play back Events from within your applications, you will have to enable Event playback as follows:
- Call ISoundFrame::PlayEvents.
|Note: When your application goes into Play mode many events will be fired in a long sequence. Therefore, it is recommended to set the playback mode to True using ISoundFrame::SetPlayBackMode during playback. When the playback is done you can set the playback mode back to False. Setting the playback mode to False will stop all playbacks in Wwise.|
SoundFrame lets you change the active states and switches in your applications to simulate real game scenarios. The following methods let you do this:
SoundFrame gives you access to methods that let you create or remove game objects and modify their positions in three dimensions. It also lets you define listeners and place them where you want within your applications. To do so, use the following methods:
SoundFrame allows you to modify RTPCs, environments, as well as launch interactive music triggers so that you can create even more realistic game simulations. You can also define the obstruction and occlusion levels of your game objects. To do so, use the following methods:
SoundBanks can be created and populated with events manually by the Wwise user in the SoundBank Manager.
However, if you use another application, such as a 3D application or level editor to integrate events into your game, you can generate a SoundBank definition file from that application and then import it in Wwise to automatically create and populate SoundBanks.
A definition file is a text file that lists all the events in your game, classified by SoundBank. The definition file must include the name of the SoundBank and the corresponding event name, separated by a tab. The following illustration demonstrates how a definition file should be written so that it can be read by Wwise.
The definition file can also include special keywords that define the types of project elements that will be packaged in the SoundBanks. The following keywords can be used:
- Event: specifies that event information will be packaged with the SoundBank.
- Structure: specifies that sound and music structure information will be packaged with the SoundBank.
- Media: specifies that audio media files will be packaged with the SoundBank.
In the definition file, one or more of these keywords can be added after the event name, with each one being separated by a tab. If no keywords are included in the definition file, all project elements and media will be packaged in the SoundBank. The following illustration demonstrates how these keywords should be used within a definition file.
If your game is not using strings for event names, you can use any of the following systems to define the events in the definition file:
The following illustration demonstrates how to define events in a definition file using the four different systems.
Event IDs are available through SoundFrame in various functions:
- AK::SoundFrame::IEvent::GetID(): Numeric ID (can be written as hexadecimal or decimal in the definition file)
- AK::SoundFrame::IClient::OnEventNotif(): The numeric ID of the event is passed as a parameter
Refer to AK::SoundFrame::IEvent, AK::SoundFrame::IClient and AK::SoundFrame::ISoundFrame for more details.
SoundBank definition files can either be imported manually, or through SoundFrame.
If your application generates a SoundBank definition file, you can make a call to notify Wwise that a new definition file needs to be imported.
To notify Wwise that a new SoundBank definition file needs to be imported:
- Call AK::SoundFrame::ISoundFrame::ProcessDefinitionFiles.
|Note: Note that the SoundBanks created by the definition file are located in the default SoundBank Work Unit. To create your SoundBank in a different Work Unit you need to import definition file manually in Wwise.|
If your application does not generate a SoundBank definition file, you can make a call to notify Wwise that the SoundBanks need to be regenerated.
To notify Wwise that the SoundBanks need to be regenerated:
- Call AK::SoundFrame::ISoundFrame::GenerateSoundBanks.
To create or update SoundBanks in Wwise by importing a definition file:
- From the SoundBanks tab in the Project Explorer, right click on a Work Unit to open the contextual menu and choose "Import SoundBank Definition ...". The Open dialog box opens.
- Navigate to the location where the definition file was created.
- Click Open.
The Import Definition Log dialog box opens.
- Review the import activity in the log. The import activity can be any one of the following:
- SoundBank Created: A new SoundBank has been created.
- Event Added: A new event has been added to an existing or new SoundBank.
- Event Deleted: An event has been deleted from an existing SoundBank (see the note below for details).
- Event Missing: An event listed in the file no longer exists in the project or has yet to be created.
- No Change Detected: The imported SoundBank is identical to the one already in Wwise.
- Click Close.
The SoundBanks that are defined in the definition file are created and/or updated in Wwise.
|Note: Wwise remembers if an Event was added manually by a user, or automatically by importing a SoundBank definition file. Only Events that were added by importing a definition file will be removed from the SoundBank during a subsequent definition file importation. Manually added Events will not be removed from the SoundBank even if they are not listed in the definition file.|