版本
menu_open
Wwise SDK 2019.1.11
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>
<EffectPlugin Name="Wwise Parametric EQ" CompanyID="0" PluginID="105" EngineDllName="EQ">
<PluginInfo>
<PlatformSupport>
<Platform Name="Windows">
<CanBeInsertOnBusses>true</CanBeInsertOnBusses>
<CanBeInsertOnAudioObjects>true</CanBeInsertOnAudioObjects>
<CanBeRendered>true</CanBeRendered>
</Platform>
<Platform Name="Mac">
<CanBeInsertOnBusses>true</CanBeInsertOnBusses>
<CanBeInsertOnAudioObjects>true</CanBeInsertOnAudioObjects>
<CanBeRendered>true</CanBeRendered>
</Platform>
<Platform Name="iOS">
<CanBeInsertOnBusses>true</CanBeInsertOnBusses>
<CanBeInsertOnAudioObjects>true</CanBeInsertOnAudioObjects>
<CanBeRendered>true</CanBeRendered>
</Platform>
<Platform Name="XboxOne">
<CanBeInsertOnBusses>true</CanBeInsertOnBusses>
<CanBeInsertOnAudioObjects>true</CanBeInsertOnAudioObjects>
<CanBeRendered>true</CanBeRendered>
</Platform>
<Platform Name="PS4">
<CanBeInsertOnBusses>true</CanBeInsertOnBusses>
<CanBeInsertOnAudioObjects>true</CanBeInsertOnAudioObjects>
<CanBeRendered>true</CanBeRendered>
</Platform>
</PlatformSupport>
</PluginInfo>
<Properties>
<Property Name="OnOffBand1" Type="bool" SupportRTPCType="Exclusive" ForceRTPCCurveSegmentShape="Constant" DisplayName="Band 1 Enable">
<DefaultValue>true</DefaultValue>
<AudioEnginePropertyID>4</AudioEnginePropertyID>
</Property>
<Property Name="FilterTypeBand1" Type="int32" SupportRTPCType="Exclusive" ForceRTPCCurveSegmentShape="Constant" DisplayName="Band 1 Filter Type">
<DefaultValue>5</DefaultValue>
<AudioEnginePropertyID>10</AudioEnginePropertyID>
<Restrictions>
<ValueRestriction>
<Enumeration Type="int32">
<Value DisplayName="Low Pass">0</Value>
<Value DisplayName="High Pass">1</Value>
<Value DisplayName="Band Pass">2</Value>
<Value DisplayName="Notch">3</Value>
<Value DisplayName="Low Shelf">4</Value>
<Value DisplayName="High Shelf">5</Value>
<Value DisplayName="Peaking">6</Value>
</Enumeration>
</ValueRestriction>
</Restrictions>
<Dependencies>
<PropertyDependency Name="OnOffBand1" Action="Enable">
<Condition>
<Enumeration Type="bool">
<Value>1</Value>
</Enumeration>
</Condition>
</PropertyDependency>
</Dependencies>
</Property>
<Property Name="GainBand1" Type="Real32" SupportRTPCType="Exclusive" DataMeaning="Decibels" DisplayName="Band 1 Gain">
<UserInterface Step="0.5" Fine="0.1" Decimals="1" />
<DefaultValue>0</DefaultValue>
<AudioEnginePropertyID>1</AudioEnginePropertyID>
<Restrictions>
<ValueRestriction>
<Range Type="Real32">
<Min>-24</Min>
<Max>24</Max>
</Range>
</ValueRestriction>
</Restrictions>
<Dependencies>
<PropertyDependency Name="OnOffBand1" Action="Enable">
<Condition>
<Enumeration Type="bool">
<Value>1</Value>
</Enumeration>
</Condition>
</PropertyDependency>
</Dependencies>
</Property>
</Properties>
</EffectPlugin>
</PluginModule>

让我们详细地考察 XML 文件的各个部分。

XML 描述文件头

让我们考察此 XML 文件头的组成部分并详细地讨论。

<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright (C) 2006 Audiokinetic Inc. -->

任何 XML 文件的第一行都是定义 XML 版本和编码方式。在本例中，XML 版本是 1.0，编码方式是 UTF-8 。任何 Wwise 插件描述文件的第一行应该总是与此完全一致。第二行是 XML 注释，在本例中是版权声明。您可以在 XML 文件的所需位置添加注释。

PluginModule元素

<PluginModule>
...
</PluginModule>

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

EffectPlugin和SourcePlugin元素

<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。三个数字不需要连续。

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

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

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

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

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

PluginInfo 元素

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

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

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

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

另外，也可选择添加 Any 平台，而无需列出所有支持的平台。不过，这样的话会在 Wwise 中将此插件报告为适用于所有平台。若该插件没有提供匹配的运行时库，则用户只有在对应平台上设置端口时才会注意到。

<PlatformSupport>
<Platform Name="Any">
<CanBeInsertOnBusses>true</CanBeInsertOnBusses>
<CanBeInsertOnAudioObjects>true</CanBeInsertOnAudioObjects>
<CanBeRendered>true</CanBeRendered>
</Platform>
</PlatformSupport>

属性要素

每个效果器或源插件都能定义属性和引用。有关属性和引用的更多信息，请参照 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>
备注: Inner Types 的属性不支持 RTPC。因此将不能使用 SupportRTPCType 属性和 AudioEnginePropertyID 元素。
备注: 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 );
备注: 内部对象只能存储在一个列表中。

请参见以下主题：

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

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

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

故障排除

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

AK::SpeakerVolumes::Vector::Max
AkForceInline void Max(AkReal32 *in_pVolumesDst, const AkReal32 *in_pVolumesSrc, AkUInt32 in_uNumChannels)
Get max for all elements of two volume vectors, independently.
Definition: AkSpeakerVolumes.h:127
AK::SpeakerVolumes::Vector::Min
AkForceInline void Min(AkReal32 *in_pVolumesDst, const AkReal32 *in_pVolumesSrc, AkUInt32 in_uNumChannels)
Get min for all elements of two volume vectors, independently.
Definition: AkSpeakerVolumes.h:137

此页面对您是否有帮助？

需要技术支持？

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

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

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

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

开始 Wwise 之旅