menu
版本
2017.1.9.6501
2024.1.4.8780
2023.1.12.8706
2022.1.18.8567
2021.1.14.8108
2019.2.15.7667
2019.1.11.7296
2018.1.11.6987
2017.2.10.6745
2017.1.9.6501
2016.2.6.6153
2015.1.9.5624
2024.1.4.8780
2023.1.12.8706
2022.1.18.8567
2021.1.14.8108
2019.2.15.7667
2019.1.11.7296
2018.1.11.6987
2017.2.10.6745
2017.1.9.6501
2016.2.6.6153
2015.1.9.5624
Wwise 的开放架构支持三种插件,它们分别是用于生成声音的源插件、用于增强声音的效果器插件和支持在 Wwise 中使用版本控制软件的版本控制插件。
前两种插件使用了 XML 插件描述文件,可以让您快速更改包括插件默认属性值在内的一些设置,而无需重新编译代码。Wwise 插件 DLL 可以包含多个插件,相关 XML 文件中必须对每个插件进行描述。
每个 Wwise 插件 DLL 的 XML 描述文件具有与 DLL 相同的名称,而扩展名可以不同。例如,如果您的 DLL 命名为“MyPlugin.dll”,那么插件描述文件必须命名为“MyPlugin.xml”。
XML 描述文件包含有关 Wwise 插件的多方面信息,包括:
以下是一个简单插件 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 version="1.0" encoding="UTF-8"?> <!-- Copyright (C) 2006 Audiokinetic Inc. -->
任何 XML 文件的第一行都是定义 XML 版本和编码方式。在本例中,XML 版本是 1.0,编码方式是 UTF-8
。任何 Wwise 插件描述文件的第一行应该总是与此完全一致。第二行是 XML 注释,在本例中是版权声明。您可以在 XML 文件的所需位置添加注释。
<PluginModule> ... </PluginModule>
本文档中的主要 XML 元素命名为 PluginModule
,包含此文件中定义的各种插件的全部信息。
<EffectPlugin Name="Wwise Parametric EQ" CompanyID="0" PluginID="105" SupportsIsSendModeEffect="false" EngineDllName="EQ"> ... </EffectPlugin>
EffectPlugin
元素是定义单个效果器插件的主要元素,而 SourcePlugin
是源插件的元素名称。
这些元素包含三个必须属性::
名称
(必需):此字符串指定了插件在 Wwise 中显示的名称。 CompanyID
(必需):此字符串必须为正整数,遵守以下值域范围: PluginID
(必需):此字符串必须是位于 0-65535 范围内的一个正整数。每个 PluginID 对于指定的 CompanyID 必须唯一。 SupportsIsSendModeEffect
(可选):(仅限于效果器插件)通过在初始化期间查询 AK::IAkEffectPluginContext::IsSendModeEffect() 获得,此布尔值指示插件是否支持发送模式。当 IsSendModeEffect() 返回 true,插件不应输出干声信号,而且应忽略干声电平属性。 EngineDllName
(可选):此字符串值指示在游戏运行时要加载的动态库。在默认情况下,它与 XML 使用相同的名称。在商用游戏引擎(例如 Unity 和 Unreal 4)中,必须为您的插件提供 DLL/so 文件。注意,此 DLL 不是 XML 相对应的 DLL 文件,其中包含所有属性页面 UI,您不可将它放置到游戏中。 例如,如果您正在开发仅供内部使用的两个源插件和一个效果器插件,那么可以选择介于 64 与 255 之间的任意一个数作为 CompanyID,介于 0 与 65535 之间的任何三个数作为 PluginID。三个数字不需要连续。
warning
|
Caution: 如果您以 Audiokinetic 提供的一个插件示例(示例插件 )为基础开发您的插件,不要忘记把 CompanyID 和 PluginID 更改为适当值。如果您有一个指定的官方 CompanyID,则使用它;如果没有,可以使用介于 64 与 255 之间的一个数。请确保该 CompanyID 的 PluginID 不重复。 |
如果同一个 CompanyID 具有两个或两个以上的相同 PluginID,Wwise 将在启动时显示错误消息。如果发生这种情况,则需更改新插件的 ID。
warning
|
Caution: 一定不要更改现有插件的 CompanyID 或 PluginID。否则使用该插件的工程将无法识别插件。CompanyID 和 PluginID 在每个源插件或效果器插件实例中始终保持一致,在加载文件时它们将用于重新创建正确的插件。 |
对于用于标识插件的函数,CompanyID 和 PluginID 属性对应于传递给它们的参数:
AkCreatePlugin()
(请参阅 导出函数 )AK::SoundEngine::RegisterPlugin()
info
|
Note: 如果 DLL 中实现了多个插件,则 XML 文件将包含多个 EffectPlugin 或 SourcePlugin 条目。 |
<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
确定效果器是否可用于离线渲染。CanBeInsertForFeedback
确定效果器是否可用于振动效果。在 Wwise 中,您的插件只可用于指定的平台。
每个效果器或源插件都能定义属性和引用。有关属性和引用的更多信息,请参照 Plug-in 属性和自定义属性 XML 描述。
InnerTypes
部分定义了插件内您可以实例化和使用的可能内部对象类型。可以在 InnerTypes
部分定义多个 InnerType。每个
InnerType
必须具有唯一名称和插件 ID。InnerType
部分包含 Properties
部分,您可以使用定义插件属性的相同方式定义其属性。
当插件中需要多个对象实例时,Inner Types 非常实用。例如,当具有不定数量的 EQ Band 时,就可以为 EQ 插件定义 Inner Type 带。每个
and 拥有相同的属性定义,但值不同。
<PluginModule> <EffectPlugin ...> <PluginInfo ...> ... </PluginInfo> <Properties> ... </Properties> <InnerTypes> <InnerType Name="Band" CompanyID="X" PluginID="Y"> <Properties> ... </Properties> </InnerType> </InnerTypes> </EffectPlugin>
info
|
Note: Inner Types 的属性不支持 RTPC。因此将不能使用 SupportRTPCType 属性和 AudioEnginePropertyID 元素。 |
info
|
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 );
info
|
Note: 内部对象只能存储在一个列表中。 |
请参见以下主题:
在向对象库中添加内部对象时,Wwise 会自动创建相关的撤消机制,您无需亲自实现撤消系统。但为了正常地支持撤消事件,您只需在收到框架通知时更新用户接口即可。例如,在对 IPluginObjectStore
调用 InsertObject
后,请勿立即更新 UI,而应等待您的插件上调用通知 AK::Wwise::IAudioPlugin::NotifyInnerObjectAddedRemoved。此通知告诉您对象已添加到列表或者已从列表中移除。它可以来自用户的动作,也可以来自撤消机制。
AK::Wwise::IAudioPlugin::NotifyInnerObjectPropertyChanged
也可能对您有用,当内部对象中的属性值变化时,将调用此函数。
工程工作单元中的一致性由 Wwise 自动处理。但您必须对声音库中的内部数据和声音引擎数据实施序列化。须将 AK::Wwise::IAudioPlugin::GetPluginData
和 AK::Wwise::IAudioPlugin::GetBankParameters
中的内部对象进行序列化。
如果您遇到任何问题,请参阅 Wwise 源插件和效果器插件故障排除指南 。