如何集成 SoundFrame

使用 SoundFrame

以下示例是 SoundFrame 客户端的基本代码结构：

#include <AK/SoundFrame/SF.h>

class SoundFrameClient
    : public AK::SoundFrame::IClient
{
    AK::SoundFrame::ISoundFrame * m_pSoundFrame;
public:

    SoundFrameClient()
        : m_pSoundFrame( NULL )
    {
        AK::SoundFrame::Create( this, &m_pSoundFrame );
        
        if ( m_pSoundFrame )
            m_pSoundFrame->Connect();
    }

    ~SoundFrameClient()
    {
        if ( m_pSoundFrame )
            m_pSoundFrame->Release();
    }

    // SoundFrame::IClient 方法

    virtual void OnConnect( bool in_bConnect ) {}
    virtual void OnEventNotif( Notif in_eNotif, AkUniqueID in_eventID ) {}
    virtual void OnDialogueEventNotif( Notif in_eNotif, AkUniqueID in_dialogueEventID ) {}
    virtual void OnSoundObjectNotif( Notif in_eNotif, AkUniqueID in_soundObjectID ) {}
    virtual void OnStatesNotif( Notif in_eNotif, AkUniqueID in_stateGroupID ) {}
    virtual void OnSwitchesNotif( Notif in_eNotif, AkUniqueID in_switchGroupID ) {}
    virtual void OnGameParametersNotif( Notif in_eNotif, AkUniqueID in_gameParameterID ) {}
    virtual void OnTriggersNotif( Notif in_eNotif, AkUniqueID in_triggerID ) {}
    virtual void OnArgumentsNotif( Notif in_eNotif, AkUniqueID in_argumentID ) {}
    virtual void OnEnvironmentsNotif( Notif in_eNotif, AkUniqueID in_environmentID ) {}
    virtual void OnGameObjectsNotif( Notif in_eNotif, AkGameObjectID in_gameObjectID ) {}
}

Caution: 为了能让 SoundFrame 从 Wwise 设计工具中接收消息，AK::SoundFrame::ISoundFrame::Connect 必须创建一个窗口。此函数必须从应用程序消息泵所在的同一线程中调用。

虽然客户端持有 SoundFrame，但它可以使用此接口通过以下方式与 Wwise 互动：

使用 Wwise 对象

SoundFrame 为您提供将 Wwise 对象集成到应用程序的功能。通过 SoundFrame，您可以执行播放事件、指定切换开关和设置环境等任务。以下 Wwise 对象可结合 SoundFrame 一起使用：

Events（事件）
Dialogue Events（对白事件）
States（状态）
Switches（切换开关）
Game Parameters（游戏参数）
Triggers（触发器）
Arguments（参数）
环境效果器。

引用 Wwise 对象

在当您的应用程序中使用 Wwise 对象时，知道如何引用它们很重要。引用 Wwise 对象分两种方式：

通过名称引用——这是 SoundBank 中包含字符串的游戏的首选方式。
通过 AudioEngine ID 引用——这是 SoundBank 中不含字符串的游戏的首选方式。

将 Wwise 对象集成到应用程序

当您想将 Wwise 对象集成到应用程序时，可使用以下任一方法启用此功能：

Wwise 中的 Send to SoundFrame 命令（仅限于事件）
侦听 IClient::OnEventNotif 中的 Notif_Push 通知。
Drag and Drop
使用 ISoundFrame::GetDnDType 和拖放处理程序中的各种拖放处理方法。

使用衰减

当您的工程中包含衰减时，如果能在应用程序中查看 Wwise 中定义的最大衰减值会非常有用。通过 SoundFrame，您可以显示衰减值，并且当在 Wwise 中修改这些值时，还可注册获取通知。

显示衰减

从 SoundFrame 的角度来看，衰减是声音对象的属性（请参阅 ISoundObject 了解更多信息）。在应用程序中显示衰减值的方法：

在事件中，遵循路径：IEvent > IActionList > IAction > ISoundObject。

注册获取衰减变化通知

在修改您的应用程序来正确显示衰减值后，最好注册获取衰减变化通知。

注册获取衰减变化通知的方法：

调用 AK::SoundFrame::ISoundFrame::ListenAttenuation。

然后当在 Wwise 中修改衰减值时，您将在、AK::SoundFrame::IClient::OnSoundObjectNotif 中收到 Notif_Changed 类型通知。

取消获取衰减变化通知：

使用空参数调用 AK::SoundFrame::ISoundFrame::ListenAttenuation。此后将不再发送衰减通知。

使用 SoundEngine API

SoundFrame 可访问大多数声音引擎 API。它可以让您启用事件播放，以及修改应用程序中的状态、切换开关、RTPC、触发器和环境。此 API 可以让您在 Wwise 中直接模拟真实的游戏场景，无需运行游戏环境，甚至不必生成 SoundBank。

启用事件的播放

如果您希望用户能够在您的应用程序中播放事件，则必须按照以下方式启用事件播放功能：

调用 ISoundFrame::PlayEvents。

Note: 当您的应用程序进入播放模式时，许多事件将排长队进行播放。因此建议在播放期间使用 ISoundFrame::SetPlayBackMode 将播放模式设置为 True。当播放结束时，您可以将播放模式重新设为 False。把播放模式设为 False 将停止 Wwise 中的一切播放。

修改游戏状态和切换开关

SoundFrame 可以让您更改应用程序中的活跃状态和切换开关来模拟真实的游戏场景。以下方法可以让您来做到这一点：

ISoundFrame::SetCurrentState
ISoundFrame::SetCurrentSwitch

创建游戏对象和修改它们的位置

SoundFrame 可以让您访问用于创建或移除游戏对象以及修改它们三维位置的方法。它还可让您定义听者，并将它们布置在应用程序中您希望的位置。为此，使用以下方法：

ISoundFrame::RegisterGameObject
ISoundFrame::UnregisterGameObject
ISoundFrame::SetActiveListeners
ISoundFrame::SetPosition
ISoundFrame::SetListenerSpatialization

修改 RTPC、触发器和环境

SoundFrame 可以让您修改 RTPC 和环境，以及启用互动音乐触发器，从而您可以创建更加逼真的游戏模拟。您还可以定义游戏对象的声障和声笼级别。为此，使用以下方法：

ISoundFrame::SetRTPCValue
ISoundFrame::PostTrigger
ISoundFrame::SetGameObjectAuxSendValues
ISoundFrame::SetGameObjectOutputBusVolume
ISoundFrame::SetEnvironmentVolume
ISoundFrame::BypassEnvironment
ISoundFrame::SetObjectObstructionAndOcclusion

在 SoundFrame 中使用 SoundBank

音频设计师可在 SoundBank Manager 中手动创建 SoundBank 并向其中装入事件。

然而，如果您要使用别的应用程序（例如 3D 应用程序或关卡编辑器）将事件集成到您的游戏中，则可以用该应用程序生成 SoundBank 定义文件，然后导入到 Wwise 以自动创建和填充 SoundBank。

SoundBank 定义文件格式

定义文件是按照 SoundBank 分类列出游戏中所有事件的文本文件。定义文件必须包含 SoundBank 的名称和相应事件名称，两者之间通过制表符隔开。下图演示应该如何编写定义文件，以使 Wwise 能够读取定义文件。

定义文件还包含特定关键词，这些关键词定义 SoundBank 中打包的工程元素类型。可以使用以下关键词：

事件：指定与 SoundBank 一起打包的事件信息。
结构：指定声音和音乐结构信息将与 SoundBank 一起打包。
媒体：指定音频媒体文件将与 SoundBank 一起打包。

在定义文件中，可在事件名称后添加若干个关键词，每个关键词通过制表符隔开。如果定义文件中不包含关键词，则所有工程元素和媒体都将打包到 SoundBank 中。下图演示如何在定义文件中使用这些关键词。

如果您的游戏未对事件名称使用字符串，则可在定义文件中使用以下任何系统来定义事件：

十六进制
十进制

下图演示如何在定义文件中使用四种不同的系统来定义事件。

在各种函数中，可通过 SoundFrame 获取事件 ID：

AK::SoundFrame::IEvent::GetID(): Numeric ID（在定义文件中可写成十六进制或十进制）
AK::SoundFrame::IClient::OnEventNotif()：事件的数字 ID 作为参数传递

请参阅 AK::SoundFrame::IEvent、AKSoundFrame::IClient 和 AK::SoundFrame::ISoundFrame 了解更多详情。

在 Wwise 中导入 SoundBank 定义文件

SoundBank 定义文件可手动导入，也可通过 SoundFrame 导入。

通过 SoundFrame 导入 SoundBank 定义文件

如果您的应用程序生成 SoundBank 定义文件，您可以通过调用来通知 Wwise 需要导入新的定义文件。

通知 Wwise 需要导入新 SoundBank 定义文件的方法是：

调用 AK::SoundFrame::ISoundFrame::ProcessDefinitionFiles。

Note: 注意，定义文件创建的 SoundBank 位于默认 SoundBank Work Unit（工作单元）中。要在不同的 Work Unit 中创建 SoundBank，您则需要在 Wwise 中手动导入定义文件。

如果您的应用程序未生成 SoundBank 定义文件，您可以通过调用来通知 Wwise 需要重新生成 SoundBank。

通知 Wwise 需要重新生成 SoundBank 的方法是：

调用 AK::SoundFrame::ISoundFrame::GenerateSoundBanks。

手动导入 SoundBank 定义文件

通过导入定义文件在 Wwise 中创建或更新 SoundBank 的方法是：

在 Project Explorer 的 SoundBanks 选项卡上，右键单击工作单元以打开上下文菜单，并选择“Import SoundBank Definition ...”。 Open 对话框打开。
前往创建定义文件的位置。
单击 Open。
Import Definition Log 对话框打开。
在日志中查看导入活动。导入活动可以是以下任何一项：
- SoundBank Created——创建了新 SoundBank。

Event Added——向现有或新 SoundBank 中添加了新事件。
Event Deleted——从现有 SoundBank 中删除了事件（请参阅下文注释了解详情）。
Event Missing——工程中不再存在文件中所列的事件，或者尚未创建该事件。
No Change Detected——导入的 SoundBank 与 Wwise 中已经存在的 SoundBank 完全相同。

单击 Close。
定义文件中定义的 SoundBank 于是会在 Wwise 创建出来或更新。

Note: Wwise 会记住事件是由用户手动添加还是通过导入 SoundBank 定义文件自动添加的。只有通过导入定义文件添加的事件在后续的定义文件导入过程中才会从 SoundBank 中移除。手动添加的事件不会从 SoundBank 中移除，即使没有列举在定义文件中也是如此。

此页面对您是否有帮助？

需要技术支持？

仍有疑问？或者问题？需要更多信息？欢迎联系我们，我们可以提供帮助！

查看我们的“技术支持”页面

介绍一下自己的项目。我们会竭力为您提供帮助。

来注册自己的项目，我们帮您快速入门，不带任何附加条件！

开始 Wwise 之旅

Wwise SDK 2017.1.9