|
Wwise SDK 2019.2.15
|
Wwise 的开放架构支持三种插件，它们分别是用于生成声音的源插件、用于增强声音的效果器插件和支持在 Wwise 中使用版本控制软件的版本控制插件。
前两种插件使用了 XML 插件描述文件，可以让您快速更改包括插件默认属性值在内的一些设置，而无需重新编译代码。Wwise 插件 DLL 可以包含多个插件，相关 XML 文件中必须对每个插件进行描述。
每个 Wwise 插件 DLL 的 XML 描述文件具有与 DLL 相同的名称，而扩展名可以不同。例如，如果您的 DLL 命名为“MyPlugin.dll”，那么插件描述文件必须命名为“MyPlugin.xml”。
XML 文件的内容
XML 描述文件包含有关 Wwise 插件的多方面信息，包括：
- 插件名称
- 公司 ID 和插件 ID。请参阅 Wwise 插件 ID 了解详情。
- 各平台所支持的功能
-
属性定义，包括：
- 属性名称（在代码中和持久化文件中标识属性的字符串）
- 属性类型
- RTPC 支持
- 默认值
- 声音引擎属性 ID（将此属性绑定到声音引擎插件的代码中）
- 值域限制或枚举限制
- 对其他属性的依赖性
- 用户界面描述元素
-
内部对象类型定义，包括：
- 内部对象类型名称（标识内部对象类型的字符串）
- 内部对象属性
示例：XML 描述文件
以下是一个简单插件 XML 描述文件的示例。
让我们详细地考察 XML 文件的各个部分。
XML 描述文件头
让我们考察此 XML 文件头的组成部分并详细地讨论。
任何 XML 文件的第一行都是定义 XML 版本和编码方式。在本例中，XML 版本是 1.0，编码方式是 UTF-8 。任何 Wwise 插件描述文件的第一行应该总是与此完全一致。第二行是 XML 注释，在本例中是版权声明。您可以在 XML 文件的所需位置添加注释。
PluginModule元素
本文档中的主要 XML 元素命名为 PluginModule ，包含此文件中定义的各种插件的全部信息。
EffectPlugin和SourcePlugin元素
EffectPlugin 元素是定义单个效果器插件的主要元素，而 SourcePlugin 是源插件的元素名称。
这些元素包含三个必须属性：:
-
Name（必需）：此字符串指定了插件在 Wwise 中显示的名称。 -
CompanyID（必需）：此字符串必须为正整数，遵守以下值域范围：- 64-255：您可以自由地将它们用于内部团队开发和使用的插件。 它们不适用于要对外发行的插件。
- 256-4095：保留用于商用插件。 Audiokinetic 将其分配给官方的第三方开发人员使用。如果您是官方的第三方开发人员之一，则可以使用 56-4095，而非 64-255 范围中的值。否则请勿使用这些值。
- 0-63：不可用。保留给 Audiokinetic 使用。
-
PluginID（必需）：此字符串必须是位于 0-32767 范围内的一个正整数。每个 PluginID 对于指定的 CompanyID 必须唯一。 -
SupportsIsSendModeEffect（可选）：（仅限于效果器插件）通过在初始化期间查询 AK::IAkEffectPluginContext::IsSendModeEffect() 获得，此布尔值指示插件是否支持发送模式。当 IsSendModeEffect() 返回 true，插件不应输出干声信号，而且应忽略干声电平属性。 -
EngineDllName(optional): This string value indicates which dynamic library to load at game runtime (by default it will be the same name as the XML). IfEngineDllNameis specified, ensure that both the static and dynamic libraries built from your plug-in share the same name. 在商用游戏引擎（例如 Unity 和 Unreal 4）中，必须为您的插件提供 DLL/so 文件。注意，此 DLL 不是 XML 相对应的 DLL 文件，其中包含所有属性页面 UI，您不可将它放置到游戏中。
例如，如果您正在开发仅供内部使用的两个源插件和一个效果器插件，那么可以选择介于 64 与 255 之间的任意一个数作为 CompanyID，介于 0 与 32767 之间的任何三个数作为 PluginID。三个数字不需要连续。
 |
注意: 如果您以 Audiokinetic 提供的一个插件示例（示例插件 ）为基础开发您的插件，不要忘记把 CompanyID 和 PluginID 更改为适当值。如果您有一个指定的官方 CompanyID，则使用它；如果没有，可以使用介于 64 与 255 之间的一个数。请确保该 CompanyID 的 PluginID 不重复。 |
如果同一个 CompanyID 具有两个或两个以上的相同 PluginID，Wwise 将在启动时显示错误消息。如果发生这种情况，则需更改新插件的 ID。
|
注意: 一定不要更改现有插件的 CompanyID 或 PluginID。否则使用该插件的工程将无法识别插件。CompanyID 和 PluginID 在每个源插件或效果器插件实例中始终保持一致，在加载文件时它们将用于重新创建正确的插件。 |
对于用于标识插件的函数，CompanyID 和 PluginID 属性对应于传递给它们的参数：
-
AkCreatePlugin()（请参阅 导出函数 ） -
AK::SoundEngine::RegisterPlugin()
 |
备注: 如果 DLL 中实现了多个插件，则 XML 文件将包含多个 EffectPlugin 或 SourcePlugin 条目。 |
PluginInfo 元素
PluginInfo/PlatformSupport 部分定义了插件支持的平台。它能包含一个或更多 Platform 要素，其中每个都指定了每个平台上插件支持的不同特性。可指定以下功能：
-
CanBeInsertOnBusses确定效果器是否可用来控制和主导总线。通常这需要效果器支持环绕声音频配置。 -
CanBeInsertOnAuxBusses确定效果器是否可用来控制和主导辅助总线。通常这需要效果器支持环绕声音频配置。注意，如果已经设置 CanBeInsertOnBusses，则效果器就已经可应用于辅助总线。 -
CanBeInsertOnAudioObjects确定效果器是否可作为作用于音效的插入效果（必须支持单声道和立体声处理）。 -
CanBeRendered确定效果器是否可用于离线渲染。 -
CanBeInsertEndOfPipeline决定效果器是否只能用在音频管线的末端，相当于顶层 Audio Bus 的最后一个效果器插槽（预留给 Audiokinetic 使用）。
在 Wwise 中，您的插件只可用于指定的平台。
另外，也可选择添加 Any 平台，而无需列出所有支持的平台。不过，这样的话会在 Wwise 中将此插件报告为适用于所有平台。若该插件没有提供匹配的运行时库，则用户只有在对应平台上设置端口时才会注意到。
属性要素
每个效果器或源插件都能定义属性和引用。有关属性和引用的更多信息，请参照 Plug-in 属性和自定义属性 XML 描述 。
内部对象
InnerTypes 部分定义了插件内您可以实例化和使用的可能内部对象类型。可以在 InnerTypes 部分定义多个 InnerType。每个 InnerType 必须具有唯一名称和插件 ID。InnerType 部分包含 Properties 部分，您可以使用定义插件属性的相同方式定义其属性。
当插件中需要多个对象实例时，Inner Types 非常实用。例如，当具有不定数量的 EQ Band 时，就可以为 EQ 插件定义 Inner Type Band 。每个 and 拥有相同的属性定义，但值不同。
|
备注: Inner Types 的属性不支持 RTPC。因此将不能使用 SupportRTPCType 属性和 AudioEnginePropertyID 元素。 |
|
备注: InnerTypes 只在源插件和效果器插件内受支持。 |
为了在插件代码中使用 Inner Type 实例（内部对象），您需要在插件初始化时通过框架提供的 AK::Wwise::IPluginObjectStore 指针来调用 AK::Wwise::IAudioPlugin::SetPluginObjectStore()。AK::Wwise::IPluginObjectStore 接口提供了用于创建和删除内部对象的函数。在创建对象时，必须使用插入和移除功能将它们存储在一个带名称的列表中。
例如，您可以创建类型为 Band 的内部对象，并将它存储在 BandList 中：
|
备注: 内部对象只能存储在一个列表中。 |
请参见以下主题：
在向对象库中添加内部对象时，Wwise 会自动创建相关的撤消机制，您无需亲自实现撤消系统。但为了正常地支持撤消事件，您只需在收到框架通知时更新用户接口即可。例如，在对 IPluginObjectStore 调用 InsertObject 后，请勿立即更新 UI，而应等待您的插件上调用通知 AK::Wwise::IAudioPlugin::NotifyInnerObjectAddedRemoved。此通知告诉您对象已添加到列表或者已从列表中移除。它可以来自用户的动作，也可以来自撤消机制。
AK::Wwise::IAudioPlugin::NotifyInnerObjectPropertyChanged 也可能对您有用，当内部对象中的属性值变化时，将调用此函数。
工程工作单元中的一致性由 Wwise 自动处理。但您必须对声音库中的内部数据和声音引擎数据实施序列化。须将 AK::Wwise::IAudioPlugin::GetPluginData 和 AK::Wwise::IAudioPlugin::GetBankParameters 中的内部对象进行序列化。
故障排除
如果您遇到任何问题，请参阅 Wwise 源插件和效果器插件故障排除指南 。