IXAudio2Voice
COM公式ドキュメント
IXAudio2Voice は、IXAudio2SourceVoice、IXAudio2SubmixVoice、IXAudio2MasteringVoice の派生元となる基底インターフェイスを表します。以下に示すメソッドは、すべての voice サブクラスに共通です。
解説(Remarks)
プラットフォーム要件
Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)メソッド 19
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
voice の作成フラグ、入力チャネル、サンプルレートに関する情報を返します。
| pVoiceDetails | XAUDIO2_VOICE_DETAILS* | out | voice に関する情報を格納する XAUDIO2_VOICE_DETAILS 構造体。 |
戻り値
このメソッドは値を返しません。
解説(Remarks)
プラットフォーム要件
Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)voice の出力を受け取る submix voice または mastering voice の新しいセットを指定します。
| pSendList | XAUDIO2_VOICE_SENDS* | inoptional | 送信先 voice を指す XAUDIO2_VOICE_SENDS 構造体ポインターの配列。pSendList が NULL の場合、voice は現在の mastering voice に出力を送信します。voice の出力をどこにも送信しないように設定するには、XAUDIO2_VOICE_SENDS の OutputCount メンバーを 0 に設定します。送信リスト内のすべての voice は同じ入力サンプルレートを持つ必要があります。詳細については XAudio2 Sample Rate Conversions を参照してください。 |
戻り値
成功した場合は S_OK を、それ以外の場合はエラーコードを返します。XAudio2 固有のエラーコードの説明については XAudio2 Error Codes を参照してください。
解説(Remarks)
このメソッドは source voice と submix voice に対してのみ有効です。mastering voice は他の voice に音声を送信できません。
SetOutputVoices を呼び出すと、voice の現在の送信レベルは既定の送信行列に置き換えられます。新しい送信リストに対してカスタム行列を設定するには、IXAudio2Voice::SetOutputMatrix メソッドを呼び出す必要があります。
コールバック(すなわち IXAudio2EngineCallback または IXAudio2VoiceCallback)の内部から SetOutputVoices を呼び出すことは無効です。コールバック内で SetOutputVoices を呼び出した場合、XAUDIO2_E_INVALID_CALL を返します。
プラットフォーム要件
Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)voice のエフェクトチェーンを置き換えます。
| pEffectChain | XAUDIO2_EFFECT_CHAIN* | inoptional | 使用する新しいエフェクトチェーンを記述する XAUDIO2_EFFECT_CHAIN 構造体へのポインター。NULL を渡すと、現在のエフェクトチェーンが削除されます。 Note pEffectChain が非 NULL の場合、それが指す XAUDIO2_EFFECT_CHAIN 構造体には少なくとも 1 つのエフェクトを指定する必要があります。
|
戻り値
成功した場合は S_OK を、それ以外の場合はエラーコードを返します。
XAudio2 固有のエラーコードの説明については XAudio2 Error Codes を参照してください。
解説(Remarks)
voice のエフェクトチェーンに許可される出力チャネル数は、voice の作成時に固定されます。エフェクトチェーンを指定して voice を作成した場合、SetEffectChain に渡す新しいエフェクトチェーンは、元のエフェクトチェーンと同じ入力チャネル数および出力チャネル数を持つ必要があります。エフェクトチェーンを指定せずに voice を作成した場合、エフェクトチェーンに許可される出力チャネル数は、既定で voice の入力チャネル数になります。エフェクトチェーンの作成の一部でも失敗した場合、その作成は一切適用されません。
XAudio2 voice にエフェクトをアタッチすると、XAudio2 がそのエフェクトの制御を引き継ぐため、クライアントはそれ以上そのエフェクトを呼び出してはいけません。これを確実にする最も簡単な方法は、エフェクトへのすべてのポインターを解放することです。
コールバック(すなわち IXAudio2EngineCallback または IXAudio2VoiceCallback)の内部から SetEffectChain を呼び出すことは無効です。コールバック内で SetEffectChain を呼び出した場合、XAUDIO2_E_INVALID_CALL を返します。
pEffectChain 引数として渡される XAUDIO2_EFFECT_CHAIN と、その中に含まれる XAUDIO2_EFFECT_DESCRIPTOR の情報は、SetEffectChain が正常に完了した後は不要となり、SetEffectChain を呼び出した直後に削除できます。
プラットフォーム要件
Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)voice のエフェクトチェーン内の指定した位置にあるエフェクトを有効にします。
| EffectIndex | DWORD | in | voice のエフェクトチェーン内のエフェクトの 0 から始まるインデックス。 |
| OperationSet | DWORD | in | この呼び出しを遅延バッチの一部として識別します。詳細については XAudio2 Operation Sets の概要を参照してください。 |
戻り値
成功した場合は S_OK を、それ以外の場合はエラーコードを返します。エラーコードの説明については XAudio2 Error Codes を参照してください。
解説(Remarks)
エフェクトをホストしている voice の実行中にそのエフェクトを有効にする場合は注意してください。このような操作は、エフェクトが音声のピッチや音量を大きく変化させる場合に問題を引き起こすことがあります。
特定の XAudio2 voice のエフェクトチェーン内のエフェクトは、その voice の処理サンプルレートで音声を消費および生成する必要があります。エフェクトが変更できる音声フォーマットの要素はチャネル数のみです。たとえば、reverb エフェクトはモノラルデータを 5.1 に変換できます。クライアントは XAUDIO2_EFFECT_DESCRIPTOR 構造体の OutputChannels フィールドを使用して、各エフェクトに生成させるチャネル数を指定できます。エフェクトチェーン内の各エフェクトは、次のエフェクトが消費できるチャネル数を生成する必要があります。これらの要件をエフェクトチェーンが満たさなくなるような IXAudio2Voice::EnableEffect または IXAudio2Voice::DisableEffect の呼び出しは失敗します。
OperationSet に XAUDIO2_COMMIT_NOW を指定して XAudio2 コールバックから EnableEffect を呼び出した場合、その効果は直ちに反映されます。
プラットフォーム要件
Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)voice のエフェクトチェーン内の指定した位置にあるエフェクトを無効にします。
| EffectIndex | DWORD | in | voice のエフェクトチェーン内のエフェクトの 0 から始まるインデックス。 |
| OperationSet | DWORD | in | この呼び出しを遅延バッチの一部として識別します。詳細については XAudio2 Operation Sets の概要を参照してください。 |
戻り値
成功した場合は S_OK を、それ以外の場合はエラーコードを返します。有効なエラーコードの説明については XAudio2 Error Codes を参照してください。
解説(Remarks)
特定の XAudio2 voice のエフェクトチェーン内のエフェクトは、その voice の処理サンプルレートで音声を消費および生成する必要があります。エフェクトが変更できる音声フォーマットの要素はチャネル数のみです。たとえば、reverb エフェクトはモノラルデータを 5.1 に変換できます。クライアントは XAUDIO2_EFFECT_DESCRIPTOR 構造体の OutputChannels フィールドを使用して、各エフェクトに生成させるチャネル数を指定できます。エフェクトチェーン内の各エフェクトは、次のエフェクトが消費できるチャネル数を生成する必要があります。これらの要件をエフェクトチェーンが満たさなくなるような IXAudio2Voice::EnableEffect または IXAudio2Voice::DisableEffect の呼び出しは失敗します。
エフェクトを無効にすると、そのエフェクトは処理グラフから直ちに削除されます。エフェクト内で保留中の音声(reverb の残響など)は再生されません。エフェクトをホストしている voice の実行中にそのエフェクトを無効にする場合は注意してください。エフェクトが音声のピッチや音量を大きく変化させる場合、可聴のアーティファクトが発生することがあります。
OperationSet に XAUDIO2_COMMIT_NOW を指定して XAudio2 コールバックから呼び出した場合、DisableEffect の効果は直ちに反映されます。
プラットフォーム要件
Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)voice のエフェクトチェーン内の指定した位置にあるエフェクトの実行状態を返します。
| EffectIndex | DWORD | in | voice のエフェクトチェーン内のエフェクトの 0 から始まるインデックス。 |
| pEnabled | BOOL* | out | エフェクトが有効な場合は TRUE を返します。エフェクトが無効な場合は FALSE を返します。 |
戻り値
このメソッドは値を返しません。
解説(Remarks)
GetEffectState は常にエフェクトの実際の現在の状態を返します。ただし、これは直近の IXAudio2Voice::EnableEffect または IXAudio2Voice::DisableEffect の呼び出しで設定された状態とは限りません。実際の状態は、IXAudio2Voice::EnableEffect または IXAudio2Voice::DisableEffect の呼び出し後(または、EnableEffect/DisableEffect が遅延操作 ID を指定して呼び出された場合は、対応する IXAudio2::CommitChanges の呼び出し後)に、オーディオエンジンが次に実行されたときにのみ変更されます。
プラットフォーム要件
Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)voice のエフェクトチェーン内の指定したエフェクトのパラメーターを設定します。
| EffectIndex | DWORD | in | voice のエフェクトチェーン内のエフェクトの 0 から始まるインデックス。 |
| pParameters | void* | in | エフェクト固有のパラメーターの現在の値を返します。 |
| ParametersByteSize | DWORD | in | pParameters 配列のサイズ(バイト単位)。 |
| OperationSet | DWORD | in | この呼び出しを遅延バッチの一部として識別します。詳細については XAudio2 Operation Sets の概要を参照してください。 |
戻り値
成功した場合は S_OK を、それ以外の場合はエラーコードを返します。エラーコードの説明については XAudio2 Error Codes を参照してください。
エフェクトが汎用的なパラメーター制御インターフェイスをサポートしていない場合は、E_NOTIMPL で失敗します。
解説(Remarks)
使用する特定のエフェクトによって、pParameters バッファーの有効なサイズとフォーマットが決まります。pParameters が無効な場合、または ParametersByteSize がエフェクトの想定するサイズと正確に一致しない場合、呼び出しは失敗します。クライアントは、SetEffectParameters の呼び出しを正しいエフェクトに向けるよう注意する必要があります。この呼び出しが、たまたま同じパラメーターブロックサイズを受け入れる別のエフェクトに向けられた場合、パラメーターは異なって解釈されます。これにより予期しない結果を招くことがあります。
pParameters が指すメモリは直ちに解放してはいけません。XAudio2 は、パラメーターが実際にエフェクトに適用される際に、後でそれを参照する必要があるためです。これは、OperationSet 引数が XAUDIO2_COMMIT_NOW の場合、次のオーディオ処理パスで発生します。それ以外の場合、パラメーターは、同じ OperationSet 引数を指定して IXAudio2::CommitChanges 関数が呼び出された後、最初の処理パスでエフェクトに適用されます。
OperationSet に XAUDIO2_COMMIT_NOW を指定して XAudio2 コールバックから呼び出した場合、SetEffectParameters の効果は直ちに反映されます。
プラットフォーム要件
Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)voice のエフェクトチェーン内の指定したエフェクトの現在のエフェクト固有のパラメーターを返します。
| EffectIndex | DWORD | in | voice のエフェクトチェーン内のエフェクトの 0 から始まるインデックス。 |
| pParameters | void* | out | エフェクト固有のパラメーターの現在の値を返します。 |
| ParametersByteSize | DWORD | in | pParameters 配列のサイズ(バイト単位)。 |
戻り値
成功した場合は S_OK を、それ以外の場合はエラーコードを返します。エラーコードの説明については XAudio2 Error Codes を参照してください。
エフェクトが汎用的なパラメーター制御インターフェイスをサポートしていない場合は、E_NOTIMPL で失敗します。
解説(Remarks)
GetEffectParameters は常にエフェクトの実際の現在のパラメーターを返します。ただし、これらは直近の IXAudio2Voice::SetEffectParameters の呼び出しで設定されたパラメーターと一致しない場合があります。実際のパラメーターは、IXAudio2Voice::SetEffectParameters の呼び出し後(または、IXAudio2Voice::SetEffectParameters が遅延操作 ID を指定して呼び出された場合は、対応する IXAudio2::CommitChanges の呼び出し後)に、オーディオエンジンが次に実行されたときにのみ変更されます。
プラットフォーム要件
Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)voice のフィルターパラメーターを設定します。
| pParameters | XAUDIO2_FILTER_PARAMETERS* | in | フィルター情報を格納する XAUDIO2_FILTER_PARAMETERS 構造体へのポインター。 |
| OperationSet | DWORD | in | この呼び出しを遅延バッチの一部として識別します。詳細については XAudio2 Operation Sets の概要を参照してください。 |
戻り値
成功した場合は S_OK を、それ以外の場合はエラーコードを返します。エラーコードの説明については XAudio2 Error Codes を参照してください。
解説(Remarks)
SetFilterParameters は、voice が XAUDIO2_VOICE_USEFILTER フラグを指定して作成されていない場合は失敗します。
このメソッドは source voice と submix voice でのみ使用でき、mastering voice には効果がありません。
プラットフォーム要件
Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)voice のフィルターパラメーターを取得します。
| pParameters | XAUDIO2_FILTER_PARAMETERS* | out | フィルター情報を格納する XAUDIO2_FILTER_PARAMETERS 構造体へのポインター。 |
戻り値
このメソッドは値を返しません。
解説(Remarks)
GetFilterParameters は、voice が XAUDIO2_VOICE_USEFILTER フラグを指定して作成されていない場合は失敗します。
GetFilterParameters は常にこの voice の実際の現在のフィルターパラメーターを返します。ただし、これらは直近の IXAudio2Voice::SetFilterParameters の呼び出しで設定されたパラメーターと一致しない場合があります。実際のパラメーターは、IXAudio2Voice::SetFilterParameters の呼び出し後(または、IXAudio2Voice::SetFilterParameters が遅延操作 ID を指定して呼び出された場合は、対応する IXAudio2::CommitChanges の呼び出し後)に、オーディオエンジンが次に実行されたときにのみ変更されます。
プラットフォーム要件
Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)この voice の送信のいずれかにフィルターパラメーターを設定します。
| pDestinationVoice | IXAudio2Voice* | inoptional | フィルターパラメーターを設定する送信の送信先 voice を指す IXAudio2Voice ポインター。 |
| pParameters | XAUDIO2_FILTER_PARAMETERS* | in | フィルター情報を格納する XAUDIO2_FILTER_PARAMETERS 構造体へのポインター。 |
| OperationSet | DWORD | in | この呼び出しを遅延バッチの一部として識別します。詳細については XAudio2 Operation Sets の概要を参照してください。 |
戻り値
成功した場合は S_OK を、それ以外の場合はエラーコードを返します。エラーコードの説明については XAudio2 Error Codes を参照してください。
解説(Remarks)
SetOutputFilterParameters は、送信が XAUDIO2_SEND_USEFILTER フラグを指定して作成されていない場合は失敗します。このメソッドは source voice と submix voice に属する送信でのみ使用でき、mastering voice の送信には効果がありません。
プラットフォーム要件
Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)この voice の送信のいずれかからフィルターパラメーターを返します。
| pDestinationVoice | IXAudio2Voice* | inoptional | フィルターパラメーターを読み取る送信の送信先 voice を指す IXAudio2Voice ポインター。 |
| pParameters | XAUDIO2_FILTER_PARAMETERS* | out | フィルター情報を格納する XAUDIO2_FILTER_PARAMETERS 構造体へのポインター。 |
戻り値
このメソッドは値を返しません。
解説(Remarks)
GetOutputFilterParameters は、送信が XAUDIO2_SEND_USEFILTER フラグを指定して作成されていない場合は失敗します。このメソッドは source voice と submix voice に属する送信でのみ使用でき、mastering voice の送信には効果がありません。
プラットフォーム要件
Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)voice の全体的な音量レベルを設定します。
| Volume | FLOAT | in | 使用する全体的な音量レベル。音量レベルの詳細については「解説」を参照してください。 |
| OperationSet | DWORD | in | この呼び出しを遅延バッチの一部として識別します。詳細については XAudio2 Operation Sets の概要を参照してください。 |
戻り値
成功した場合は S_OK を、それ以外の場合はエラーコードを返します。エラーコードの説明については XAudio2 Error Codes を参照してください。
解説(Remarks)
SetVolume は voice のマスター入力音量レベルを制御します。マスター音量レベルは、voice の種類によって適用されるタイミングが異なります。submix voice と mastering voice では、音量レベルは voice の組み込みフィルターおよびエフェクトチェーンが適用される直前に適用されます。source voice では、マスター音量レベルは voice のフィルターおよびエフェクトチェーンが適用された後に適用されます。
音量レベルは、-XAUDIO2_MAX_VOLUME_LEVEL から XAUDIO2_MAX_VOLUME_LEVEL(-2²⁴ ～ 2²⁴)の範囲の浮動小数点の振幅乗数として表され、最大ゲインは 144.5 dB です。音量レベル 1.0 は減衰もゲインもないことを意味し、0 は無音を意味します。負のレベルを使用して音声の位相を反転させることができます。音量制御の詳細については XAudio2 Volume and Pitch Control を参照してください。
プラットフォーム要件
Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)voice の現在の全体的な音量レベルを取得します。
| pVolume | FLOAT* | out | voice の現在の全体的な音量レベルを返します。音量レベルの詳細については「解説」を参照してください。 |
戻り値
このメソッドは値を返しません。
解説(Remarks)
音量レベルは、-224 ～ 224 の範囲の浮動小数点の振幅乗数として表され、最大ゲインは 144.5 dB です。音量レベル 1 は減衰もゲインもないことを意味し、0 は無音を意味します。負のレベルを使用して音声の位相を反転させることができます。音量制御の詳細については XAudio2 Volume and Pitch Control を参照してください。
プラットフォーム要件
Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)voice の音量レベルをチャネルごとに設定します。
| Channels | DWORD | in | voice のチャネル数。 |
| pVolumes | FLOAT* | in | voice の各チャネルの新しい音量を格納する配列。配列は Channels 個の要素を持つ必要があります。音量レベルの詳細については「解説」を参照してください。 |
| OperationSet | DWORD | in | この呼び出しを遅延バッチの一部として識別します。詳細については XAudio2 Operation Sets の概要を参照してください。 |
戻り値
成功した場合は S_OK を、それ以外の場合はエラーコードを返します。XAudio2 固有のエラーコードの説明については XAudio2 Error Codes を参照してください。
解説(Remarks)
SetChannelVolumes は voice のチャネルごとの出力レベルを制御し、voice の最終的な SRC の直後、かつ送信の前に適用されます。
mastering voice はチャネルごとの音量を指定しないため、このメソッドは source voice と submix voice に対してのみ有効です。
音量レベルは、-XAUDIO2_MAX_VOLUME_LEVEL から XAUDIO2_MAX_VOLUME_LEVEL(-2²⁴ ～ 2²⁴)の範囲の浮動小数点の振幅乗数として表され、最大ゲインは 144.5 dB です。音量 1 は減衰もゲインもないことを意味し、0 は無音を意味します。負のレベルを使用して音声の位相を反転させることができます。音量制御の詳細については XAudio2 Volume and Pitch Control を参照してください。
プラットフォーム要件
Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)voice の音量レベルをチャネルごとに返します。
| Channels | DWORD | in | voice のチャネル数を確認します。 |
| pVolumes | FLOAT* | out | voice の各チャネルの現在の音量レベルを返します。配列は少なくとも Channels 個の要素を持つ必要があります。音量レベルの詳細については「解説」を参照してください。 |
戻り値
このメソッドは値を返しません。
解説(Remarks)
これらの設定は、エフェクトチェーンが適用された後に適用されます。mastering voice はチャネルごとの音量を指定しないため、このメソッドは source voice と submix voice に対してのみ有効です。
音量レベルは、-2²⁴ ～ 2²⁴ の範囲の浮動小数点の振幅乗数として表され、最大ゲインは 144.5 dB です。音量 1 は減衰もゲインもないことを意味し、0 は無音を意味し、負のレベルを使用して音声の位相を反転させることができます。音量制御の詳細については XAudio2 Volume and Pitch Control を参照してください。
プラットフォーム要件
Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)voice の最終出力の各チャネルの音量レベルを設定します。これらのチャネルは、指定した送信先 voice の入力チャネルにマッピングされます。
| pDestinationVoice | IXAudio2Voice* | inoptional | 音量レベルを設定する送信先 IXAudio2Voice へのポインター。 Note voice が単一のターゲット voice に送信している場合、NULL を指定すると SetOutputMatrix はそのターゲット voice に対して動作します。
| |||||||||||||||||||||
| SourceChannels | DWORD | in | voice の出力チャネル数を確認します。これは、チェーン内の最後のエフェクトが生成するチャネル数です。 | |||||||||||||||||||||
| DestinationChannels | DWORD | in | 送信先 voice の入力チャネル数を確認します。 | |||||||||||||||||||||
| pLevelMatrix | FLOAT* | in | 送信先 voice に送信される [SourceChannels × DestinationChannels] 個の音量レベルの配列。ソースチャネル S から送信先チャネル D に送信されるレベルは、pLevelMatrix[SourceChannels × D + S] の形式で指定します。 たとえば、2 チャネルのステレオ入力を、フロントチャネルに重み付けされ、センターチャネルと低周波チャネルには存在しない 5.1 出力にレンダリングする場合、行列は次の表に示す値を持つことがあります。
Note 左右の入力は出力の左右チャネルに完全にマッピングされ、左右の入力の 80 パーセントがリアの左右チャネルにマッピングされます。
| |||||||||||||||||||||
| OperationSet | DWORD | in | この呼び出しを遅延バッチの一部として識別します。詳細については XAudio2 Operation Sets の概要を参照してください。 |
戻り値
成功した場合は S_OK を、それ以外の場合はエラーコードを返します。エラーコードの説明については XAudio2 Error Codes を参照してください。
解説(Remarks)
mastering voice は行列ミキシングを行わずにデバイスに直接書き込むため、このメソッドは source voice と submix voice に対してのみ有効です。
音量レベルは、-XAUDIO2_MAX_VOLUME_LEVEL から XAUDIO2_MAX_VOLUME_LEVEL(-2²⁴ ～ 2²⁴)の範囲の浮動小数点の振幅乗数として表され、最大ゲインは 144.5 dB です。音量レベル 1.0 は減衰もゲインもないことを意味し、0 は無音を意味します。負のレベルを使用して音声の位相を反転させることができます。音量制御の詳細については XAudio2 Volume and Pitch Control を参照してください。
X3DAudio の関数 X3DAudioCalculate は、サウンドの位置とリスナーの位置に基づいて、SetOutputMatrix で使用する出力行列を生成できます。
プラットフォーム要件
Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)voice の最終出力の各チャネルの音量レベルを取得します。これらのチャネルは、指定した送信先 voice の入力チャネルにマッピングされます。
| pDestinationVoice | IXAudio2Voice* | inoptional | 出力行列を取得する送信先 IXAudio2Voice を指定するポインター。 Note voice が単一のターゲット voice に送信している場合、NULL を指定すると GetOutputMatrix はそのターゲット voice に対して動作します。
|
| SourceChannels | DWORD | in | voice の出力チャネル数を確認します。これは、チェーン内の最後のエフェクトが生成するチャネル数です。 |
| DestinationChannels | DWORD | in | 送信先 voice の入力チャネル数を確認します。 |
| pLevelMatrix | FLOAT* | out | 送信先 voice に送信される [SourceChannels * DestinationChannels] 個の音量レベルの配列。ソースチャネル S から送信先チャネル D に送信されるレベルは、pLevelMatrix[DestinationChannels × S + D] の形式で返されます。音量レベルの詳細については「解説」を参照してください。 |
戻り値
このメソッドは値を返しません。
解説(Remarks)
mastering voice は行列ミキシングを行わずにデバイスに直接書き込むため、このメソッドは source voice と submix voice にのみ適用されます。
音量レベルは、-2²⁴ ～ 2²⁴ の範囲の浮動小数点の振幅乗数として表され、最大ゲインは 144.5 dB です。音量レベル 1 は減衰もゲインもないことを意味し、0 は無音を意味します。負のレベルを使用して音声の位相を反転させることができます。音量制御の詳細については XAudio2 Volume and Pitch Control を参照してください。
標準的なチャネルの並び順については WAVEFORMATEXTENSIBLE を参照してください。
プラットフォーム要件
Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)voice を破棄します。必要に応じて voice を停止し、XAudio2 グラフから削除します。
戻り値
このメソッドは値を返しません。
解説(Remarks)
他の voice が現在この voice に音声を送信している場合、このメソッドは失敗します。
DestroyVoice はオーディオ処理スレッドがアイドル状態になるのを待つため、多少時間がかかることがあります(通常は数ミリ秒以内)。これは、voice がそれ以上コールバックを行ったり音声データを読み取ったりしないことを保証するために必要であり、これによりアプリケーションは呼び出しが返ると同時にこれらのリソースを安全に解放できます。
ブロッキングする DestroyVoice の呼び出しによるタイトルスレッドの中断を避けるため、アプリケーションは別の非クリティカルなスレッドで voice を破棄するか、voice を破棄する代わりに再利用する voice プーリング戦略を使用できます。voice は、その voice の作成時と同じデータフォーマットおよび同じチャネル数を持つ音声でのみ再利用できることに注意してください。voice は、適切な比率パラメーターを指定して IXAudio2SourceVoice::SetFrequencyRatio を呼び出すことで、その voice とは異なるサンプルレートの音声データを再生できます。
コールバック(すなわち IXAudio2EngineCallback または IXAudio2VoiceCallback)の内部から DestroyVoice を呼び出すことは無効です。
プラットフォーム要件
Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IXAudio2Voice "{}" #usecom global IXAudio2Voice IID_IXAudio2Voice "{}" #comfunc global IXAudio2Voice_GetVoiceDetails 0 var #comfunc global IXAudio2Voice_SetOutputVoices 1 var #comfunc global IXAudio2Voice_SetEffectChain 2 var #comfunc global IXAudio2Voice_EnableEffect 3 int,int #comfunc global IXAudio2Voice_DisableEffect 4 int,int #comfunc global IXAudio2Voice_GetEffectState 5 int,var #comfunc global IXAudio2Voice_SetEffectParameters 6 int,sptr,int,int #comfunc global IXAudio2Voice_GetEffectParameters 7 int,sptr,int #comfunc global IXAudio2Voice_SetFilterParameters 8 var,int #comfunc global IXAudio2Voice_GetFilterParameters 9 var #comfunc global IXAudio2Voice_SetOutputFilterParameters 10 sptr,var,int #comfunc global IXAudio2Voice_GetOutputFilterParameters 11 sptr,var #comfunc global IXAudio2Voice_SetVolume 12 float,int #comfunc global IXAudio2Voice_GetVolume 13 var #comfunc global IXAudio2Voice_SetChannelVolumes 14 int,var,int #comfunc global IXAudio2Voice_GetChannelVolumes 15 int,var #comfunc global IXAudio2Voice_SetOutputMatrix 16 sptr,int,int,var,int #comfunc global IXAudio2Voice_GetOutputMatrix 17 sptr,int,int,var #comfunc global IXAudio2Voice_DestroyVoice 18 ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IXAudio2Voice "{}" #usecom global IXAudio2Voice IID_IXAudio2Voice "{}" #comfunc global IXAudio2Voice_GetVoiceDetails 0 sptr #comfunc global IXAudio2Voice_SetOutputVoices 1 sptr #comfunc global IXAudio2Voice_SetEffectChain 2 sptr #comfunc global IXAudio2Voice_EnableEffect 3 int,int #comfunc global IXAudio2Voice_DisableEffect 4 int,int #comfunc global IXAudio2Voice_GetEffectState 5 int,sptr #comfunc global IXAudio2Voice_SetEffectParameters 6 int,sptr,int,int #comfunc global IXAudio2Voice_GetEffectParameters 7 int,sptr,int #comfunc global IXAudio2Voice_SetFilterParameters 8 sptr,int #comfunc global IXAudio2Voice_GetFilterParameters 9 sptr #comfunc global IXAudio2Voice_SetOutputFilterParameters 10 sptr,sptr,int #comfunc global IXAudio2Voice_GetOutputFilterParameters 11 sptr,sptr #comfunc global IXAudio2Voice_SetVolume 12 float,int #comfunc global IXAudio2Voice_GetVolume 13 sptr #comfunc global IXAudio2Voice_SetChannelVolumes 14 int,sptr,int #comfunc global IXAudio2Voice_GetChannelVolumes 15 int,sptr #comfunc global IXAudio2Voice_SetOutputMatrix 16 sptr,int,int,sptr,int #comfunc global IXAudio2Voice_GetOutputMatrix 17 sptr,int,int,sptr #comfunc global IXAudio2Voice_DestroyVoice 18 ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。