IXAudio2::CreateSourceVoice メソッド

  • [アーティクル]

ソース ボイスを作成し、設定します。

構文

HRESULT CreateSourceVoice(         IXAudio2SourceVoice **ppSourceVoice,         const WAVEFORMATEX *pSourceFormat,         UINT32 Flags = 0,         float MaxFrequencyRatio = XAUDIO2_DEFAULT_FREQ_RATIO,         IXAudio2VoiceCallback *pCallback = NULL,         const XAUDIO2_VOICE_SENDS *pSendList = NULL,         const XAUDIO2_EFFECT_CHAIN *pEffectChain = NULL)

パラメーター

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

  • pSourceFormat
    [in] WAVEFORMATEX 構造体へのポインターです。この構造体には、ソース ボイスに送られるすべてのオーディオ バッファーに期待される形式が含まれます。

    XAudio2 は、PCM、xWMA、ADPCM (Windows のみ)、および XMA (Xbox 360 のみ) のボイス タイプをサポートします。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 である必要があります。

    注意

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

  • Flags
    [in] ソース ボイスの動作を指定するフラグです。フラグには 0 または次の値を 1 つ以上組み合わせて指定できます。

    値 説明
    XAUDIO2_VOICE_NOPITCH ボイスに対するピッチ コントロールは使用できません。 
    XAUDIO2_VOICE_NOSRC ボイスに対してサンプル レート変換は実行できません。ボイスの出力はすべて同じ入力サンプル レートである必要があります。
    Ee418607.note(ja-jp,VS.85).gif注
    XAUDIO2_VOICE_NOSRC フラグによって、XAUDIO2_VOICE_NOPITCH フラグも指定されているかのようにボイスが動作します。
     
    XAUDIO2_VOICE_USEFILTER このボイスでは、フィルター エフェクトが使用可能でなければなりません。 
    XAUDIO2_VOICE_MUSIC ボイスは、バックグラウンド ミュージックの再生に使用されます。ボイスは、ユーザーが選択したミュージックで自動的に置き換えられます。 

  • MaxFrequencyRatio
    [in] このボイスに設定できる最大許容周波数比です。この引数の値は、XAUDIO2_MIN_FREQ_RATIO から XAUDIO2_MAX_FREQ_RATIO までの間でなければなりません。以降の IXAudio2SourceVoice::SetFrequencyRatio への呼び出しは、XAUDIO2_MIN_FREQ_RATIO と MaxFrequencyRatio の間でクランプされます。

    この引数の最大値は、XAUDIO2_MAX_FREQ_RATIO として定義されます。これにより、最大で 10 オクターブまでピッチを上げることができます。

    MaxFrequencyRatio が 1.0 未満の場合、ボイスは作成後すぐに、既定の 1.0 ではなくその周波数比を使用します。

    Ee418607.note(ja-jp,VS.85).gifXbox 360

    XMA ボイスの場合は、MaxFrequencyRatio 引数およびボイスのサンプル レートについて、さらに別の制限があります。これらの 2 つの数値の積が、1 チャンネル ボイスの場合は XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO を、それ以外のチャンネル数のボイスの場合は XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL を超えることはできません。MaxFrequencyRatio に指定されている値が、指定の形式には高すぎる場合、CreateSourceVoice への呼び出しは失敗し、デバッグ メッセージが表示されます。

    注意

    MaxFrequencyRatio で可能な最も低い値を使用することで、XAudio2 のメモリー使用量を減らすことができます。

  • pCallback
    [in, optional] クライアントが指定したコールバック インターフェイスへのポインターである IXAudio2VoiceCallback です。

  • pSendList
    [in, optional] ソース ボイスに対する一連のデスティネーション ボイスを表す XAUDIO2_VOICE_SENDS 構造体のリストへのポインターです。pSendList が NULL の場合、送信リストは、既定で、最初に作成されたマスター ボイスへの単一の出力となります。

  • pEffectChain
    [in, optional] ソース ボイスで使用するエフェクト チェーンを表す XAUDIO2_EFFECT_CHAIN 構造体のリストへのポインターです。

戻り値

正常に実行された場合は S_OK を返し、失敗した場合はエラー コードを返します。XAudio2 固有のエラー コードの説明については、「XAudio2 エラー コード」を参照してください。

解説　

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

ソース ボイスには、データを、ソース フォーマット サンプル レートからボイス送信リストに必要な出力レートに変換するための、可変レート サンプル レート変換も含まれます。NULL 送信リストが使用されている場合は、ターゲットのサンプル レートは、マスタリング ボイスの入力サンプル レートになります。単一のボイスが pSendList で提供されている場合は、そのボイスの入力サンプル レートがターゲット レートになります。複数のボイスが pSendList で提供されている場合は、ソース ボイスの出力ボイスがすべて同じサンプル レートで実行される必要があります。

マスター ボイスが存在しなければ、ソース ボイスまたはサブミックス ボイスを作成することはできません。また、ソース ボイスまたはサブミックス ボイスが存在している間は、マスター ボイスを破棄することはできません。

ソース ボイスは、常に、サブミックス ボイスまたはマスター ボイスの前に処理されます。したがって、処理順序を制御する ProcessingStage パラメーターは必要はありません。

最初に作成したとき、ソース ボイスは停止した状態になっています。

XAudio2 では、同じ形式のボイスに 1 つの内部メモリー プールを使用するので、多くのボイスが作成された後、破棄される場合に、ボイスのメモリー割り当てが行われる回数が少なくなります。ジャストインタイムの割り当てを最小限に抑えるために、必要なボイスの予想最大数をタイトルで事前に作成してから、必要に応じて削除することができます。その後、ボイスは XAudio2 プールから再利用されます。メモリー プールは XAudio2 エンジンのインスタンスに関連付けられます。XAudio2 エンジンのインスタンスによって使用されるすべてのメモリーは、XAudio2 オブジェクトを破棄し、必要に応じて再作成することで、再利用できます (必要に応じて、事前割り当てによるメモリー プールの拡大を再適用する必要があります)。

コールバック内からの CreateSourceVoice の呼び出しは無効です。コールバック内から CreateSourceVoice を呼び出すと、XAUDIO2_E_INVALID_CALL が返されます。

要件

ヘッダー: xaudio2.h で宣言されています。

関連項目

IXAudio2
方法 : 基本的なオーディオ処理グラフの作成
XAudio2 のサンプル レート変換
XAPO の概要