警告：系统已根据您所用大版本 (2024.1.4.8780) 自动跳转至最新文档。若想访问特定版本的文档，请从 Audiokinetic Launcher 下载离线文档，并在 Wwise 设计程序中勾选 Offline Documentation 选项。

Wwise SDK 2024.1.4

插件媒体系统使插件（效果器、源插件、Sink 插件或混音器）可利用 Wwise 架构存储工程中的二进制数据文件。

以下是在插件中使用插件媒体相对于使用自定义数据的诸多优势：

内置的数据持久化
集成了版本控制（使用工作组功能）
允许单独为每个平台实施数据转码
允许终端用户选择用来存放数据的 SoundBank

Wwise Authoring 插件

管理插件媒体

您可以通过在后端获取 AK::Wwise::Plugin::RequestObjectMedia 来请求 Object Media 服务。藉此，可提供成员 m_objectMedia 以访问相应的服务方法。若要接收有关对象媒体的通知（比如在用户执行更改后），请从 AK::Wwise::Plugin::Notifications::ObjectMedia 获取，并覆盖 AK::Wwise::Plugin::Notifications::ObjectMedia::NotifyPluginMediaChanged() 方法。

class MyPluginBackend
:   public AK::Wwise::Plugin::AudioPlugin
,   public AK::Wwise::Plugin::RequestObjectMedia
,   public AK::Wwise::Plugin::Notifications::ObjectMedia
,   public AK::Wwise::Plugin::RequestHost
{
    void NotifyPluginMediaChanged() override
    {
        // React to change
        // ...
 
        // Notify Wwise the data needs to be reconverted
        m_host.NotifyInternalDataChanged(
            AK::IAkPluginParam::ALL_PLUGIN_DATA_ID,
            true /* in_bMakeProjectDirty */
        );
    }
};

您可以通过调用 AK::Wwise::Plugin::ObjectMedia::SetMediaSource() 来导入媒体文件。在导入媒体时，其将被复制到插件的 Originals 目录下，并完全由 Wwise 进行管理。在索引 0 处添加插件媒体文件：

m_pObjMedia->SetMediaSource( pszFilename, 0, bReplace );

覆盖函数 NotifyPluginMediaChanged 以在插件数据发生更改时接收通知。只要对媒体源进行修改就会触发 NotifyPluginMediaChanged 函数。

void NotifyPluginMediaChanged() override
{
    // React to changes
    // ...
    
    // 通知 Wwise 需要重新转码数据
    m_pPSet->NotifyInternalDataChanged( AK::IAkPluginParam::ALL_PLUGIN_DATA_ID );
}

请参阅 AK::Wwise::Plugin::ObjectMedia 的功能文档了解详情。

为运行时组件转码媒体

若插件定义文件使用 CanReferenceDataFile，则须在运行时将导入的原始 WAV 媒体转码为适合实时组件的格式。

要想实现媒体转码，需从 AK::Wwise::Plugin::MediaConverter 继承并实现所需函数：

class MyPlugin
:   public AK::Wwise::Plugin::AudioPlugin,
,   public AK::Wwise::Plugin::MediaConverter

以下是 AK::Wwise::Plugin::MediaConverter 函数的应用示例：

#include <AK/Tools/Common/AkFNVHash.h>
#include <filesystem>
#include <ctype.h>
 
AK::Wwise::Plugin::ConversionResult MyPlugin::ConvertFile(
    const GUID& in_guidPlatform,
    const BasePlatformID& in_basePlatform,
    const AkOSChar* in_szSourceFile,
    const AkOSChar* in_szDestFile,
    AkUInt32 in_uSampleRate,
    AkUInt32 in_uBlockLength,
    IProgress* in_pProgress,
    IWriteString* io_pError)
{
    // 将原始源文件转码为经过转码的文件。
    // 至少将原始文件复制到已转码的文件中
    std::error_code ec;
    std::filesystem::copy(
        in_szSourceFile,
        in_szDestFile,
        std::filesystem::copy_options::overwrite_existing,
        ec
    );
 
    if (ec)
    {
        return AK:Wwise::Plugin::ConversionFailed;
    }
    return AK::Wwise::Plugin::ConversionSuccess;
}
 
uint32_t MyPlugin::GetCurrentConversionSettingsHash(
    const GUID& in_guidPlatform,
    AkUInt32 in_uSampleRate,
    AkUInt32 in_uBlockLength)
{
    AK::FNVHash32 hashFunc;
 
    // 使用影响转码的参数生成哈希值。
    // 提取源文件名称。
    char szInputFileName[_MAX_PATH];
    auto size = m_pObjMedia->GetMediaSourceFileName(szInputFileName, _MAX_PATH);
    if (size == 0)
        return 0;
 
    for (int i = 0; i < size; ++i)
    {
        szInputFileName[i] = tolower(szInputFileName[i]);
    }
    return hashFunc.Compute(szInputFileName, size);
}

插件定义

在插件定义文件（即插件 XML 文件）中，确保将 CanReferenceDataFile 元素设为 true。

<PluginModule>
    <EffectPlugin Name="YOUR_PLUGIN" CompanyID="???" PluginID="???">
        <PluginInfo MenuPath="???">
            <PlatformSupport>
                <Platform Name="Windows">
...
                    <CanReferenceDataFile>true</CanReferenceDataFile>
                </Platform>
                <Platform Name="XboxOne">
...
                    <CanReferenceDataFile>true</CanReferenceDataFile>
                </Platform>

运行时插件

在运行时使用插件媒体

在插件的声音引擎部分中实现 AK::IAkEffectPlugin 时，会在 Init(...) 函数中接收 AK::IAkEffectPluginContext 指针。从 AK::IAkEffectPluginContext 中，您可以调用 AK::IAkPluginContextBase::GetPluginMedia 来获取经过转码的媒体，这些媒体打包存储于 Wwise 的 SoundBank 中。

AKRESULT RunTimeEffect::Init(
    AK::IAkPluginMemAlloc* in_pAllocator,       // 内存分配器接口。
    AK::IAkEffectPluginContext* in_pFXCtx,      // FX 环境。
    const AkAudioFormat& in_rFormat             // 音频输入格式。)
{
    AkUInt8 * pPluginData = NULL;
    AkUInt32 uPluginDataSize;
    in_pFXCtx->GetPluginMedia( 0, pPluginData, uPluginDataSize );
    if ( pPluginData == NULL )
        return AK_Fail; // 没有冲激响应的时候无需实例化插件。
    ...
}

info 备注: 本例展示了如何在运行时使用 effect 插件媒体。不过，其也可用来阐释如何使用另一插件类型，如 source 插件。在这种情况下，要实现 AK::IAkSourcePlugin 并接收 AK::IAkSourcePluginContext 指针。