IXAudio2::CreateMasteringVoice メソッド (xaudio2.h)

[アーティクル]
08/28/2023

マスタリング音声を作成して構成します。

構文

HRESULT CreateMasteringVoice(
  [out]          IXAudio2MasteringVoice     **ppMasteringVoice,
  [in]           UINT32                     InputChannels,
  [in]           UINT32                     InputSampleRate,
  [in]           UINT32                     Flags,
  [in]           LPCWSTR                    szDeviceId,
  [in, optional] const XAUDIO2_EFFECT_CHAIN *pEffectChain,
  [in, optional] AUDIO_STREAM_CATEGORY      StreamCategory
);

パラメーター

[out] ppMasteringVoice

成功した場合は、新しい IXAudio2MasteringVoice オブジェクトへのポインターを返します。

[in] InputChannels

マスタリング音声が入力オーディオで想定するチャネルの数。 InputChannels は、 XAUDIO2_MAX_AUDIO_CHANNELS以下である必要があります。

InputChannels を XAUDIO2_DEFAULT_CHANNELS に設定すると、XAudio2 がシステムスピーカー構成のセットアップを検出しようとします。

[in] InputSampleRate

マスタリング音声の入力オーディオデータのサンプルレート。このレートは、XAUDIO2_QUANTUM_DENOMINATORの倍数である必要があります。 InputSampleRate は、XAUDIO2_MIN_SAMPLE_RATEとXAUDIO2_MAX_SAMPLE_RATEの間にある必要があります。

InputSampleRate をXAUDIO2_DEFAULT_SAMPLERATEに設定できます。既定値は現在のプラットフォームによって決定されます。

Windows XP の既定値は 44100 です。

Windows Vista と Windows 7 の既定値は、サウンドコントロールパネルで指定された設定です。この設定の既定値は 44100 (ドライバーで必要な場合は 48000) です。

Flags

[in] Flags

マスタリング音声の動作を指定するフラグ。 0 または XAUDIO2_NO_VIRTUAL_AUDIO_CLIENTを指定できます。

[in] szDeviceId

出力オーディオを受信するデバイスの識別子。既定値を NULL に指定すると、XAudio2 はグローバルな既定のオーディオデバイスを選択します。 Windows 10 以降では、FLAGS に渡されない限りXAUDIO2_NO_VIRTUAL_AUDIO_CLIENT、NULL は WASAPI 仮想化クライアントにもオプトインします。

[in, optional] pEffectChain

マスタリング音声で使用するエフェクトチェーンを記述する XAUDIO2_EFFECT_CHAIN 構造体へのポインター。効果を使用しない場合は NULL。

[in, optional] StreamCategory

このマスタリング音声に使用するオーディオストリームカテゴリ。

戻り値

成功した場合はS_OKを返します。それ以外の場合は、エラーコード。既定のオーディオデバイスが存在せず、szDeviceId パラメーターとして NULL が渡された場合は、ERROR_NOT_FOUNDを返します。

XAudio2 固有のエラーコードの説明については、「XAudio2 エラーコード」を参照してください。

注釈

マスタリング音声は、1 つ以上のソースボイスまたはサブミックスボイスの出力を受け取ります。データを処理し、オーディオ出力デバイスに送信します。

通常は、タイトルのオーディオコンテンツの大部分で使用される入力サンプルレートでマスタリング音声を作成する必要があります。マスタリング音声は、この入力サンプルレートから実際のデバイス出力レートへのサンプルレート変換を実行します。

マスター音声が存在するまで、ソースボイスまたはサブミックスボイスを作成することはできません。ソースボイスまたはサブミックスボイスがまだ存在する場合、マスタリングボイスを破棄することはできません。

マスタリングボイスは、すべてのソースボイスとサブミックスボイスの後に常に処理されます。つまり、処理順序を制御するために ProcessingStage パラメーターを指定する必要はありません。

XAudio2 では、一度に 1 つのマスタリング音声のみが存在できます。複数の音声を作成しようとすると、XAUDIO2_E_INVALID_CALLが返されます。別のオーディオカテゴリが設定されている出力デバイスなど、追加のマスタリング音声が必要な場合は、追加の XAudio2 インスタンスを作成する必要があります。

最初に作成すると、マスタリング音声は開始状態になります。

コールバック (IXAudio2EngineCallback または IXAudio2VoiceCallback) 内から CreateMasteringVoice を呼び出すのは無効です。コールバック内で CreateMasteringVoice を 呼び出すと、XAUDIO2_E_INVALID_CALLが返されます。

pEffectChain 引数として渡される XAUDIO2_EFFECT_CHAIN とその中に含まれる XAUDIO2_EFFECT_DESCRIPTOR 情報は、 CreateMasteringVoice が正常に完了した後は不要になり、 CreateMasteringVoice が呼び出された直後に削除される可能性があります。

DirectX SDK XAUDIO2 バージョンの CreateMasteringVoice では、szDeviceId 引数と StreamCategory 引数の代わりに DeviceIndex 引数が使用されることに注意してください。これは、標準の Windows デバイス列挙モデルに必要な変更を反映しています。