|
Wwise SDK 2024.1.1
|
鉴于 2023.1 中的有些新增功能（参见 新增功能概述 2023.1 章节），在迁移到 Wwise 2023.1 之前有些重要事项需要注意。
WwiseConsole 现在参数总是与 CWD 相对
之前，WwiseConsole 的 convert-external-source 和 generate-soundbank 命令有时会将参数解析为相对于工程目录的路径。现在所有传给 WwiseConsole 的路径都是跟主机当前工作目录相对的。
更改了可执行文件的位置
现在将之前存放在 Authoring/x64/Release/bin/Tools 下的可执行文件存放到了与 Wwise.exe at Authoring/x64/Release/bin 相同的目录下。 若工程使用了 FilePackager 作为 SoundBank Post-Generation 步骤，则须更新 FilePackager.Console.exe 可执行文件的路径。
Low-Level I/O Hook 重大改进
为了提升高延迟设备（如 Web 应用程序）上流播放接口的效率，23.1 中对 Low-Level I/O Hook 接口做了大幅改进。同时，对接口进行了全面重构以将之前的改进整合到更为连贯的接口中。以下章节介绍了可能会给游戏构建带来较大影响的重大更改。
移除了 AK::StreamMgr::IAkIOHookBlocking 和 CAkDefaultIOHookBlocking
移除了阻塞型 I/O 挂钩示例。阻塞型 I/O 调用之前是在单独的线程中执行的。这样可以避免 I/O 调用的无序执行，但也给有些系统上的文件访问带来了不必要的延迟。若您的游戏使用了此示例，请将其替换为 CAkDefaultIOHookDeferred。API 是一样的。
合并了相关接口
将 AK::StreamMgr::IAkLowLevelIOHook、AK::StreamMgr::IAkIOHookDeferred 和 AK::StreamMgr::IAkIOHookDeferredBatch 接口合并为了 AK::StreamMgr::IAkLowLevelIOHook。之前，这些接口是分开的，为的是支持阻塞型变体。不过现在已不提供相应支持，也就没必要再做这种划分了。若 I/O 挂钩源自 IAkIOHookBlocking、IAkIOHookDeferred 或 IAkIOHookDeferredBatch，请将其替换为 IAkLowLevelIOHook 来实现缺失的函数。
将 AK::StreamMgr::IAkFileLocationResolver::Open() 函数替换为了 AK::StreamMgr::IAkLowLevelIOHook::BatchOpen()
若游戏已使用默认的 CAkDefaultIOHookDeferred 示例类，请忽略本节所述的内容，因为示例已经做了所有必要的更改。
倘若游戏采用了自己的 I/O 挂钩或文件位置解析器，那么最重要的改动就是对 AK::StreamMgr::IAkFileLocationResolver::Open() 进行了重命名并将其位置改到了特定于 I/O 设备的接口。在新的接口中，AK::StreamMgr::IAkLowLevelIOHook::BatchOpen() 函数会同时接收多个而非一个文件打开请求。它既可立即执行操作（同步），也可先分派再通知（异步）。跟 BatchRead() 函数一样，BatchOpen() 现在接收回调函数指针来发送操作结果通知。有关这一改进的详细信息，请参阅 延迟打开 章节。
If your game handles multiple I/O devices, be aware of the implementation of the new AK::StreamMgr::IAkFileLocationResolver::GetNextPreferredDevice function. 对于单设备游戏，其可能会返回 AK_NotImplemented。这样系统也能正常运行。不过，对于多设备游戏，必须使用 CAkDefaultLowLevelIODispatcher 示例或详细参阅 File Location Resolver（ File Location Resolver ） 章节。
AkDeviceSettings.uSchedulerTypeFlags Removed
弃用并移除了 I/O 设备创建当中所用的 AkDeviceSettings 的 uSchedulerTypeFlags 成员。同时移除了关联的 AK_SCHEDULER_BLOCKING 和 AK_SCHEDULER_DEFERRED_LINED_UP 常量。若代码引用了其中的符号，请删除与此相关的代码。
AkFileDesc 生命周期改进
现在必须通过 AK::StreamMgr::IAkLowLevelIOHook::BatchOpen() 函数来创建用于识别 Streaming Manager 所用文件的 AkFileDesc 结构，并通过 AK::StreamMgr::IAkLowLevelIOHook::Close() 函数来删除该结构。
移除了 AkFileDesc 的 "Custom" 成员
移除了 AkFileDesc::pCustomParam 和 AkFileDesc::uCustomParamSize 成员，因为其在 CAkDefaultIOHookDeferred 的子类中的用法不明确。若 I/O 挂钩需要随 AkFileDesc 一起保留附加数据，请从基础结构获取 I/O 挂钩。就像上节说的，I/O 挂钩现在会创建并销毁 AkFileDesc 结构。
对于源自 CAkDefaultIOHookDeferred 示例的 I/O 挂钩，子类可使用 AkFileDescType 类型定义同时获取 AkFileDesc 类型和中间子类（如有必要）。若对 AkFileDesc 进行扩展，还要覆盖 CAkDefaultIOHookDeferred::CreateDescriptor 函数来创建正确的类型。
移除了混音器插件
就像 重要迁移说明 2022.1 章节说的，Wwise 2023.1 中移除了混音器插件。
更新了自定义混音器插件
现在必须将混音器插件转换为效果器插件：
- 插件必须应用
IAkOutOfPlaceObjectPlugin接口。该接口替换了之前的IAkMixerEffectPlugin接口。 - 将之前放在
ConsumeInput函数中的代码移到Execute函数。 - 将插件 XML 文件中的 Attachables 节点替换为 MetadataPlugin 节点。MetadataPlugin 节点为插件类型元素。
 | 备注: in_objects.ppObjects[i]->arCustomMetadata 包含传给函数的元数据。这样可以有效替换被移除的 GetInputParam 函数。 |
AK Channel Router 插件迁移
AK Channel Router 插件已由混音器插件转换为效果器插件。该插件可在 Property Editor 的 Effects 选项卡中插入。效果器仅可插入到将 Bus Configuration 设为 Audio Objects 的总线上。
Audio Objects 总线配置有两个显著特性：
- 总线上已有的有些效果器可能与此总线配置不兼容。有关详细信息，请参阅结合 Audio Object 使用效果器。
- 这种总线配置不能应用于顶层总线。
在迁移时会移除所有 Ak Channel Router 混音器插件实例，但不会将其自动替换为 AK Channel Router 效果器插件。用户必须手动将 AK Channel Router 效果器添加到相应的总线。 新的元数据类型 Channel Router Settings 会替换 Ak Channel Router 混音器插件的现有 AttachableMixerInput。在迁移时会移除所有 AttachableMixerInput 实例并将其替换为新的元数据。
弃用了 Subversion 版本控制示例插件
现已弃用并会在未来 Wwise 版本中移除 Subversion 版本控制示例插件。
版本控制 – Silent Mode
现在无需用户界面就可执行版本控制操作。若启用 Silent Mode，在 WAAPI 请求与版本控制系统进行交互时便不会显示对话框。 为了应用这一改进，我们对 AK::Wwise::ISourceControlProgress 类（之前的 AK::Wwise::ISourceControlOperationProgress 类）做了调整。为此，更改或添加了以下方法：
- 将
ShowProgress()方法重命名为了BeginOperation() - 将
OperationCompleted()方法重命名为了EndOperation() - 添加了
IsSilent()方法 - 添加了
IsAutoCheckout()方法
WAAPI 默认值
对于以下 WAAPI 函数，autoAddToSourceControl 参数现在默认设为 true：
- ak.wwise.core.object.create
- ak.wwise.core.object.set
- ak.wwise.core.audio.import
- ak.wwise.core.audio.importTabDelimited
注意，由于问题 WG-61743，以下函数的行为在大部分情况下会像 autoAddToSourceControl 默认设为 true 一样：
对于以下 WAAPI 函数，bypassSave 参数现在默认设为 true：
WAAPI Command Identifier Changes
The following command identifiers have been renamed:
- WorkgroupAddWAV -> SourceControlAddWAV
- WorkgroupAddWWU -> SourceControlAddWWU
- WorkgroupCheckoutWAV -> SourceControlCheckoutWAV
- WorkgroupCheckoutWWU -> SourceControlCheckoutWWU
- WorkgroupCommitWAV -> SourceControlCommitWAV
- WorkgroupCommitWWU -> SourceControlCommitWWU
- WorkgroupDiffWAV -> SourceControlDiffWAV
- WorkgroupDiffWWU -> SourceControlDiffWWU
- WorkgroupRefreshIcons -> SourceControlRefreshIcons
- WorkgroupRevertWAV -> SourceControlRevertWAV
- WorkgroupRevertWWU -> SourceControlRevertWWU
- WorkgroupUpdateWAV -> SourceControlUpdateWAV
- WorkgroupUpdateWWU -> SourceControlUpdateWWU
Refer to Wwise 设计工具命令标识符 for more information.
(Spatial Audio) Revised Room and Portal Wet Path Signal Model
现在通过发声体上指定的衰减将湿声路径的 Attenuation、Occlusion、Obstruction、Transmission Loss 和 Diffraction 应用于 Emitter-Room Connection。"Room" Auxiliary Bus 上应用的衰减曲线不再起任何作用，需要移动至原始声音声音上处理。除非在工程中或通过 API 进行修改，否则 "Room" Auxiliary Bus 的输出始终为 0 dB。
现在会按照发声体来基于发声体和听者之间的路径计算湿声路径上的衍射。湿声路径衍射不能超过干声路径衍射。
现在会通过所有与发声体和听者之间射线相交的表面的最大 Transmission Loss 值将几何透射损失应用于湿声路径。Room 透射损失为从发声体到听者的所有潜在路径当中的最小值。单条路径的透射损失为该路径上所有 Room 的透射损失的最大值。
Room-Listener Connection 当中的射线现在仅用于空间化处理，不会对 Room-Listener Connection 的音量产生影响。因此，Voice Inspector 中不再予以显示。
对于选中 Enable Game-Defined Sends 复选框的发声体，现在会发送到其自身 Room 的总线以及所有与听者之间存在活跃路径的相邻 Room。若发声体和听者处在同一 Room 内，则发送到所有相邻 Room。
添加了 AkSpatialAudioInitSettings::uMaxEmitterRoomAuxSends 来限制每个发声体创建的相邻 Room 的 Emitter-Room Connection 数量。默认值为 0，表示不做限制。若设定了限值，则保留最为突出的发送（基于从发声体角度来说散布到相邻 Portal 的比例）。若将限值设为 1，则只发送到发声体所在 Room 以及发声体过渡到的 Room（在 Portal 中的时候）。
为 Apple 平台新增了基于 AVAudioEngine 的 Sink
Wwise 中的 System Audio Device 现在支持将 AVAudioEngine 用于系统的音频输出。这样可在声道配置方面提供一定的灵活性，并在 macOS 和 iOS/tvOS 平台之间发挥协同作用。
最终，为 Apple 平台添加了 AkPlatformInitSettings::eAudioAPI 。在设为默认值 AkAudioAPI_Default 时，会自动选择 AVAudioEngine 并用于提供相应支持的操作系统（macOS 10.15 或更高版本及 iOS/tvOS 13 或更高版本）。旧版操作系统上运行的 Wwise 安装包将继续使用 AudioUnit API（其仅提供基本功能）。
如需详细了解基于 AVAudioEngine 的 Sink 的新行为，请参阅 平台上的音频输出 章节。
另外，在 iOS/tvOS 上， AK::SoundEngine::GetPlatformInitSettings 会返回 Audio Session 的默认采样率而非固定的 48000 Hz。
最后，在 iOS/tvOS 上，更新了 AudioInputCallbackFunc 函数签名以确保音频缓冲区的常量性。
鉴于这一改进，应用程序现在必须链接 AVFoundation.framework。
AK::SoundEngine::Suspend 不再影响 AK::Comm 的状态
在有些平台上，之前使用 AK::SoundEngine::Suspend() 和 AK::SoundEngine::WakeupFromSuspend() 调用来自动暂停和唤醒 AK::Comm 模块并断开所连接的 Wwise Profiler。现在，客户端必须单独管理 AK::Comm 模块。如需了解如何针对支持的平台在应用程序生命周期事件中管理 AK::Comm 模块，请参阅 处理系统专用事件 章节。
HF Damping 返回值范围更新
将 AK::SpatialAudio::ReverbEstimation::EstimateHFDamping() 返回的 HF Damping 值的范围拓宽了一倍。现在为 -1 ~ 1。现在映射到此值的 RTPC 的取值范围为 -1 ~ 1。
在 SDK 中添加了新的版本控制方法
新的 ISourceControl::Connect() 和 ISourceControl::Disconnect() 方法支持通过 ak.wwise.core.sourceControl.setProvider WAAPI 函数登录版本控制系统。为了确保与此 Wwise 版本的兼容性，必须将这些方法添加到 ISourceControl 并重新构建相应插件。
若版本控制实现不支持连接，这些方法会返回 OperationResult_NotImplemented 。
在 WAQL 中使用 maxRadiusAttenuation 和 maxDurationSource
现在无法再在 WAQL 中使用 maxRadiusAttenuation 和 maxDurationSource 来直接引用对象本身（比如在使用 "select" 时）。对此，请分别使用新的访问器 maxRadiusAttenuationObject 和 maxDurationSourceObject。
音频文件导入过程中的错误和警告
在使用 ak.wwise.core.audio.import 时，在导入日志中发现警告或错误的情况下，不会再通过 WAAPI 报告错误。现在由调用来返回导入日志。并且，应对其进行解析来检测导入错误和警告。