|
Wwise SDK 2024.1.1
|
由于部分 2021.1 新增功能 的原因，您在迁移到 Wwise 2021.1 时需要注意以下事项。
Spatial Audio
Wwise Spatial Audio 现在在 API 和设计工具中统一使用透射损失来定义声音透过 Room 和几何构造传播时的声笼系数。相应地，我们将 AkRoomParams::WallOcclusion 重命名为了 AkRoomParams::TransmissionLoss，并将 AkAcousticSurface::occlusion 重命名为了 AkAcousticSurface::transmissionLoss 。
为了简化声音传播物理模型的设计和实现，我们将所有用来应用衍射和透射处理的选项合并成了一个选项。
- 在 Positioning 选项卡中，将 Enable Diffraction 重命名为了 Enable Diffraction and Transmission。
- 移除了初始化设置 bEnableTransmission；对于在设计工具中选中了 Enable Diffraction and Transmission 的声音，始终启用透射模拟。若声音透射在游戏中并无多大用处，则可将所有 Room 和几何构造的默认透射损失系数设为 1.0，同时使用默认的声笼曲线，来确保完全听不到由此传播的声音。
另外，为了简化 Spatial Audio 的设置，我们还对 AkSpatialAudioInitSettings 的以下字段进行了相应的更改：
- 移除了
AkDiffractionFlags，改为使用以下替代设置：- 始终将
DiffractionFlags_UseBuiltInParam设为 true。现在无需进行显式配置便可使用 Diffraction 内置参数。 - 将
DiffractionFlags_UseObstruction替换为了布尔值 AkSpatialAudioInitSettings::bUseObstruction，但逻辑保持不变。 - 将
DiffractionFlags_CalcEmitterVirtualPosition替换为了布尔值AkSpatialAudioInitSettings::bCalcEmitterVirtualPosition，但逻辑保持不变。
- 始终将
- 将
bEnableDirectPathDiffraction重命名为了 AkSpatialAudioInitSettings::bEnableGeometricDiffractionAndTransmission，以便更加精确地描述该选项。 - 移除了
fDiffractionShadowAttenFactor和fDiffractionShadowDegrees。这些选项使用起来比较麻烦，不建议用于基于物理模型的声音渲染。
3D Audio
在 Wwise 2019.2 及先前版本中，内置 System Audio Device 最高支持 7.1 声道的音频。要想突破该限制来访问某些平台上可用的 3D Audio 输出功能，需要应用各种各样的插件。
在 Wwise 2021.1 中，我们将这些插件整合到了 System Audio Device 中。结合新增的 Audio Objects Bus Configuration，可大大简化 3D Audio 输出的管理。
以下章节介绍了如何迁移使用现已弃用的 3D Audio 插件的 Wwise 工程以便运用 2021.1 中的各项改进功能。
插件等效功能
特定于平台的文档中对旧版插件进行了说明，同时阐释了在 Wwise 2021.1 中的哪些位置可以找到与之等效的功能。
迁移
使用单个输出
对于使用双输出策略拆分 Spatial 和 Passthrough 混音的 Wwise 工程，现在需要改用单个 System Audio Device 来通过单条 Audio Object 播放流生成两种混音。
发送 Audio Object
需移除 3D Audio 混音器插件实例，改为使用 Audio Objects Bus Configuration，以便将 Audio Object 发送到顶层总线和 System Audio Device。要想在 3D Audio 模式下操作时自动从 System Audio Device 继承 Audio Object 配置，建议使用 Same as parent Bus Configuration。
所有非 3D 单声道或立体声播放流都将由 System Audio Device 自动传给 Passthrough Mix。通过在 "Wwise System Output Settings " Metadata 中将 Mix Behavior 设为 Mix To Passthrough，还可强制将其他类型的对象发送到 Passthrough Mix。
自动配置
之前需要使用游戏端逻辑来检测 3D 音频，并在 Headphone 和 Surround 模式之间正确切换：比如，绑定 Bypass all 和 Passthrough objects 这两项对象声像摆位器设置。
现在将由 System Audio Device 执行该检测，并依据是否激活了 3D Audio 来自动启用 Audio Object 或 Passthrough Mix。在目标为 Headphones 或 Surround 时，还可针对 Main Mix 选用单独的配置。而且，任何总线都可使用 Same as main mix 或 Same as passthrough mix Bus Configuration 来从 Main Mix 或 Passthrough Mix 继承配置。
实用示例
在 Wwise SDK Integration Demo 中，添加了新的页面来展示如何完成前面章节中所述的目标设置。
详情参见 Positioning Demo > 3D Audio Objects and Spatialized Bed。
关于终止支持原有 Wwise 命令行接口 (WwiseCLI) 的声明
We announce that Wwise 2021.1 will be the last major version to support the legacy Wwise command line interface, known as WwiseCLI.exe. 2021.1 的小版本仍提供相应支持，但未来大版本将不再予以涵盖。有关 Wwise Console（替代原有 Wwise 命令行接口）的详细信息，请参阅 使用命令行 章节。
关于终止支持 SoundFrame 的声明
在此声明，Wwise 2021.1 将是最后一个支持 SoundFrame 的大版本。2021.1 的小版本仍提供相应支持，但未来大版本将不再予以涵盖。Refer to 使用 Wwise Authoring API（WAAPI） to learn more about the Wwise Authoring API (WAAPI), which replaces the SoundFrame.
从 Wwise 2013.1 之前的版本迁移
现在不再支持直接从 2013.1 之前的版本迁移 Wwise 工程。如有必要，可先迁移到 2019.2，再迁移到 2021.1。
影响向后兼容性的 WAAPI 改进
之前在返回选项中包含未知属性的情况下调用 ak.wwise.core.object.get 不会给出任何结果。现在会生成 WAAPI 错误。注意，在使用未在 XML 中定义的属性时会出现此错误。在将已知属性用于不支持的对象时并不会生成错误。
现在需要 C++14 编译器
Wwise SDK 头文件和源文件现在需要 C++14 来进行正常编译。如需查看支持的编译器列表，请参阅 平台要求 章节。
Height Spread
Spread 和 Focus 曲线现在依据发声体和听者之间的实际距离取值，而之前都是依据听者顶向矢量所定义平面上投射的听者-发声体矢量的距离取值。
先前行为一般通过增大听者上方或下方所传递 3D 声音的散布，来帮助实现 2D 扬声器配置（5.1、7.1 等）下声像摆位的平滑过渡。不过遗憾的是，该行为不太适合在 3D 配置（如双耳立体声或 7.1.4）下实施声像摆位。比如，在发声体从听者身边掠过时，其 3D 嗖嗖声会突然变成全指向声音。
为了能够依据实际距离来估算 Spread 值，同时确保在 2D 配置下实施声像摆位时平滑地过渡，我们新增了一项名为 Height Spread 的属性。若在 2D 配置下实施声像摆位，则根据高度角自动计算最小散布值；若在 7.1.4 之类的 3D 配置（半球空间）下实施声像摆位，则直接根据负高度角计算最小散布值。
该属性默认设为 true，可在 Attenuation Editor 中找到。您可以通过取消选中该复选框来禁用相应的行为。若没有为声音应用任何衰减，则需专门创建 Attenuation ShareSet，并设置平缓的 Output Bus Volume 曲线。
重命名私密平台
将新增的私密平台重命名为了 PlayStation 5 和 Xbox Series X。若 Wwise 工程中已有所述平台，则将执行迁移步骤以由之前的代号重命名为 PS5 和 XboxSeriesX。若将平台的定义（如名称、GeneratedSoundBanks 和 ExternalSourceFilePaths）设为了默认值，也会根据适用情况对其进行重命名。
PlayStation 5 平台之前的代号为 Pellegrino，现在改为了 PS5。应特别注意以下几点：
- AK_PELLEGRINO 已重命名为
AK_PS5。 - AK::IAkPellegrinoContext 已重命名为
AK::IAkPS5Context。
对以下 Microsoft Game Core 平台进行了重命名：
- Xbox One Game Core 平台之前的代号为 GX，现在改为了 XboxOneGC。
- Xbox Series X|S 平台之前的代号为 Chinook，现在改为了 XboxSeriesX。
- Xbox 系列主机之间共用的 Microsoft Game Core 软件元素现在称为 XboxGC。
- Windows Game Core 平台之前的代号为 GDX，现在改为了 WinGC。
应特别注意以下几点：
- AK_CHINOOK 已重命名为
AK_XBOXSERIESX。 AK_XBOXONEGC现在定义 Xbox One Game Core。- AK::IAkGXContext 已重命名为
AK::IAkXboxGCContext。
XAudio2 和 DirectSound 的支持
Microsoft 平台现在仅支持 WASAPI。2021.1 停止了对 XAudio2 和 DirectSound 的支持。
移除了 AkAudioAPIWindows。 针对 Windows 移除了 AkPlatformInitSettings::eAudioAPI。
- 移除了 AkAudioAPIXboxOne 和 AkAudioAPIGX。
针对 XboxOne 和 XboxOneGC 移除了 AkPlatformInitSettings::eAudioAPI。
移除了 AkAudioAPIGX。 针对 XboxGC（之前称为 GX）移除了 AkPlatformInitSettings::eAudioAPI。
Memory Manager 改进
Falign 和 ReallocAligned
移除了 AK::MemoryMgr::Falign 和 AK::MemoryMgr::dFalign。对于通过 AK::MemoryMgr::Malign 或 dMalign 分配的内存，现在可使用 AK::MemoryMgr::Free 或 dFree 来释放，或者使用 AK::MemoryMgr::ReallocAligned 或 dReallocAligned 来重新分配。
Memory Manager 调试
- 移除了 AkMemDebugCheckForOverwrite，改为使用 AkMemSettings::uMemoryDebugLevel，来检查覆写 (overwrite) 和内存 stomp。
- 为便于调试提供了新的内存函数：AkCrtAllocator* 和 AkStompAllocator*。
插件内存分配器
IAkPluginMemAlloc::Malloc和IAkPluginMemAlloc::Malign现在使用文件名称和行号来追踪内存分配。注意，该操作由AK_PLUGIN_ALLOC和AK_PLUGIN_ALLOC_ALIGN宏自动处理。建议在适用情况下使用这些宏。- 添加了
AK_PLUGIN_REALLOC和AK_PLUGIN_REALLOC_ALIGN，来分别调用IAkPluginMemAlloc::Realloc和IAkPluginMemAlloc::ReallocAligned。 - 移除了
IAkPluginMemAlloc:dMalloc和IAkPluginMemAlloc::dMalign。现在依据 AkMemSettings::uMemoryDebugLevel 自动调用这些函数的调试版本。
MIDI API 改进
对 MIDI API 函数进行了增强。其中包括：
- AK::SoundEngine::PostMIDIOnEvent 采用与 PostEvent 更为类似的参数：
- 返回播放 ID
- 指定可选播放 ID（使用现有 ID）
- 指定回调函数（带有 Flag 和 Cookie）
- AkMIDIPost 中现在既可指定相对偏置（跟之前一样），也可指定绝对偏置。您可以通过 PostMIDIOnEvent 的新参数来加以指定。
- 新的 AkMIDIEvent 类型：AK_MIDI_EVENT_TYPE_WWISE_CMD。藉此，可提供以下 Wwise 专用 MIDI Event：
- AK_MIDI_WWISE_CMD_PLAY
- AK_MIDI_WWISE_CMD_STOP
- AK_MIDI_WWISE_CMD_PAUSE
- AK_MIDI_WWISE_CMD_RESUME
- AK_MIDI_WWISE_CMD_SEEK_MS
- AK_MIDI_WWISE_CMD_SEEK_SAMPLES
- 可将返回的播放 ID 用于现有播放 ID 函数（如 ExecuteActionOnPlayingID）。
为反映这一 API 改进，我们对 IAkGlobalPluginContext::PostMIDIOnEventSync 和 IAkGlobalPluginContext::StopMIDIOnEventSync 进行了更新。
其他 API 改进
移除了一些无用的平台特定对齐定义：
- AK_ALIGN
- AK_ALIGN_DMA
- AK_ALIGN_FASTDMA
- AK_ALIGN_SIZE_FOR_DMA
- AK_OS_STRUCT_ALIGNED
- AK_64B_OS_STRUCT_ALIGNED
- AK_ALIGN_ACM
AK/SoundEngine/Platforms/Android/AkAndroidSoundEngine.h:
- 移除了无用的 AkPlatformInitSettings::uChannelMask。
AK/SoundEngine/Common/IAkPlugin.h:
- 将 IAkEffectPluginContext::GetNodeID()、IAkSourcePluginContext::GetNodeID() 和 IAkMixerPluginContext::GetBusID() 替换为了
IAkPluginContextBase::GetAudioNodeID()。 - 移除了 IAkMixerInputContext::GetAudioNodeID。
- 将 IAkGlobalPluginContext::MixNinNChannels、Mix1inNChannels、MixChannel 移到了以下插件服务中：
IAkPluginServiceMixer（PluginServiceType_Mixer类型的IAkPluginService）。
AK/SoundEngine/Common/AkSpeakerConfig.h: AK/SoundEngine/Common/AkCommonDefs.h:
- 移除了 AkChannelConfig::IsChannelConfigSupported()。
- 移除了 AkAudioFormat::IsChannelConfigSupported。
AK/Wwise/Utilities.h:
- 弃用了 AK::Wwise::IWriteData::WritePascalString，改为使用 AK::Wwise::IWriteData::WriteUtf16String。
Wwise 设计工具插件 API 改进
Wwise 2021.1 将使用全新的 Wwise 设计工具插件 API。改进后的 API 可有效解决之前的一些问题，并实现更多的 Wwise 设计工具功能（比如区分前端和向后兼容）。 同时，也大大减少了对平台和工具集专用功能的依赖。 新的 API 可在 <Wwise>/SDK/include/AK/Wwise/Plugin 下找到。
专门的迁移指南中简要介绍了如何将插件迁移到新的 API （参见 Migrating a pre-2021.1 Authoring Plug-in 章节）。
 | 备注: 新的 C++ API 需要兼容 C++17 的编译器。 |
为便于过渡，Wwise 2021.1 中仍在相同的位置 (<Wwise>/SDK/include/AK/Wwise) 提供之前的原有 API，并且 Wwise 2021.1 依然支持使用其构建的插件。 不过，现在会标记为__原有__ API。未来的 Wwise 版本中将__不再__予以更新。 建议所有插件开发者将其插件迁移到这一新的 API。
声音引擎插件 API（如 <Wwise>/SDK/AK/SoundEngine/Common/IAkPlugin.h）依然通用，__并不会__被视为原有 API。新的 API 仅针对 Wwise 插件的设计工具端。 有关更多详细信息，请参阅 插件概述 章节。
Wwise 2021.1 对原有 API 还做了如下改进：
- 更改了
AK::Wwise::IAudioPlugin::NotifyMonitorData的签名，以便支持新的时间戳参数（秒）。您可以结合使用新的 Meter History 功能来随时实施电平测量。 - 移除了函数
AK::Wwise::IWriteData::WriteUtf16String和AK::Wwise::IWriteData::WritePascalString（已在 Wwise 2019.2 中弃用）。 在使用 Wwise 设计工具插件 API 进行交互时，UTF-8 现在专门用于数据字符串。 注意，在新的 API 中，我们将路径字符串参数由LPCWSTR迁移到了通用的AkOSChar缓冲区。
Removed iZotope Trash Box Modeler's boxmodel.wav
已移除 iZotope Trash Box Modeler 插件不再需要的外部文件 boxmodel.wav。