版本

menu_open
Wwise SDK 2023.1.2
创建音频设备 (Sink) 插件

音频设备插件接口实现

音频设备插件(Audio Device plug-in)是音频处理链的终端。自然音频设备是指操作系统原生支持的声音系统。倘若附加硬件或驱动程序允许,还可以有更多输出终端形式。Sink 插件的作用是将最终混音采样转码为兼容格式并传输至设备。

声音引擎组件

在声音引擎端编写音频设备插件的过程包括实现 AK::IAkSinkPlugin 接口。本节只介绍此接口专用的函数。请参阅 创建声音引擎插件 了解与其他插件类型(AK::IAkPlugin 接口)共享的接口组件的信息。另请参阅与所述 AkSink 插件相关的示例代码( 示例 )。

音频设备始终通过其所用插件 (Audio Device ShareSet) 和设备 ID 指定。此设备 ID 对 Wwise 声音引擎来说并无意义,只是为了方便插件实现类区分多个相同类型的设备。该 ID 由游戏通过 AK::SoundEngine::InitAK::SoundEngine::AddOutput 中使用的 AkOutputSettings::idDevice 参数传递。比如,对于要访问 Windows 音频设备的音频设备插件,可能会识别出某台电脑上的多个 Windows 设备。

若所用设备无需与多个设备区分,则可忽略该参数。若需要区分,则还须支持“默认设备”概念(在 idDevice 参数为 0 时选择的设备)。插件参数决定在接收到 0 值时是选择第一个可用设备还是特定设备。

Sink 插件可以注册一个附加静态函数来实现对可用音频设备的枚举。此函数的作用是列出可能的设备,以便用户设计工具中选择,并允许通过调用 AK::SoundEngine::GetDeviceList 来在运行时枚举设备。此函数是可选的。若不使用该函数,则插件将在必要时初始化为默认输出。在必要时,需在插件参数创建函数之后提供该附加静态函数。如需进一步了解要为插件创建提供的其他静态函数,请参阅 创建声音引擎插件

下面以虚构的 Sink 插件 MyPlugin 为例展示了如何实现设备枚举。注意,MyPlugin 命名空间中的函数和类皆为实际插件实现所对应的占位符。

Wwise 调用插件设备枚举函数时,将采用所要列出的最大设备数以及 AkDeviceDescription 的预分配数组。设备名称的最大长度为 AK_MAX_PATH (256 个字符)。您必须修改计数 (io_maxNumDevices),使其正确反映列出的设备描述数量。即便所提供的设备描述数组指针为 NULL,也要修改计数来反映所要填写的设备描述数量。这样调用方才能为 out_deviceDescriptions 分配相应数量的内存。

// ...
AKRESULT GetMyPluginDeviceList(AkUInt32& io_maxNumDevices, AkDeviceDescription* out_deviceDescriptions)
{
// For example, fetch the available devices
const AkUInt32 deviceCount = MyPlugin::GetNumberOfDevices();
const MyPlugin::Device* devices = MyPlugin::GetDevices();
// 处理设备计数请求:
// 若 out_deviceDescriptions 为 NULL,则 io_maxNumDevices 应设为设备计数
// 这样调用方才能确定要预留多少内存。
if (out_deviceDescriptions == NULL)
{
io_maxNumDevices = deviceCount;
return AK_Success;
}
// 否则,填写 out_deviceDescriptions
// until all available devices are filled (i == deviceCount)
// or the end of the array is reached (i == io_maxNumDevices)
int i = 0;
for (; i < deviceCount && i < io_maxNumDevices; ++i)
{
AKPLATFORM::SafeStrCpy(out_deviceDescriptions[i].deviceName, device[i]->deviceName, AK_MAX_PATH);
out_deviceDescriptions[i].idDevice = devices[i].idDevice;
out_deviceDescriptions[i].deviceStateMask = devices[i].deviceStateMask;
out_deviceDescriptions[i].isDefaultDevice = devices[i].isDefaultDevice;
}
// 设置数组中写入的设备数
io_maxNumDevices = i;
return AK_Success;
}
// 静态初始化器对象将插件自动注册到声音引擎中。
AK::PluginRegistration MyPluginRegistration(AkPluginTypeEffect, AKCOMPANYID_MYCOMPANY, EFFECTID_MYPLUGIN, CreateMyPlugin, CreateMyPluginParams, GetMyPluginDeviceList);
备注: 为了能够针对支持的所有平台实现设备枚举,并在运行时通过 AK::SoundEngine::GetDeviceList 调用相应的函数,此声音引擎实现替换了之前设计工具专用插件对应的 AkGetSinkPluginDevices 函数。
备注: 此函数将针对所有平台进行编译。在处理特定于平台的设备枚举时,需使用相应的宏(如 AK_WINAK_LINUX ),并针对没有定义实现的平台返回 AK_NotImplemented

适用于音频设备插件的设计工具 DLL

Sink 插件跟其他插件一样需要对应的设计工具 DLL。有关插件通用 Wwise 设计工具组件的基本设置,请参阅“ 设计工具插件库格式 ”。

备注: AkGetSinkPluginDevices 现已弃用。有关如何实现设备枚举的信息,请参见上述 声音引擎组件 部分。

测试您的音频设备插件

在实现了插件的 Wwise 部件( 编写音频插件的设计工具部分 )和声音引擎部件后,应该对您的新插件进行测试。以下是测试的步骤。

  • 在您的 Wwise 工程中,根据新插件创建 Audio Device ShereSet(音频设备共享集)。为 ShareSet 指定名称,保证不重名。
  • 生成 SoundBank。
  • 确保已在游戏代码中注册插件。请参阅 声音引擎插件概述
  • 在声音引擎初始化参数中指定要使用的音频设备ID。AkOutputSettings 中的 ID 为工程中 Audio Device ShareSet 名称的哈希值(由 AK::SoundEngine::GetIDFromString 给出)。

例如:

AkInitSettings initSettings;
AkPlatformInitSettings platformInitSettings;
initSettings.settingsMainOutput.audioDeviceShareset = AK::SoundEngine::GetIDFromString("YourNewAudioDeviceSharesetNameHere");
AK::SoundEngine::Init( &initSettings, &platformInitSettings );

另外,也可结合 Audio Device 插件使用 AK::SoundEngine::AddOutput。

AkOutputSettings outputSettings("YourNewAudioDeviceSharesetNameHere", 0 /*Default device*/)'
AK::SoundEngine::AddOutput(outputSettings);

您可以使用 AK::SoungEngine::GetDeviceList 来针对所用插件测试设备枚举。

const int maxNbDevices = 20;
AkDeviceDescription devices[maxNbDevices];
AkUInt32 deviceCount = maxNbDevices;
AK::SoundEngine::GetIDFromString("YourNewAudioDeviceSharesetNameHere"),
deviceCount,
devices
);

有关更多信息,请参阅以下各节:

AkOutputSettings settingsMainOutput
Main output device settings.
AkAudioDeviceState deviceStateMask
Bitmask used to filter the device based on their state.
Definition: AkTypes.h:323
AKSOUNDENGINE_API AKRESULT Init(AkInitSettings *in_pSettings, AkPlatformInitSettings *in_pPlatformSettings)
#define AK_MAX_PATH
Maximum path length.
Definition: AkTypes.h:82
bool isDefaultDevice
Identify default device. Always false when not supported.
Definition: AkTypes.h:324
AKRESULT
Standard function call result.
Definition: AkTypes.h:213
@ AkPluginTypeEffect
Effect plug-in: applies processing to audio data.
Definition: AkTypes.h:1253
Platform-independent initialization settings of output devices.
#define NULL
Definition: AkTypes.h:46
@ AK_Success
The operation was successful.
Definition: AkTypes.h:215
AKSOUNDENGINE_API void GetDefaultInitSettings(AkInitSettings &out_settings)
AKSOUNDENGINE_API void GetDefaultPlatformInitSettings(AkPlatformInitSettings &out_platformSettings)
AkForceInline void SafeStrCpy(wchar_t *in_pDest, const wchar_t *in_pSrc, size_t in_uDestMaxNumChars)
Safe unicode string copy.
AKSOUNDENGINE_API AkUInt32 GetIDFromString(const char *in_pszString)
AkUniqueID audioDeviceShareset
uint32_t AkUInt32
Unsigned 32-bit integer
AKSOUNDENGINE_API AKRESULT GetDeviceList(AkUInt32 in_ulCompanyID, AkUInt32 in_ulPluginID, AkUInt32 &io_maxNumDevices, AkDeviceDescription *out_deviceDescriptions)
AkUInt32 idDevice
Device ID for Wwise. This is the same as what is returned from AK::GetDeviceID and AK::GetDeviceIDFro...
Definition: AkTypes.h:321

此页面对您是否有帮助?

需要技术支持?

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

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

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

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

开始 Wwise 之旅