Wwise SDK 2023.1.3

プラグインメディアのシステムは、Wwiseアーキテクチャを利用して、プラグイン（エフェクト、ソース、シンク、ミキサーなど）からバイナリデータファイルをプロジェクトに保存できるようになっています。

プラグインでカスタムデータを使用する代わりにプラグインメディアを使用することには、幾つかの利点があります:

データの組み込み持続性
ソース管理の一元化 (ワークグループ機能を使用)
プラットフォーム別のデータコンバージョンが可能
エンドユーザーが、データを保持するSoundBankを選択することが可能

Wwise オーサリングプラグイン

ブラグインメディアの管理

Object Mediaサービスをリクエストするには、あなたのプラグインのバックエンドで AK::Wwise::Plugin::RequestObjectMedia を派生させます。これで、サービスのメソッドをアクセスするための、メンバー 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 is triggered by any modifications to the media source.

void NotifyPluginMediaChanged() override
{
    // React to changes
    // ...
    
    // Notify Wwise the data needs to be reconverted
    m_pPSet->NotifyInternalDataChanged( AK::IAkPluginParam::ALL_PLUGIN_DATA_ID );
}

詳細については AK::Wwise::Plugin::ObjectMedia の機能についての文書を参照してください。

ランタイムのためにメディアを変換する

If the plug-in definition file uses CanReferenceDataFile, you must convert your imported original WAV media at runtime to an appropriate format for the real-time component.

To implement conversion functions, inherit from AK::Wwise::Plugin::MediaConverter and implement the required functions:

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)
{
    // Convert the original source to a converted file.
    // At minimum, copy the original file to converted
    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;
 
    // Generate a Hash from parameters that have an influence on the conversion.
    // Take the source file name.
    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);
}

プラグインの定義

In the plug-in definition file (the plug-in XML file), ensure that the CanReferenceDataFile element is set to 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 を実装するときに、プラグインのSound Engine部分で、 Init(...) 関数の中に AK::IAkEffectPluginContext ポインタを受け取ります。AK::IAkEffectPluginContext から、 AK::IAkPluginContextBase::GetPluginMedia を呼び出して、変換したメディアを手に入れます。これはWwiseのSoundBankにパッケージされています.

AKRESULT RunTimeEffect::Init(
    AK::IAkPluginMemAlloc* in_pAllocator,       // Memory allocator interface.
    AK::IAkEffectPluginContext* in_pFXCtx,      // FX Context.
    const AkAudioFormat& in_rFormat             // Audio input format. )
{
    AkUInt8 * pPluginData = NULL;
    AkUInt32 uPluginDataSize;
    in_pFXCtx->GetPluginMedia( 0, pPluginData, uPluginDataSize );
    if ( pPluginData == NULL )
        return AK_Fail; // No point in instantiating plug-in without impulse response.
    ...
}

注釈: これは、ランタイムに エフェクト プラグインメディアを使った例です。ただし、 source プラグインなど別のプラグインタイプの使い方の参考にもなります。例えばソースプラグインの場合は、 AK::IAkSourcePlugin を実装し、 AK::IAkSourcePluginContext ポインターを受領することになります。