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

[アーティクル]
03/13/2024

ソース音声を作成して構成します。

構文

HRESULT CreateSourceVoice(
  [out]          IXAudio2SourceVoice        **ppSourceVoice,
  [in]           const WAVEFORMATEX         *pSourceFormat,
  [in]           UINT32                     Flags,
  [in]           float                      MaxFrequencyRatio,
  [in, optional] IXAudio2VoiceCallback      *pCallback,
  [in, out]      const XAUDIO2_VOICE_SENDS  *pSendList,
  [in, optional] const XAUDIO2_EFFECT_CHAIN *pEffectChain
);

パラメーター

[out] ppSourceVoice

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

[in] pSourceFormat

次の表のいずれかの構造体へのポインター。この構造体には、ソース音声に送信されるすべてのオーディオバッファーに対して想定される形式が含まれています。 XAudio2 では、PCM と ADPCM の音声の種類がサポートされています。

タグの書式設定	波の形式の構造	サイズ (バイト単位)
WAVE_FORMAT_PCM (0x0001)	PCMWAVEFORMAT	16
または	WAVEFORMATEX	18
WAVE_FORMAT_IEEE_FLOAT (0x0003) [32 ビット]	PCMWAVEFORMAT	18
WAVE_FORMAT_ADPCM (0x0002) [MS-ADPCM]	ADPCMWAVEFORMAT	50
WAVE_FORMAT_EXTENSIBLE (0xFFFE)	WAVEFORMATEXTENSIBLE	40

XAudio2 では、次の PCM 形式がサポートされています。

8 ビット (符号なし) 整数 PCM
16 ビット整数 PCM (XAudio2 に最適な形式)
20 ビット整数 PCM (24 または 32 ビットコンテナー内)
24 ビット整数 PCM (24 または 32 ビットコンテナー内)
32 ビット整数 PCM
32 ビット浮動小数点 PCM (16 ビット整数の後に推奨される形式)

ソース音声のチャンネル数は、XAUDIO2_MAX_AUDIO_CHANNELS以下である必要があります。ソース音声のサンプルレートは、XAUDIO2_MIN_SAMPLE_RATEとXAUDIO2_MAX_SAMPLE_RATEの間である必要があります。

メモPCMWAVEFORMAT や ADPCMWAVEFORMAT などの PCM データ形式は、WAVEFORMATEX によって提供される情報よりも多くの情報を必要としますが、その形式構造の最初のメンバーとして WAVEFORMATEX 構造を持っています。これらの形式のいずれかを使用してソース音声を作成する場合は、形式の構造を WAVEFORMATEX 構造体としてキャストし、 pSourceFormat の値として使用します。

[in] Flags

ソース音声の動作を指定するフラグ。フラグには、0 または次の 1 つ以上の組み合わせを指定できます。

値	説明
XAUDIO2_VOICE_NOPITCH	音声ではピッチコントロールを使用できません。
XAUDIO2_VOICE_NOSRC	音声でサンプルレート変換を使用できません。音声の出力のサンプルレートは同じである必要があります。メモ XAUDIO2_VOICE_NOSRC フラグを指定すると、音声は XAUDIO2_VOICE_NOPITCH フラグも指定されているかのように動作します。
XAUDIO2_VOICE_USEFILTER	フィルター効果は、この音声で使用できる必要があります。

メモ windows では、XAUDIO2_VOICE_MUSIC フラグはサポートされていません。

[in] MaxFrequencyRatio

この音声で設定できる最高の許容周波数比。この引数の値は、XAUDIO2_MIN_FREQ_RATIOとXAUDIO2_MAX_FREQ_RATIOの間である必要があります。 IXAudio2SourceVoice::SetFrequencyRatio への後続の呼び出しは、XAUDIO2_MIN_FREQ_RATIOと MaxFrequencyRatio の間でクランプされます。この引数の最大値は、最大 10 オクターブでピッチを上げることができるXAUDIO2_MAX_FREQ_RATIOとして定義されます。

MaxFrequencyRatio が 1.0 未満の場合、音声は作成直後に (既定値の 1.0 ではなく) その比率を使用します。

Xbox 360
XMA 音声の場合、 MaxFrequencyRatio 引数と音声のサンプルレートにはもう 1 つの制限があります。これら 2 つの数値の積は、1 チャネルの音声の場合はXAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONOを超えることはできません。また、他の数のチャネルを含む音声の場合はXAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNELを超えることはできません。 MaxFrequencyRatio に指定された値が指定した形式に対して高すぎる場合、CreateSourceVoice の呼び出しは失敗し、デバッグメッセージが生成されます。

Xbox 360

XMA 音声の場合、 MaxFrequencyRatio 引数と音声のサンプルレートにはもう 1 つの制限があります。これら 2 つの数値の積は、1 チャネルの音声の場合はXAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONOを超えることはできません。また、他の数のチャネルを含む音声の場合はXAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNELを超えることはできません。 MaxFrequencyRatio に指定された値が指定した形式に対して高すぎる場合、CreateSourceVoice の呼び出しは失敗し、デバッグメッセージが生成されます。

メモ可能な限り最小の MaxFrequencyRatio 値を使用して、XAudio2 のメモリ使用量を減らすことができます。

[in, optional] pCallback

クライアント提供のコールバックインターフェイス IXAudio2VoiceCallback へのポインター。

[in, out] pSendList

ソース音声の宛先音声のセットを記述する XAUDIO2_VOICE_SENDS 構造のリストへのポインター。 pSendList が NULL の場合、送信リストの既定値は、作成された最初のマスタリング音声への 1 つの出力になります。

[in, optional] pEffectChain

ソース音声で使用するエフェクトチェーンを記述する XAUDIO2_EFFECT_CHAIN 構造体のリストへのポインター。

戻り値

成功した場合はS_OKを返します。それ以外の場合は、エラーコード。

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

注釈

ソース音声は、クライアントからオーディオデータを読み取ります。データを処理し、XAudio2 処理グラフに送信します。

ソース音声には、ソース形式のサンプルレートから音声送信リストに必要な出力レートにデータを変換する、可変レートのサンプルレート変換が含まれています。 NULL 送信リストを使用する場合、ターゲットサンプルレートはマスタリング音声の入力サンプルレートになります。 pSendList で 1 つの音声を指定した場合、その音声の入力サンプルレートがターゲットレートになります。 pSendList に複数の音声を指定する場合は、ソース音声のすべての出力音声が同じ入力サンプルレートで実行されている必要があります。

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

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

最初に作成すると、ソース音声は停止状態になります。

XAudio2 は、同じ形式の音声に内部メモリプーラーを使用します。つまり、音声のメモリ割り当ては、より多くの音声が作成されて破棄されるため、発生頻度が低くなります。 Just-In-Time の割り当てを最小限に抑えるために、タイトルで事前に必要な予想される最大音声数を作成し、必要に応じて削除できます。その後、XAudio2 プールから音声が再利用されます。メモリプールは XAudio2 エンジンインスタンスに関連付けられています。 XAudio2 オブジェクトを破棄し、必要に応じて再作成することで、XAudio2 エンジンのインスタンスで使用されるすべてのメモリを再利用できます (事前割り当てによってメモリプールを強制的に拡張するには、必要に応じて再適用する必要があります)。

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

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