XDspSubmitCommandWithEnvelope
指定された XDSP ストリームに対して、1 つのコマンドをハードウェア キューに送信します。この API は 1 つのコマンドをハードウェアに送信する XDspSubmitCommand と似ていますが、インパルス応答フィルターの各ブロックに対するゲイン値を含む追加のパラメーター envelopeBuffer を受け取る点が異なります。これらのゲイン値は、畳み込み中にインパルス応答に適用されます。エンベロープを使用したい場合、この API を有効なエンベロープ バッファーへのポインターで呼び出す必要があります。エンベロープ バッファーが不要になるまで有効な状態を保つのは、呼び出し元の責任です。エンベロープの使用を停止するには、XDspSubmitCommand を使用するか、envelopeBuffer に nullptr を指定して XDspSubmitCommandWithEnvelope を使用します。 この API は、XDspProcessType::Convolution 用にアクティブ化されたストリームに対してのみ使用してください。
構文
パラメーター
handle _In_型: XDspStreamHandle 有効な XDSP ストリーム ハンドル。 command _In_
型: XDspCommand* XDspCommand 構造体へのポインター。 envelopeBuffer _In_
型: float* 畳み込み中に適用されるインパルス応答フィルターの各ブロックのゲイン値へのポインター。
このバッファーは、XDspConnect または XDspConnectWithMaximumStreamLimit によって登録されたメモリの一部でなければならず、16 バイト境界に整列している必要があります。このバッファーはハードウェアによって使用されるため、このバッファーを使用するすべてのコマンドが完了して応答が取得されるまで、変更したり解放したりすることはできません。 エンベロープ バッファー内のゲイン値の数は、インパルス応答フィルター内のブロック数以上でなければならず、次のように計算されます。
uint32_t IRLengthInComplexValues = XDspActivationParameters::impulseResponseLengthInFloats/2;
uint32_t IRLengthInBlocks = IRLengthInComplexValues/ XDspActivationParameters::blockFrameCount;
uint32_t envelopeSize = ((IRLengthInBlocks * sizeof(float) + 15) & ~(0xF)) / sizeof(float); このバッファーはインパルス応答のサイズに従います。ステレオ インパルス応答の場合、左チャネル インパルス応答の後に右チャネル インパルス応答が続くのと同じように、左チャネル全体のゲイン値の後に右チャネル全体のゲイン値が続きます。 モノラル インパルス応答の場合、同じゲイン値がステレオ入力信号の左右両方のチャネルに適用されます。このバッファーの最小サイズは、モノラル インパルス応答フィルターの場合は 8 個の float 値、ステレオ インパルス応答フィルターの場合は 16 個の float 値です。 commandSequence _Out_
型: uint32_t* コマンド シーケンス値を返す
uint32_t へのポインター。詳細については、解説 セクションを参照してください。
戻り値
型: HRESULT メソッドが成功した場合は S_OK を返します。失敗した場合は次のコードを返します (一部の一覧):解説
この呼び出しは、リソースを割り当てたりデータを処理したりせず、コマンドをハードウェア サーバーに送信するだけなので、高速です。 畳み込み処理には ‘n’ 個のステージがあり、エンベロープの切り替えやオン/オフは最初のステージでのみ行うことができます。つまり、エンベロープ効果は即時ではなく、いくつかの送信分だけ遅延する場合があります。 エンベロープ パラメーターを無効にするには、XDspSubmitCommand または null の envelopeBuffer を指定した XDspSubmitCommandWithEnvelope を呼び出す必要があります。 この呼び出しは、後でコマンド結果の準備ができた時点を追跡するために、コマンド シーケンス値 commandSequence を返すuint32_t へのポインターも受け取ります。この数値は、セッションが開始され、XDspActivate が呼び出された後、正常に送信されたコマンドの合計数を表します。この数値は最初のコマンドで 1 になり、その後の正常な XDspSubmitCommandWithEnvelope または XDspSubmitCommand 呼び出しごとに 1 ずつ増加します。
ハードウェア サーバーが不良状態にある場合、XDspSubmitCommandWithEnvelope は XDSP_E_DEVICE_FATAL_ERROR エラー コードを返します。この時点で、失敗状態にある XDSP ストリームに対してさらにコマンドを送信することはできません。ストリームの XDspStatus にも同じエラーが示されます。影響を受ける XDSP ストリームは、XDspStatus をチェックしてハードウェアが送信されたすべてのコマンドを処理するのを待機し、すべてのコマンドが処理されたら XDspDeactivate を使用して非アクティブ化する必要があります。他の XDSP ストリームは影響を受けず、ハードウェアはそれらのコマンドの処理を続行します。
要件
ヘッダー: XDspAudio.h ライブラリ: Chad.lib サポートされるプラットフォーム: XBOX Series X|S概念ドキュメント
関連項目
XDSPXdspSubmitCommand
XDSP エラー
XDSP API を使用した単一ストリーム畳み込みの概要
XDSP API を使用したエンベロープ付き単一ストリーム畳み込みの概要 XDSP API を使用した単一ストリーム FFT/IFFT の概要