Wwise SDK 2024.1.9

プラグインメディアのシステムは、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 は、メディアソースに対する変更によってトリガーされます。

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 の機能についての文書を参照してください。

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

プラグイン定義ファイルがCanReferenceDataFileを使用する場合、インポートしたオリジナルのWAVメディアを、リアルタイムのコンポーネントに適したフォーマットへとランタイムに変換する必要があります。

[//]: # （WG-67845が解決した時にテキストの非表示を解除する）プラグインが代わりにCanReferenceSourceFileを使用する場合、Wwiseはオリジナルの通常の変換設定を使用するので、コンバージョン（変換）を自分で実装する必要はありません。

コンバージョン関数を実装するには、 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;
 
    // 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);
}

プラグインの定義

プラグイン定義ファイル（プラグインの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 を実装するときに、プラグインの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 ポインターを受領することになります。