Win32 API 日本語リファレンス
ホーム › Media.Audio.XAudio2 › IXAudio2SourceVoice

IXAudio2SourceVoice

COM
📘 Microsoft Learn (日本語) · English
継承元IXAudio2Voice自前メソッド開始 vtbl19

公式ドキュメント

ソースボイスを使用して、XAudio2 の処理パイプラインにオーディオデータを送信します。

解説(Remarks)

プラットフォーム要件

Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)

メソッド 10

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 19 HRESULT Start(DWORD Flags, DWORD OperationSet)

ボイスによるオーディオの消費と処理を開始します。処理結果は、接続されているサブミックスボイスまたはマスタリングボイス、あるいは出力デバイスに配信されます。

FlagsDWORDinボイスの開始方法を制御するフラグ。0 でなければなりません。
OperationSetDWORDinこの呼び出しを遅延バッチの一部として識別します。詳細については、XAudio2 Operation Sets の概要を参照してください。

戻り値

成功した場合は S_OK を、それ以外の場合はエラーコードを返します。XAudio2 固有のエラーコードの説明については、XAudio2 Error Codes を参照してください。

解説(Remarks)

XAudio2 エンジンが停止すると、ボイスは実行を停止します。ただし、開始状態は維持されるため、エンジンが開始されると再び実行を開始します。

作成直後のソースボイスは停止状態です。サブミックスボイスとマスタリングボイスは開始状態です。

Start を呼び出した後、IXAudio2SourceVoice::Stop が呼び出される前に再度呼び出しても、それ以上の効果はありません。さらに、対応する IXAudio2SourceVoice::Stop の呼び出しがないまま Start を複数回呼び出すと、デバッグビルドでは警告メッセージが出力されます。

プラットフォーム要件

Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)
vtbl 20 HRESULT Stop(DWORD Flags, DWORD OperationSet)

現在のボイスによるオーディオの消費を停止します。

FlagsDWORDin

ボイスの停止方法を制御するフラグ。0 または以下の値を指定できます。

値 説明
XAUDIO2_PLAY_TAILS ボイスの停止後もエフェクト出力の生成を継続します。
OperationSetDWORDinこの呼び出しを遅延バッチの一部として識別します。詳細については、XAudio2 Operation Sets の概要を参照してください。

戻り値

成功した場合は S_OK を、それ以外の場合はエラーコードを返します。XAudio2 固有のエラーコードの説明については、XAudio2 Error Codes を参照してください。

解説(Remarks)

ボイスのキューに登録されているすべてのソースバッファと現在のカーソル位置は保持されます。これにより、ボイスは再開時に中断した位置から続行できます。キューに登録されたソースバッファをフラッシュするには、IXAudio2SourceVoice::FlushSourceBuffers メソッドを使用できます。

既定では、ボイスエフェクトからの保留中の出力(たとえばリバーブの残響音)は再生されません。代わりに、ボイスは直ちに無音になります。ボイスの実行停止後もエフェクト出力の生成を継続するには、XAUDIO2_PLAY_TAILS フラグを使用できます。

XAUDIO2_PLAY_TAILS フラグを指定して停止したボイスは、ソースバッファの消費を停止しますが、エフェクトの処理を継続し、宛先ボイスへオーディオを送信し続けます。この状態のボイスは、後で Flags 引数に 0 を設定して Stop を再度呼び出すことで完全に停止できます。これにより、XAUDIO2_PLAY_TAILS を指定してボイスを停止し、エフェクトが生成するオーディオが完了するまで十分な時間を待ってから、XAUDIO2_PLAY_TAILS を指定せずに Stop を再度呼び出してボイスを完全に停止する、という手順が可能になります。この手法により、エフェクトを持つボイスを緩やかに停止しつつ、アイドル状態のボイスがオーディオの生成完了後も処理され続けないようにできます。

Stop は、コールバック内で呼び出された場合であっても、常に非同期です。

Note ボイスが停止している場合、XAudio2 はそのボイスに対していかなるボイスコールバックも呼び出しません(XAUDIO2_PLAY_TAILS を指定して停止した場合でも同様です)。

プラットフォーム要件

Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)
vtbl 21 HRESULT SubmitSourceBuffer(XAUDIO2_BUFFER* pBuffer, XAUDIO2_BUFFER_WMA* pBufferWMA)

新しいオーディオバッファをボイスのキューに追加します。

pBufferXAUDIO2_BUFFER*inキューに登録する XAUDIO2_BUFFER 構造体へのポインター。
pBufferWMAXAUDIO2_BUFFER_WMA*inoptionalWMA データを送信する際に使用する追加の XAUDIO2_BUFFER_WMA 構造体へのポインター。

戻り値

成功した場合は S_OK を、それ以外の場合はエラーコードを返します。XAudio2 固有のエラーコードの説明については、XAudio2 Error Codes を参照してください。

解説(Remarks)

ボイスは、キュー内のバッファを送信された順序で処理し、再生します。

XAUDIO2_BUFFER 構造体には、オーディオバッファの位置とサイズ、実際に再生すべきバッファの部分、(存在する場合は)ループ領域とループ回数、このバッファに関連するコールバックで使用されるコンテキストポインター、および連続したサウンドの最後のバッファであることを示すオプションの XAUDIO2_END_OF_STREAM フラグに関する詳細情報が含まれます。

ボイスが開始されており、キューにバッファがない場合、新しいバッファは直ちに再生を開始します。ボイスが停止している場合、バッファはボイスのキューに追加され、ボイスが開始したときに再生されます。

指定したバッファの一部のみを再生する場合は、XAUDIO2_BUFFER の PlayBegin フィールドと PlayLength フィールドを使用して再生する領域を指定できます。PlayLength の値が 0 の場合はバッファ全体を再生することを意味します(この場合、PlayBegin も 0 でなければなりません)。

バッファの全体または一部を連続ループで再生する場合は、XAUDIO2_BUFFER の LoopBegin、LoopLength、LoopCount フィールドを使用してループ領域の特性を指定できます。LoopBegin の値が XAUDIO2_NO_LOOP_REGION の場合はループを実行しないことを意味し、この場合 LoopLength と LoopCount は 0 を指定する必要があります。ループ領域を指定する場合、それは空であってはならず(LoopLength > 0)、ループ回数は 1 から XAUDIO2_MAX_LOOP_COUNT までの範囲(両端を含む)でなければなりません(または IXAudio2SourceVoice::ExitLoop が呼び出されたときにのみ終了する無限ループを指定するには XAUDIO2_LOOP_INFINITE を指定します)。ループ回数 N は、N 回だけ後方にスキップすること、すなわちループ領域を N+1 回再生することを意味します。

明示的な再生領域を指定する場合、それは指定したオーディオバッファ内(圧縮の場合は、バッファがデコードされるサンプルの集合内)で開始および終了しなければなりません。さらに、ループ領域は再生領域の終端を越えて終了することはできません。

Xbox 360
一部のオーディオ形式では、再生領域やループ領域の有効な端点に追加の制約が存在する場合があります。たとえば XMA バッファの場合、これらの領域はデコード後のオーディオにおいて 128 サンプル境界でのみ開始または終了できます。

pBuffer ポインターは、このメソッドの呼び出し後すぐに再利用または解放できますが、pBuffer が参照する実際のオーディオデータは、バッファが XAudio2 によって完全に消費される(IXAudio2VoiceCallback::OnBufferEnd コールバックによって示されます)まで有効なまま保持しておく必要があります。

1 つのボイスには、同時に最大 XAUDIO2_MAX_QUEUED_BUFFERS 個のバッファをキューに登録できます。

SubmitSourceBuffer は、OperationSet に XAUDIO2_COMMIT_NOW を指定して XAudio2 コールバックから呼び出された場合、直ちに有効になります。

Xbox 360
このメソッドは Xbox のシステムスレッドから呼び出すことができます(他のほとんどの XAudio2 メソッドは呼び出せません)。ただし、システムスレッドから一度に送信できるソースバッファは最大 2 個です。

プラットフォーム要件

Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)
vtbl 22 HRESULT FlushSourceBuffers()

保留中のすべてのオーディオバッファをボイスのキューから削除します。

戻り値

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

解説(Remarks)

ボイスが開始されている場合、現在再生中のバッファはキューから削除されません。

FlushSourceBuffers は、ボイスが現在開始状態か停止状態かに関係なく呼び出すことができます。

削除されたバッファごとに OnBufferEnd コールバックが行われますが、その他のバッファ単位のコールバック(OnBufferStart、OnStreamEnd、OnLoopEnd)は行われません。

FlushSourceBuffers はボイスの実行状態を変更しません。そのため、呼び出し前にボイスがバッファを再生していた場合は再生を継続し、そのバッファに対するすべてのコールバックを通常どおり配信します。つまり、このバッファに対する OnBufferEnd コールバックは、削除されたバッファに対する OnBufferEnd コールバックの後に発生します。したがって、FlushSourceBuffers を呼び出す XAudio2 クライアントは、バッファが送信された順序で OnBufferEnd コールバックを受け取ることを期待できません。

現在再生中のバッファが完了しても、バッファキューの枯渇に関する警告は出力されません。クライアントがそれに続くバッファを意図的に削除したものと見なされるためです。ただし、このバッファがゼロクロッシングで終わらない場合、オーディオにポップ音が発生することがあります。特定のバッファが再生されている間にフラッシュ操作が確実に行われるようにする必要がある場合(たとえばバッファがゼロクロッシングで終わるため)は、同期的に実行されるように、コールバックから FlushSourceBuffers を呼び出す必要があります。

ボイスを停止した後に FlushSourceBuffers を呼び出し、続いてボイスに新しいデータを送信すると、ボイスの内部カウンターがすべてリセットされます。

FlushSourceBuffers を呼び出した後、(以前にバッファが送信されていた場合は)OnBufferEnd コールバックが発生するか、または IXAudio2SourceVoice::GetState が XAUDIO2_VOICE_STATE の BuffersQueued == 0 で返るまで、ボイスの状態はリセットされたとは見なされません。たとえば、ボイスを停止して FlushSourceBuffers を呼び出しても、前述の条件のいずれかが満たされるまでは、IXAudio2SourceVoice::SetSourceSampleRate(ボイスに現在キューされているバッファがないことを要求します)を直ちに呼び出すことはできません。

プラットフォーム要件

Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)
vtbl 23 HRESULT Discontinuity()

現在キューにある最後のバッファの後に、それ以上バッファが送信されないことを XAudio2 ボイスに通知します。

戻り値

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

解説(Remarks)

Discontinuity は、ボイスの再生用オーディオバッファが尽きたときに XAudio2 のデバッグビルドで通常発生する警告を抑制します。ストリームの最後のバッファには XAUDIO2_END_OF_STREAM フラグを付けてマークすることが望ましいですが、バッファがストリームの終端であることをバッファ送信後まで把握できない場合もあります。

Discontinuity の呼び出しは、送信済みの最後のバッファに対して XAUDIO2_END_OF_STREAM フラグを遡って適用することと同等であるため、このバッファが完了したときに OnStreamEnd コールバックが行われます。

Note XAudio2 は、Discontinuity の呼び出しが有効になる前にバッファキュー全体を消費し、警告を出力する場合があります。そのため、Discontinuity が警告を抑制することは保証されません。

プラットフォーム要件

Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)
vtbl 24 HRESULT ExitLoop(DWORD OperationSet)

現在のループ領域の終端に到達したときに、ボイスのループを停止します。

OperationSetDWORDin操作を遅延適用する操作セット識別子。即時適用はXAUDIO2_COMMIT_NOW。

戻り値

成功した場合は S_OK を、それ以外の場合はエラーコードを返します。XAudio2 固有のエラーコードの説明については、XAudio2 Error Codes を参照してください。

解説(Remarks)

ボイスのカーソルがループ領域内にない場合、ExitLoop は何も行いません。

プラットフォーム要件

Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)
vtbl 25 void GetState(XAUDIO2_VOICE_STATE* pVoiceState, DWORD Flags)

ボイスの現在のカーソル位置データを返します。

pVoiceStateXAUDIO2_VOICE_STATE*outボイスの状態を格納する XAUDIO2_VOICE_STATE 構造体へのポインター。
FlagsDWORDinどのボイス状態データを返すかを制御するフラグ。有効な値は 0 または XAUDIO2_VOICE_NOSAMPLESPLAYED です。既定値は 0 です。XAUDIO2_VOICE_NOSAMPLESPLAYED を指定すると、GetState はバッファ状態のみを返し、サンプラー状態は返しません。XAUDIO2_VOICE_NOSAMPLESPLAYED を指定した場合、GetState の完了に要する時間はおよそ 3 分の 1 になります。

解説(Remarks)

複数のボイスの相関のとれた位置を取得する必要がある場合(たとえば、あるボイスの特定のサンプルが再生されているときに、別のボイスのどのサンプルが再生されているかを正確に把握する場合)、クライアントは XAudio2 エンジンのコールバック内で GetState を呼び出す必要があります。これにより、呼び出しの実行中にどのボイスも進行しないことが保証されます。XAudio2 コールバックの使用については、XAudio2 Callbacks の概要を参照してください。

なお、DirectX SDK バージョンの XAUDIO2 では、GetState は Flags パラメーターを受け取りません。

プラットフォーム要件

Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)
vtbl 26 HRESULT SetFrequencyRatio(FLOAT Ratio, DWORD OperationSet)

ボイスの周波数調整比を設定します。

RatioFLOATin周波数調整比。この値は、XAUDIO2_MIN_FREQ_RATIO と、ボイスの作成時に指定した MaxFrequencyRatio パラメーター(IXAudio2::CreateSourceVoice を参照)の間でなければなりません。XAUDIO2_MIN_FREQ_RATIO は現在 0.0005 であり、ピッチを最大 11 オクターブまで下げることができます。
OperationSetDWORDinこの呼び出しを遅延バッチの一部として識別します。詳細については、XAudio2 Operation Sets の概要を参照してください。

戻り値

成功した場合は S_OK を、それ以外の場合はエラーコードを返します。エラーコードの説明については、XAudio2 Error Codes を参照してください。

解説(Remarks)

周波数調整は source frequency / target frequency(ソース周波数 / ターゲット周波数)として表されます。周波数比を変更すると、ボイスでオーディオが再生される速度が変わります。1.0 より大きい比ではオーディオが速く再生され、1.0 より小さい比では遅く再生されます。さらに、周波数比はボイス上のオーディオのピッチにも影響します。たとえば、値 1.0 はオーディオに影響を与えませんが、値 2.0 はピッチを 1 オクターブ上げ、0.5 は 1 オクターブ下げます。

有効範囲外の Ratio 値を指定して SetFrequencyRatio を呼び出した場合、このメソッドは周波数比を最も近い有効な値に設定します。また、デバッグビルドでは警告が生成されます。

Note IXAudio2SourceVoice::GetFrequencyRatio は常にボイスの実際の現在の周波数比を返します。ただし、これは直近の IXAudio2SourceVoice::SetFrequencyRatio 呼び出しで設定した比と一致しない場合があります。実際の比が変更されるのは、IXAudio2SourceVoice::SetFrequencyRatio の呼び出し(または、IXAudio2SourceVoice::SetFrequencyRatio を遅延操作 ID を指定して呼び出した場合は、対応する IXAudio2::CommitChanges の呼び出し)の後にオーディオエンジンが次に実行されるときのみです。

プラットフォーム要件

Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)
vtbl 27 void GetFrequencyRatio(FLOAT* pRatio)

ボイスの周波数調整比を返します。

pRatioFLOAT*out成功した場合、現在の周波数調整比を返します。

解説(Remarks)

GetFrequencyRatio は常にボイスの実際の現在の周波数比を返します。ただし、これは直近の IXAudio2SourceVoice::SetFrequencyRatio 呼び出しで設定した比と一致しない場合があります。実際の比が変更されるのは、IXAudio2SourceVoice::SetFrequencyRatio の呼び出し(または、IXAudio2SourceVoice::SetFrequencyRatio を遅延操作 ID を指定して呼び出した場合は、対応する IXAudio2::CommitChanges の呼び出し)の後にオーディオエンジンが次に実行されるときのみです。

周波数比については、IXAudio2SourceVoice::SetFrequencyRatio を参照してください。

プラットフォーム要件

Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)
vtbl 28 HRESULT SetSourceSampleRate(DWORD NewSourceSampleRate)

ボイスの作成時に指定したサンプルレートとは異なるサンプルレートでソースデータを消費するように、ボイスを再構成します。

NewSourceSampleRateDWORDinボイスが送信されたデータを処理する新しいサンプルレート。有効なサンプルレートは 1kHz から 200kHz です。

戻り値

成功した場合は S_OK を、それ以外の場合はエラーコードを返します。エラーコードの説明については、XAudio2 Error Codes を参照してください。

解説(Remarks)

SetSourceSampleRate メソッドは、ボイスがさまざまなサンプルレートのサウンドを再生できるようにすることで、XAudio2 ボイスの再利用をサポートします。SetSourceSampleRate を使用するには、ボイスが XAUDIO2_VOICE_NOPITCH フラグまたは XAUDIO2_VOICE_NOSRC フラグなしで作成されており、かつ現在キューに登録されたバッファがない状態でなければなりません。

SetSourceSampleRate の典型的な用途は、ボイスプーリングのサポートです。たとえば、ボイスプーリングをサポートするために、アプリケーションは使用が見込まれるすべてのボイスを事前に作成しておきます。新しいサウンドを再生するたびに、アプリケーションは非アクティブなボイスを選択するか、すべてのボイスが使用中の場合は最も重要度の低いボイスを選び、そのボイスに対して新しいサウンドのサンプルレートで SetSourceSampleRate を呼び出します。ボイスに対して SetSourceSampleRate を呼び出した後、アプリケーションは新しいサンプルレートでのバッファの送信と再生を直ちに開始できます。これにより、アプリケーションはゲームプレイ中にボイスを頻繁に作成および破棄するオーバーヘッドを回避できます。

プラットフォーム要件

Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数: 
#define global IID_IXAudio2SourceVoice "{}"
#usecom global IXAudio2SourceVoice IID_IXAudio2SourceVoice "{}"
#comfunc global IXAudio2SourceVoice_Start                19 int,int
#comfunc global IXAudio2SourceVoice_Stop                 20 int,int
#comfunc global IXAudio2SourceVoice_SubmitSourceBuffer   21 var,var
#comfunc global IXAudio2SourceVoice_FlushSourceBuffers   22
#comfunc global IXAudio2SourceVoice_Discontinuity        23
#comfunc global IXAudio2SourceVoice_ExitLoop             24 int
#comfunc global IXAudio2SourceVoice_GetState             25 var,int
#comfunc global IXAudio2SourceVoice_SetFrequencyRatio    26 float,int
#comfunc global IXAudio2SourceVoice_GetFrequencyRatio    27 var
#comfunc global IXAudio2SourceVoice_SetSourceSampleRate  28 int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。