Wwise SDK 2024.1.3

オーディオデバイスプラグインインターフェースの実装

オーディオデバイスプラグインは、オーディオの処理チェーンの最終ポイントです。Natural AudioデバイスはOSのサウンドシステムですが、追加のハードウェアやドライバを使うことで許容される場合は、他の出力も可能です。シンクプラグインの役目は、ミックスされた最終オーディオサンプルを、デバイスが分かる形式でデバイスに転送することです。

サウンドエンジンコンポーネント

オーディオデバイスプラグインを書くことは、サウンドエンジン側では、 AK::IAkSinkPlugin インターフェースの実装を意味します。ここでは、これらのインターフェースに固有の関数のみがカバーされています。他のプラグインタイプと共有されるインターフェースコンポーネント（ AK::IAkPlugin インターフェース）に関する情報については、 Sound Engineプラグインの作成を参照してください。サンプルコードは、提供のAkSink プラグインを参照してください ( サンプル ) 。

オーディオデバイスは常に、そのオーディオデバイスが使用するプラグイン（Audio Deviceシェアセット）と具体的なデバイスIDによって、特定されます。このデバイスIDはWwiseサウンドエンジンにとって特に意味はなく、プラグインの作成者が、同じ種類のデバイスが多数ある場合にそれぞれ区別できるためだけのものです。 AK::SoundEngine::Initや AK::SoundEngine::AddOutputで使われる AkOutputSettings::idDeviceパラメータを経由して、ゲームから送信されます。例えば、Windowsのオーディオデバイスにアクセスするオーディオデバイスプラグインからは、あるコンピュータ上で多数のWindowsデバイスを確認する可能性があります。

複数あるデバイス同士を区別する必要のないデバイスを使う場合は、このパラメータを無視します。一方、これを実装する必要がある場合は、 idDevice パラメータが 0 の時に選択される "デフォルトデバイス"のコンセプトに、必ず対応してください。 0 を受信した時に、最初に使用できるデバイスを選択するのか、特定デバイスを指定するのかは、プラグインプログラマーの自由です。

シンクプラグインに、追加の静的な関数を登録し、利用可能なオーディオデバイスの列挙に対応させることができます。この関数の目的は、オーサリングツール上でユーザーが選択できるデバイスを表示させることと、ランタイムに AK::SoundEngine::GetDeviceList へのコールを通してデバイスの列挙を可能にすることです。この関数はオプションです。これを実装しないと、必要に応じてプラグインがデフォルトの出力先に初期化すると予想されます。必要であれば、追加の静的関数を、プラグインパラメータ作成の関数のあとに提供してください。プラグイン作成のために提供するほかの静的関数に関する詳細は、 Sound Engineプラグインの作成を参照してください。

以下は、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();
 
    // Handle device count requests:
    // If out_deviceDescriptions is NULL, io_maxNumDevices should be set to the device count
    // so the caller can determine how much memory to reserve.
    if (out_deviceDescriptions == NULL)
    {
        io_maxNumDevices = deviceCount;
        return AK_Success;
    }
 
    // else, fill 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;
    }
 
    // Set the number of devices written into the array
    io_maxNumDevices = i;
 
    return AK_Success;
}
 
//Static initializer object to automatically register the plug-in in the sound engine.
AK::PluginRegistration MyPluginRegistration(AkPluginTypeEffect, AKCOMPANYID_MYCOMPANY, EFFECTID_MYPLUGIN, CreateMyPlugin, CreateMyPluginParams, GetMyPluginDeviceList);

info 注釈: このサウンドエンジンの実装は、今までのオーサリングだけの、プラグインに相当する AkGetSinkPluginDevices の代わりとなるもので、デバイス列挙を、サポートされる全プラットフォームで実装し、 AK::SoundEngine::GetDeviceList を通してランタイムにコールできるようにしています。

info 注釈: このファンクションは、全プラットフォームでコンパイルされます。プラットフォーム独自のデバイス列挙に対応するには、適切なマクロ（例 AK_WIN、 AK_LINUX など）を使うべきで、実装が定義されていないプラットフォームの場合は、 AK_NotImplemented を返すべきです。

Audio DeviceプラグインのためのAuthoring DLL

シンクプラグインも、ほかのプラグインと同様に、対応するオーサリングDLLが必要です。全プラグイン共通となるWwiseオーサリング側のコンポーネントの、基本的な設定については、 Authoring Plug-in Library Format を参照してください。

info 注釈: AkGetSinkPluginDevices は非推奨となり、デバイス列挙を実装するには、上記のサウンドエンジンコンポーネントセクションを参照してください。

オーディオデバイスプラグインをテストする

プラグインのWwise側（オーディオプラグインのAuthoring部分の記述）とサウンドエンジン側の部分を実装後、以下の手順でプラグインをテストできます:

Wwise プロジェクトで、新しいプラグインを使って Audio Device Shareset を作成します。ShareSet には固有な名前をつけてください。
バンクを生成し。
プラグインがゲームコードで登録されているかを確認します。 Sound Engineプラグインの概要参照してください。
サウンドエンジンの初期化パラメータに使用する、オーディオデバイスIDを指定します。AkOutputSettingsにあるIDは、このプロジェクトのAudio Deviceシェアセットの名前のハッシュ値であり、 AK::SoundEngine::GetIDFromString で提供されるものです。

例：

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

あるいは、オーディオデバイスプラグインを、 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;
AKRESULT res = AK::SoundEngine::GetDeviceList(
    AK::SoundEngine::GetIDFromString("YourNewAudioDeviceSharesetNameHere"),
    deviceCount,
    devices
);

詳細については、以下のセクションを参照してください：

AkInitSettings::settingsMainOutput

AkOutputSettings settingsMainOutput

Main output device settings.

Definition: AkSoundEngine.h:237

AkDeviceDescription::deviceStateMask

AkAudioDeviceState deviceStateMask

Bitmask used to filter the device based on their state.

Definition: AkTypes.h:247

AK::SoundEngine::Init

AKSOUNDENGINE_API AKRESULT Init(AkInitSettings *in_pSettings, AkPlatformInitSettings *in_pPlatformSettings)

AK_MAX_PATH

#define AK_MAX_PATH

Maximum path length.

Definition: AkTypes.h:82

AkPlatformInitSettings

Definition: AkAndroidSoundEngine.h:56

AkDeviceDescription::isDefaultDevice

bool isDefaultDevice

Identify default device. Always false when not supported.

Definition: AkTypes.h:248

AKRESULT

Standard function call result.

Definition: AkTypes.h:134

AkPluginTypeEffect

@ AkPluginTypeEffect

Effect plug-in: applies processing to audio data.

Definition: AkTypes.h:1190

AkOutputSettings

Platform-independent initialization settings of output devices.

Definition: AkSoundEngine.h:123

NULL

#define NULL

Definition: AkTypes.h:46

AK_Success

@ AK_Success

The operation was successful.

Definition: AkTypes.h:136

AK::SoundEngine::GetDefaultInitSettings

AKSOUNDENGINE_API void GetDefaultInitSettings(AkInitSettings &out_settings)

AK::PluginRegistration

Definition: IAkPlugin.h:1917

AK::SoundEngine::GetDefaultPlatformInitSettings

AKSOUNDENGINE_API void GetDefaultPlatformInitSettings(AkPlatformInitSettings &out_platformSettings)

AKPLATFORM::SafeStrCpy

AkForceInline void SafeStrCpy(wchar_t *in_pDest, const wchar_t *in_pSrc, size_t in_uDestMaxNumChars)

Safe unicode string copy.

Definition: AkPlatformFuncs.h:426

AK::SoundEngine::GetIDFromString

AKSOUNDENGINE_API AkUInt32 GetIDFromString(const char *in_pszString)

AkDeviceDescription

Definition: AkTypes.h:244

AkOutputSettings::audioDeviceShareset

AkUniqueID audioDeviceShareset

Definition: AkSoundEngine.h:136

AkUInt32

uint32_t AkUInt32

Unsigned 32-bit integer

Definition: AkNumeralTypes.h:38

AkInitSettings

Definition: AkSoundEngine.h:223

AK::SoundEngine::GetDeviceList

AKSOUNDENGINE_API AKRESULT GetDeviceList(AkUInt32 in_ulCompanyID, AkUInt32 in_ulPluginID, AkUInt32 &io_maxNumDevices, AkDeviceDescription *out_deviceDescriptions)

AkDeviceDescription::idDevice

AkUInt32 idDevice

Device ID for Wwise. This is the same as what is returned from AK::GetDeviceID and AK::GetDeviceIDFro...

Definition: AkTypes.h:245

このページはお役に立ちましたか？

サポートは必要ですか？

ご質問や問題、ご不明点はございますか？お気軽にお問い合わせください。

サポートページをご確認ください

あなたのプロジェクトについて教えてください。ご不明な点はありませんか。

プロジェクトを登録していただくことで、ご利用開始のサポートをいたします。

Wwiseからはじめよう

Wwise SDK

Audio Device（Sink）プラグインの作成