Wwise 插件 XML 描述文件

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 version="1.0" encoding="UTF-8"?>
<!-- Copyright (C) 2006 Audiokinetic Inc. -->

PluginModule元素

<PluginModule>
    ...
</PluginModule>

本文档中的主要 XML 元素命名为 PluginModule ，包含此文件中定义的各种插件的全部信息。

WwiseObject元素

    <EffectPlugin Name="Wwise Parametric EQ" CompanyID="0" PluginID="105" SupportsIsSendModeEffect="false" EngineDllName="EQ">
        ...
    </EffectPlugin>

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 （可选）：此字符串值指示在游戏运行时要加载的动态库。在默认情况下，它与 XML 使用相同的名称。在商用游戏引擎（例如 Unity 和 Unreal 4）中，必须为您的插件提供 DLL/so 文件。注意，此 DLL 不是 XML 相对应的 DLL 文件，其中包含所有属性页面 UI，您不可将它放置到游戏中。

例如，如果您正在开发仅供内部使用的两个源插件和一个效果器插件，那么可以选择介于 64 与 255 之间的任意一个数作为 CompanyID，介于 0 与 32767 之间的任何三个数作为 PluginID。三个数字不需要连续。

Caution: 如果您以 Audiokinetic 提供的一个插件示例（示例插件）为基础开发您的插件，不要忘记把 CompanyID 和 PluginID 更改为适当值。如果您有一个指定的官方 CompanyID，则使用它；如果没有，可以使用介于 64 与 255 之间的一个数。请确保该 CompanyID 的 PluginID 不重复。

如果同一个 CompanyID 具有两个或两个以上的相同 PluginID，Wwise 将在启动时显示错误消息。如果发生这种情况，则需更改新插件的 ID。

Caution: 一定不要更改现有插件的 CompanyID 或 PluginID。否则使用该插件的工程将无法识别插件。CompanyID 和 PluginID 在每个源插件或效果器插件实例中始终保持一致，在加载文件时它们将用于重新创建正确的插件。

对于用于标识插件的函数，CompanyID 和 PluginID 属性对应于传递给它们的参数：

AkCreatePlugin() （请参阅导出函数）
AK::SoundEngine::RegisterPlugin()

Note: 如果 DLL 中实现了多个插件，则 XML 文件将包含多个 EffectPlugin 或 SourcePlugin 条目。

PluginInfo 元素

    <PlatformSupport>
           <Platform Name="Windows">
              <CanBeInsertOnBusses>true</CanBeInsertOnBusses>
              <CanBeInsertOnAudioObjects>true</CanBeInsertOnAudioObjects>
              <CanBeRendered>true</CanBeRendered>
              <CanBeInsertForFeedback>false</CanBeInsertForFeedback>
           </Platform>
           <Platform Name="Mac">
              <CanBeInsertOnBusses>true</CanBeInsertOnBusses>
              <CanBeInsertOnAudioObjects>true</CanBeInsertOnAudioObjects>
              <CanBeRendered>true</CanBeRendered>
              <CanBeInsertForFeedback>false</CanBeInsertForFeedback>
           </Platform>
           <Platform Name="iOS">
              <CanBeInsertOnBusses>true</CanBeInsertOnBusses>
              <CanBeInsertOnAudioObjects>true</CanBeInsertOnAudioObjects>
              <CanBeRendered>true</CanBeRendered>
              <CanBeInsertForFeedback>false</CanBeInsertForFeedback>
           </Platform>
           <Platform Name="XboxOne">
              <CanBeInsertOnBusses>true</CanBeInsertOnBusses>
              <CanBeInsertOnAudioObjects>true</CanBeInsertOnAudioObjects>
              <CanBeRendered>true</CanBeRendered>
              <CanBeInsertForFeedback>false</CanBeInsertForFeedback>
           </Platform>
           <Platform Name="PS4">
              <CanBeInsertOnBusses>true</CanBeInsertOnBusses>
              <CanBeInsertOnAudioObjects>true</CanBeInsertOnAudioObjects>
              <CanBeRendered>true</CanBeRendered>
              <CanBeInsertForFeedback>false</CanBeInsertForFeedback>
           </Platform>
      </PlatformSupport>

PluginInfo/PlatformSupport 部分定义了插件支持的平台。它能包含一个或更多 Platform 要素，其中每个都指定了每个平台上插件支持的不同特性。可指定以下功能：

CanBeInsertOnBusses 确定效果器是否可用来控制和主导总线。通常这需要效果器支持环绕声音频配置。
CanBeInsertOnAuxBusses 确定效果器是否可用来控制和主导辅助总线。通常这需要效果器支持环绕声音频配置。注意，如果已经设置 CanBeInsertOnBusses，则效果器就已经可应用于辅助总线。
CanBeInsertOnAudioObjects 确定效果器是否可作为作用于音效的插入效果（必须支持单声道和立体声处理）。
CanBeRendered 确定效果器是否可用于离线渲染。

在 Wwise 中，您的插件只可用于指定的平台。

属性要素

每个效果器或源插件都能定义属性和引用。有关属性和引用的更多信息，请参照 Plug-in 属性和自定义属性 XML 描述。

内部对象

InnerTypes 部分定义了插件内您可以实例化和使用的可能内部对象类型。可以在 InnerTypes 部分定义多个 InnerType。每个 InnerType 必须具有唯一名称和插件 ID。InnerType 部分包含 Properties 部分，您可以使用定义插件属性的相同方式定义其属性。

当插件中需要多个对象实例时，Inner Types 非常实用。例如，当具有不定数量的 EQ Band 时，就可以为 EQ 插件定义 Inner Type Band 。每个 and 拥有相同的属性定义，但值不同。

<PluginModule>
    <EffectPlugin ...>
        <PluginInfo ...>
            ...
        </PluginInfo>
        <Properties>
            ...
        </Properties>
        <InnerTypes>
            <InnerType Name="Band" CompanyID="X" PluginID="Y">
                <Properties>
                    ...
                </Properties>
            </InnerType>
        </InnerTypes>
    </EffectPlugin>

Note: Inner Types 的属性不支持 RTPC。因此将不能使用 SupportRTPCType 属性和 AudioEnginePropertyID 元素。

Note: InnerTypes 只在源插件和效果器插件内受支持。

为了在插件代码中使用 Inner Type 实例（内部对象），您需要在插件初始化时通过框架提供的 AK::Wwise::IPluginObjectStore 指针来调用 AK::Wwise::IAudioPlugin::SetPluginObjectStore()。AK::Wwise::IPluginObjectStore 接口提供了用于创建和删除内部对象的函数。在创建对象时，必须使用插入和移除功能将它们存储在一个带名称的列表中。

例如，您可以创建类型为 Band 的内部对象，并将它存储在 BandList 中：

    // 创建新 band
    AK::Wwise::IPluginPropertySet* pBand = GetObjectStore()->CreateObject( L"Band" );

    // 在“BandList”中插入新 band（位于末尾）
    GetObjectStore()->InsertObject( L"BandList", (unsigned int)-1, pBand );

Note: 内部对象只能存储在一个列表中。

请参见以下主题：

在向对象库中添加内部对象时，Wwise 会自动创建相关的撤消机制，您无需亲自实现撤消系统。但为了正常地支持撤消事件，您只需在收到框架通知时更新用户接口即可。例如，在对 IPluginObjectStore 调用 InsertObject 后，请勿立即更新 UI，而应等待您的插件上调用通知 AK::Wwise::IAudioPlugin::NotifyInnerObjectAddedRemoved。此通知告诉您对象已添加到列表或者已从列表中移除。它可以来自用户的动作，也可以来自撤消机制。

AK::Wwise::IAudioPlugin::NotifyInnerObjectPropertyChanged 也可能对您有用，当内部对象中的属性值变化时，将调用此函数。

工程工作单元中的一致性由 Wwise 自动处理。但您必须对声音库中的内部数据和声音引擎数据实施序列化。须将 AK::Wwise::IAudioPlugin::GetPluginData 和 AK::Wwise::IAudioPlugin::GetBankParameters 中的内部对象进行序列化。

故障排除

如果您遇到任何问题，请参阅 Wwise 源插件和效果器插件故障排除指南。

此页面对您是否有帮助？

需要技术支持？

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

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

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

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

开始 Wwise 之旅

Wwise SDK 2017.2.10