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
    成功した場合、新しい IXAudio2SourceVoice オブジェクトへのポインターを返します。

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

  • Flags
    ソース ボイスの動作を指定するフラグです。フラグには 0 または次のいずれかの値を指定します。

    値説明
    XAUDIO2_VOICE_NOPITCHボイスに対するピッチ コントロールは使用できません。
    XAUDIO2_VOICE_NOSRCボイスに対してサンプル レート変換は実行できません。ボイスの出力はすべて同じ入力サンプル レートである必要があります。

    注    XAUDIO2_VOICE_NOSRC フラグによって、XAUDIO2_VOICE_NOPITCH フラグも指定されているかのようにボイスが動作します。

    XAUDIO2_VOICE_USEFILTERこのボイスでは、フィルター エフェクトが使用可能でなければなりません。
    XAUDIO2_VOICE_MUSICボイスは、バックグラウンド ミュージックの再生に使用されます。ボイスは、ユーザーが選択したミュージックで自動的に置き換えられます。

  • MaxFrequencyRatio
    このボイスに設定できる最大許容周波数比です。この引数の値は、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 ではなくその周波数比を使用します。 注    MaxFrequencyRatio で可能な最も低い値を使用することで、XAudio2 のメモリー使用量を減らすことができます。

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

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

  • pEffectChain
    ソース ボイスで使用するエフェクト チェーンを表す 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 の概要