目录

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

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

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

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

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

Note: 如果 DLL 中实现了多个插件,则 XML 文件将包含多个 EffectPluginSourcePlugin 条目。

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::GetPluginDataAK::Wwise::IAudioPlugin::GetBankParameters 中的内部对象进行序列化。

故障排除

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