ホーム › Media.Audio.XAudio2 › IXAPO

IXAPO

COM

📘 Microsoft Learn (日本語) · English

IIDa410b984-9839-4819-a0be-2856ae6b3adb継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

XAudio2 のエフェクトチェーンで使用されるオーディオ処理オブジェクト (Audio Processing Object) のインターフェイスです。

解説(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 3 HRESULT GetRegistrationProperties(XAPO_REGISTRATION_PROPERTIES** ppRegistrationProperties)

XAPO の登録プロパティを返します。

ppRegistrationProperties

XAPO_REGISTRATION_PROPERTIES**

out

XAPO の作成時に使用された登録プロパティを格納する XAPO_REGISTRATION_PROPERTIES 構造体へのポインターを受け取ります。構造体を解放するには XAPOFree を使用します。

戻り値

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

解説(Remarks)

プラットフォーム要件

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

vtbl 4 HRESULT IsInputFormatSupported(WAVEFORMATEX* pOutputFormat, WAVEFORMATEX* pRequestedInputFormat, WAVEFORMATEX** ppSupportedInputFormat)

指定された出力フォーマットに対して、特定の入力フォーマットがサポートされているかどうかを照会します。

pOutputFormat	WAVEFORMATEX*	in	出力フォーマット。
pRequestedInputFormat	WAVEFORMATEX*	in	サポートされているかどうかを確認する入力フォーマット。
ppSupportedInputFormat	WAVEFORMATEX**	outoptional	NULL でなく、指定された出力フォーマットに対して入力フォーマットがサポートされていない場合、ppSupportedInputFormat はサポートされる最も近い入力フォーマットへのポインターを返します。返された構造体を解放するには XAPOFree を使用します。

戻り値

フォーマットの組み合わせがサポートされている場合は S_OK を返します。フォーマットの組み合わせがサポートされていない場合は XAPO_E_FORMAT_UNSUPPORTED を返します。

解説(Remarks)

IXAPO::IsOutputFormatSupported メソッドと IsInputFormatSupported メソッドを使用すると、XAPO は処理可能なオーディオフォーマットを示すことができます。要求されたフォーマットがサポートされていない場合、XAPO はサポートする最も近いフォーマットを返す必要があります。最も近いフォーマットは、フレームレート、ビット深度、チャンネル数の順に重要度を考慮して決定する必要があります。IsInputFormatSupported の動作は XAPO の内部状態に基づいて変化してもかまいませんが、IXAPO::LockForProcess メソッドと IXAPO::UnlockForProcess メソッドの呼び出しの間は動作が一定に保たれる必要があります。

プラットフォーム要件

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

vtbl 5 HRESULT IsOutputFormatSupported(WAVEFORMATEX* pInputFormat, WAVEFORMATEX* pRequestedOutputFormat, WAVEFORMATEX** ppSupportedOutputFormat)

指定された入力フォーマットに対して、特定の出力フォーマットがサポートされているかどうかを照会します。

pInputFormat	WAVEFORMATEX*	in	入力フォーマット。
pRequestedOutputFormat	WAVEFORMATEX*	in	サポートされているかどうかを確認する出力フォーマット。
ppSupportedOutputFormat	WAVEFORMATEX**	outoptional	NULL でなく、指定された入力フォーマットに対して出力フォーマットがサポートされていない場合、ppSupportedOutputFormat はサポートされる最も近い出力フォーマットへのポインターを返します。返された構造体を解放するには XAPOFree を使用します。

戻り値

解説(Remarks)

IXAPO::IsInputFormatSupported メソッドと IsOutputFormatSupported メソッドを使用すると、XAPO は処理可能なオーディオフォーマットを示すことができます。要求されたフォーマットがサポートされていない場合、XAPO はサポートする最も近いフォーマットを返す必要があります。最も近いフォーマットは、フレームレート、ビット深度、チャンネル数の順に重要度を考慮して決定する必要があります。IsOutputFormatSupported の動作は XAPO の内部状態に基づいて変化してもかまいませんが、IXAPO::LockForProcess メソッドと IXAPO::UnlockForProcess メソッドの呼び出しの間は動作が一定に保たれる必要があります。

プラットフォーム要件

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

vtbl 6 HRESULT Initialize(void* pData, DWORD DataByteSize)

エフェクト固有の初期化を実行します。

pData	void*	inoptional	エフェクト固有の初期化パラメーター。DataByteSize が 0 の場合は NULL でもかまいません。
DataByteSize	DWORD	in	pData のサイズ (バイト単位)。pData が NULL の場合は 0 でもかまいません。

戻り値

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

解説(Remarks)

pData の内容は各 XAPO によって定義されます。不変のパラメーター (XAPO の存続期間中一定であるもの) は、このメソッドで設定する必要があります。一度初期化された XAPO を再度初期化することはできません。XAPO は、エフェクトチェーンの一部として XAudio2 に渡す前に初期化しておく必要があります。

メモ XAudio2 はこのメソッドを呼び出しません。XAPO を XAudio2 に渡す前に、クライアントが呼び出す必要があります。

プラットフォーム要件

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

vtbl 7 void Reset()

フレーム履歴に依存する変数をリセットします。

解説(Remarks)

入力フォーマットや出力フォーマットなどの定数化・ロックされたパラメーターは変更されません。IXAPOParameters::SetParameters によって設定された変数も変更されません。

たとえば、ディレイを持つエフェクトは、このメソッド内でディレイラインをゼロにクリアする必要がありますが、XAPO は一定の入力・出力構成でロックされたままであるため、何も再割り当てすべきではありません。

XAudio2 は、XAPO がロックされている場合にのみこのメソッドを呼び出します。

このメソッドはリアルタイムスレッドから呼び出されるため、ブロックしてはなりません。

プラットフォーム要件

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

vtbl 8 HRESULT LockForProcess(DWORD InputLockedParameterCount, XAPO_LOCKFORPROCESS_PARAMETERS* pInputLockedParameters, DWORD OutputLockedParameterCount, XAPO_LOCKFORPROCESS_PARAMETERS* pOutputLockedParameters)

XAPO の入力・出力構成をロックするために XAudio2 から呼び出されます。これにより、リアルタイムスレッドで Process が呼び出される前に、XAPO が最終的な初期化を実行できるようになります。

InputLockedParameterCount	DWORD	in	ppInputLockedParameters の要素数。CXAPOBase::CXAPOBase に渡された XAPO_REGISTRATION_PROPERTIES.MinInputBufferCount と XAPO_REGISTRATION_PROPERTIES.MaxInputBufferCount の値の範囲内である必要があります。
pInputLockedParameters	XAPO_LOCKFORPROCESS_PARAMETERS*	inoptional	入力用の XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS 構造体の配列。InputLockedParameterCount が 0 の場合、pInputLockedParameters は NULL でもかまいません。それ以外の場合は InputLockedParameterCount 個の要素を持つ必要があります。
OutputLockedParameterCount	DWORD	in	ppOutputLockedParameters の要素数。CXAPOBase::CXAPOBase に渡された XAPO_REGISTRATION_PROPERTIES.MinOutputBufferCount と XAPO_REGISTRATION_PROPERTIES.MaxOutputBufferCount の値の範囲内である必要があります。XAPO_REGISTRATION_PROPERTIES.Flags に XAPO_FLAG_BUFFERCOUNT_MUST_MATCH フラグが指定されている場合、OutputLockedParameterCount は InputLockedParameterCount と等しくなければなりません。
pOutputLockedParameters	XAPO_LOCKFORPROCESS_PARAMETERS*	inoptional	出力用の XAPO_LOCKFORPROCESS_BUFFER_PARAMETERS 構造体の配列。OutputLockedParameterCount が 0 の場合、pOutputLockedParameters は NULL でもかまいません。それ以外の場合は OutputLockedParameterCount 個の要素を持つ必要があります。

戻り値

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

解説(Remarks)

一度ロックされると、入力・出力構成やその他のロックされたパラメーターは、UnLockForProcess が呼び出されるまで一定に保たれます。XAPO がロックされた後は、UnLockForProcess 関数が呼び出されるまで、LockForProcess をさらに呼び出しても効果はありません。

XAPO は、IsInputFormatSupported メソッドと IsOutputFormatSupported メソッドの実装を通じて、サポートする具体的なフォーマットを示します。XAPO は、入力・出力構成がサポートされていること、および必要なエフェクト固有の初期化が完了していることを確認する必要があります。このメソッドを呼び出す前に、必要に応じて IsInputFormatSupported、IsOutputFormatSupported、Initialize の各メソッドを使用してください。

Process はノンブロッキングなメソッドであるため、Process に必要なすべての内部メモリバッファーは LockForProcess で割り当てる必要があります。

Process が LockForProcess の正常終了より前に呼び出されることはありません。

LockForProcess は XAudio2 によって直接呼び出されるものであり、クライアントコードから呼び出してはなりません。

プラットフォーム要件

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

vtbl 9 void UnlockForProcess()

LockForProcess メソッドで割り当てられた変数を解放します。

解説(Remarks)

XAPO インスタンスのロックを解除すると、異なる入力・出力フォーマットで再利用できるようになります。

プラットフォーム要件

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

vtbl 10 void Process(DWORD InputProcessParameterCount, XAPO_PROCESS_BUFFER_PARAMETERS* pInputProcessParameters, DWORD OutputProcessParameterCount, XAPO_PROCESS_BUFFER_PARAMETERS* pOutputProcessParameters, BOOL IsEnabled)

指定された入力バッファーと出力バッファーに対して、XAPO のデジタル信号処理 (DSP) コードを実行します。

InputProcessParameterCount	DWORD	in	pInputProcessParameters の要素数。メモ XAudio2 は現在、1 つの入力ストリームと 1 つの出力ストリームのみをサポートしています。
pInputProcessParameters	XAPO_PROCESS_BUFFER_PARAMETERS*	inoptional	XAPO_PROCESS_BUFFER_PARAMETERS 構造体の入力配列。
OutputProcessParameterCount	DWORD	in	pOutputProcessParameters の要素数。メモ XAudio2 は現在、1 つの入力ストリームと 1 つの出力ストリームのみをサポートしています。
pOutputProcessParameters	XAPO_PROCESS_BUFFER_PARAMETERS*	inoutoptional	XAPO_PROCESS_BUFFER_PARAMETERS 構造体の出力配列。入力時、XAPO_PROCESS_BUFFER_PARAMETERS. ValidFrameCount の値は、XAPO が出力バッファーに書き込むべきフレーム数を示します。出力時、XAPO_PROCESS_BUFFER_PARAMETERS. ValidFrameCount の値は、実際に書き込まれたフレーム数を示します。
IsEnabled	BOOL	in	通常の処理を行う場合は TRUE、スルー処理を行う場合は FALSE を指定します。詳細については「解説」を参照してください。

解説(Remarks)

この関数はリアルタイムオーディオ処理スレッドから呼び出されるため、実装ではブロックしてはなりません。

フォーマットの検証やメモリの割り当てなど、遅延を引き起こす可能性のあるすべてのコードは、リアルタイムオーディオ処理スレッドから呼び出されない IXAPO::LockForProcess メソッドに配置する必要があります。

インプレース処理では、pInputProcessParameters パラメーターが pOutputProcessParameters と必ずしも同一になるわけではありません。むしろ、それらの pBuffer メンバーが同じメモリを指すことになります。

インプレース XAPO では複数の入力バッファーと出力バッファーを使用できますが、入力バッファー数は出力バッファー数と等しくなければなりません。複数の入力バッファーと出力バッファーを使用するインプレース処理では、XAPO は入力バッファー数が出力バッファー数に等しいものとみなすことができます。

XAPO は、必要に応じて出力バッファーへ書き込むだけでなく、出力ストリームのバッファーフラグと有効フレーム数を設定する責任があります。

IsEnabled が FALSE の場合、XAPO は指定された入力・出力バッファーに対して通常の処理を適用してはなりません。代わりに、可能な限り変更を加えずに入力から出力へデータを渡す必要があります。フォーマット変換を行うエフェクトは、その処理を継続してください。エフェクトは、通常処理とスルー処理の切り替え時に信号へ不連続が生じないようにする必要があります。

Process メソッドを記述する際は、XAudio2 のオーディオデータがインターリーブされている点に注意することが重要です。これは、特定のサンプル番号について各チャンネルのデータが隣接して配置されることを意味します。たとえば、4 チャンネルの wave が XAudio2 ソースボイスで再生されている場合、オーディオデータはチャンネル 0 のサンプル、チャンネル 1 のサンプル、チャンネル 2 のサンプル、チャンネル 3 のサンプル、続いてチャンネル 0、1、2、3 の次のサンプル、というように並びます。

プラットフォーム要件

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

vtbl 11 DWORD CalcInputFrames(DWORD OutputFrameCount)

指定された数の出力フレームを生成するために必要な入力フレーム数を返します。

OutputFrameCount

DWORD

必要な出力フレーム数。

戻り値

必要な入力フレーム数を返します。

解説(Remarks)

XAudio2 は、指定された数の出力フレームを生成するために XAPO が必要とする入力バッファーのサイズを判断するために、このメソッドを呼び出します。このメソッドは、XAPO がロックされている間に一度だけ呼び出せば十分です。CalcInputFrames は、XAPO がロックされている場合にのみ XAudio2 から呼び出されます。

この関数はリアルタイムオーディオ処理スレッドから呼び出される可能性があるため、ブロックしてはなりません。

プラットフォーム要件

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

vtbl 12 DWORD CalcOutputFrames(DWORD InputFrameCount)

指定された数の入力フレームから生成される出力フレーム数を返します。

InputFrameCount

DWORD

入力フレーム数。

戻り値

生成される出力フレーム数を返します。

解説(Remarks)

XAudio2 は、一定数の入力フレームに対して XAPO がどれだけ大きな出力バッファーを必要とするかを判断するために、このメソッドを呼び出します。CalcOutputFrames は、XAPO がロックされている場合にのみ XAudio2 から呼び出されます。

この関数はリアルタイムオーディオ処理スレッドから呼び出される可能性があるため、ブロックしてはなりません。

プラットフォーム要件

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_IXAPO "{A410B984-9839-4819-A0BE-2856AE6B3ADB}"
#usecom global IXAPO IID_IXAPO "{}"
#comfunc global IXAPO_GetRegistrationProperties  3 var
#comfunc global IXAPO_IsInputFormatSupported     4 var,var,var
#comfunc global IXAPO_IsOutputFormatSupported    5 var,var,var
#comfunc global IXAPO_Initialize                 6 sptr,int
#comfunc global IXAPO_Reset                      7
#comfunc global IXAPO_LockForProcess             8 int,var,int,var
#comfunc global IXAPO_UnlockForProcess           9
#comfunc global IXAPO_Process                    10 int,var,int,var,int
#comfunc global IXAPO_CalcInputFrames            11 int
#comfunc global IXAPO_CalcOutputFrames           12 int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IXAPO "{A410B984-9839-4819-A0BE-2856AE6B3ADB}"
#usecom global IXAPO IID_IXAPO "{}"
#comfunc global IXAPO_GetRegistrationProperties  3 sptr
#comfunc global IXAPO_IsInputFormatSupported     4 sptr,sptr,sptr
#comfunc global IXAPO_IsOutputFormatSupported    5 sptr,sptr,sptr
#comfunc global IXAPO_Initialize                 6 sptr,int
#comfunc global IXAPO_Reset                      7
#comfunc global IXAPO_LockForProcess             8 int,sptr,int,sptr
#comfunc global IXAPO_UnlockForProcess           9
#comfunc global IXAPO_Process                    10 int,sptr,int,sptr,int
#comfunc global IXAPO_CalcInputFrames            11 int
#comfunc global IXAPO_CalcOutputFrames           12 int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。