Skip to main content
このトピックでは、Microsoft Game Development Kit (GDK) に含まれているサンプルの 1 つを使用して、XBOX Series X デバイスでハードウェア コンボリューション リバーブを使用する方法についての想定されるコード フローを説明します。

ハードウェアの接続と起動

XDspConnect または XDspConnectWithMaximumStreamLimit を介して、ハードウェア アクセラレーション ユニットとの接続を確立する必要があります。呼び出し元は、次のパラメーターを使用して接続の要件を設定します。
  1. baseBuffer - ハードウェアに渡される入力、出力、エンベロープ バッファー、および/またはブロック マルチプライヤー バッファーを保持するのに十分なユーザー割り当てメモリへのポインター。このメモリは、次の属性で XMemAlloc を介して割り当てる必要があります。XALLOC_MEMTYPE_PHYSICAL_CACHEABLEXALLOC_PAGESIZE_64KBXALLOC_ALIGNMENT_64K。これらの属性は、以下の例に示すように MAKE_XALLOC_ATTRIBUTES() を使用して設定する必要があります。このメモリは、XDspDisconnect の呼び出しが成功するまで解放してはなりません。このバッファーのサイズは少なくとも 64KB である必要があります。
  2. baseBufferLength - baseBuffer の長さ (バイト単位)。このバッファーは少なくとも 64KB で 500 MB 以下である必要があります。
  3. aggregateImpulseResponseInSeconds - XDspProcessType::ConvolutionXDspActivate を使用して同時にアクティブ化されるすべての個別のインパルス応答の全体的な持続時間を表します。この値が 0 の場合、XDspProcessType::Convolution を持つストリームをアクティブ化することはできません。
  4. handle - この呼び出しによって返されるハンドルを保持する XDspClientHandle へのポインター。
呼び出しが成功すると、baseBuffer を呼び出し元が使用して、XDspCommand パラメーターを介してストリームの入力データを渡し、出力データを取得できます。XDspCommand で渡されるすべてのバッファーは 16 バイトにアラインされている必要があります。以下の簡単なバッファー マネージャーの例を、入力および出力バッファーの管理に使用できます。
各ストリームのエンベロープ バッファーは、入力および出力バッファーと同様に XDspConnect または XDspConnectWithMaximumStreamLimit に渡される baseBuffer の一部である必要があります。各エンベロープ バッファーの長さは、次のように計算できます。
メモリを割り当てて接続を確立する最初のステップのコード例を以下に示します。アクティブにできるストリーム数が 256 未満の場合、内部メモリ使用量を減らすために、XDspConnect の代わりに XDspConnectWithMaximumStreamLimit を使用できます。
ここで、XMemAllocAttributes は上記の属性を表します。次のコードは、aggregateImpulseResponse を 32 秒に設定します。

ストリームのアクティブ化と非アクティブ化

デバイスとの接続が確立された後、呼び出し元は、コンボリューション、FFT、または IFFT を起動するためにストリーム アクティブ化コマンドを送信する必要があります。呼び出し元は、XDspActivationParametersXDspProcessType、ブロック フレーム カウント、チャネル カウント、float 単位のインパルス応答の長さ、および周波数領域のインパルス応答データへのポインターを指定する必要があります。モノラルまたはステレオのストリームのみが許可されます。XDspProcessType::ForwardFourierTransform および XDspProcessType::inverseFourierTransform の場合、XDspActivationParameters::impulseResponse は nullptr で、XDspActivationParameters::impulseResponseLengthInFloats = 0 である必要があります。XDspActivationOptions は適切に設定してください。 コンボリューション用に 1 つのストリームをアクティブ化するコードを以下に示します。
XDspActivate は、パラメーターの 1 つとして XDspStatus バッファーを返します。この XDspStatus バッファーを使用して、このストリームに対してハードウェアによって処理されたコマンドの状態を確認してください。アクティブ化の結果を受け取った後、呼び出し元は Convolution/FFT/IFFT 用にデータを送信できます。これは、XDspSubmitCommand または XDspSubmitCommandWithEnvelope API を使用して行う必要があります。各呼び出しで、呼び出し元は以下を行う必要があります。
  1. 入力バッファーに正確に blockFrameCount のデータを入れます。
  2. XDspCommand に適切な値と、16 バイトにアラインされた入力および出力バッファーを入れます。
  3. XDspSubmitCommand を呼び出して、ハードウェアにコマンドを送信します。この関数は、ハードウェアに送信されたコマンドの数を追跡するために使用できるコマンド シーケンス番号を返します。
  4. エンベロープを適用するには、インパルス応答フィルターの各ブロックのゲイン値でエンベロープ バッファーを埋め、XDspSubmitCommandWithEnvelope を呼び出し、エンベロープ処理が不要になるか、エンベロープを変更する必要があるまで、同じエンベロープ バッファーでこの呼び出しを続けます。
  5. エンベロープ処理が不要になったら、envelopeBuffer を nullptr にして XDspSubmitCommand または XDspSubmitCommandWithEnvelope を呼び出します。envelopeBuffer を nullptr にした XDspSubmitCommandWithEnvelopeXDspSubmitCommand と同等である点に注意してください。
  6. エンベロープを切り替える際、ハードウェアがそのエンベロープを使用してすべてのコマンドを処理し、結果がピックアップされた場合にのみ、現在の envelopeBuffer を次のエンベロープ用に更新できます。そうでない場合は、別のエンベロープ バッファーを使用してください。
以下のコード スニペットは、インパルス応答フィルターの各ブロックのゲイン値でエンベロープ バッファーを埋める例を示しています。ここでは、1.0f で始まり線形に減少する、インパルス応答フィルターの前半のブロックに対するゲイン値のみを使用し、後半は 0.0f のゲイン値で埋める方法を示しています。ステレオ インパルス応答フィルターの場合、左チャネルの全体フィルターに続いて右チャネルの全体フィルターが続きます。ステレオ インパルス応答フィルターのエンベロープ バッファーは同じパターンに従い、左チャネル全体のゲイン値の後に右チャネル全体のゲイン値が続きます。エンベロープ バッファーのサイズの計算については、XDSP API を使用したエンベロープ処理の概要を参照してください。
以下のコード スニペットは、有効な envelopeBufferXDspSubmitCommandWithEnvelope を呼び出してエンベロープを適用する例を示しています。これは、追加の envelopeBuffer パラメーターを渡すことを除いて、XDspSubmitCommand を使用してコマンドを送信するスニペットと同じです。エンベロープが不要になるまでこれを繰り返す必要があります。その時点で、XDspSubmitCommand または envelopeBuffer を nullptr にした XDspSubmitCommandWithEnvelope のいずれかを呼び出す必要があります。
次に、以下のようにしてハードウェアに送信されたコマンドの状態を確認するため XDspStatus をチェックできます。
ストリーム内のパケットが処理されるか、ハードウェアが XDspStatus の結果にエラーを返すと、XDspDeactivate を呼び出す必要があります。
このストリーム用に送信されたすべてのコマンドの処理がハードウェアで完了していない場合、XDspDeactivateXDSP_E_PENDING_RESULTS を返します。

終了

XDspDeactivate が成功した後、呼び出し元は割り当てられたすべてのリソースを解放するために XDspDisconnect を呼び出してオーディオ ハードウェア アクセラレーション ユニットから切断する必要があります。すべてのストリームが非アクティブ化されていない場合、XDspDisconnectXDSP_E_NOT_ALL_HANDLES_DEACTIVATED エラーを返します。

リファレンス API ドキュメント

関連項目

XDSP の概要 XDSP API を使用したエンベロープ処理の概要
最終更新日 2026年8月24日