> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XDspSubmitCommandWithEnvelope

> XDspSubmitCommandWithEnvelope

# XDspSubmitCommandWithEnvelope

指定された XDSP ストリームに対して、1 つのコマンドをハードウェア キューに送信します。この API は 1 つのコマンドをハードウェアに送信する XDspSubmitCommand と似ていますが、インパルス応答フィルターの各ブロックに対するゲイン値を含む追加のパラメーター envelopeBuffer を受け取る点が異なります。これらのゲイン値は、畳み込み中にインパルス応答に適用されます。\
エンベロープを使用したい場合、この API を有効なエンベロープ バッファーへのポインターで呼び出す必要があります。エンベロープ バッファーが不要になるまで有効な状態を保つのは、呼び出し元の責任です。エンベロープの使用を停止するには、XDspSubmitCommand を使用するか、envelopeBuffer に nullptr を指定して XDspSubmitCommandWithEnvelope を使用します。
この API は、XDspProcessType::Convolution 用にアクティブ化されたストリームに対してのみ使用してください。

## 構文

```cpp theme={null}
HRESULT XDspSubmitCommandWithEnvelope(  
         XDspStreamHandle handle,  
         XDspCommand* command,  
         float* envelopeBuffer,
         uint32_t* commandSequence  
)  
```

### パラメーター

*handle*   \_In\_\
型: [XDspStreamHandle](/reference/audio/xdspaudio/handles/xdspstreamhandle)

有効な XDSP ストリーム ハンドル。

*command*   \_In\_\
型: [XDspCommand\*](/reference/audio/xdspaudio/structs/xdspcommand)

[XDspCommand](/reference/audio/xdspaudio/structs/xdspcommand) 構造体へのポインター。

*envelopeBuffer*   \_In\_\
型: float\*

畳み込み中に適用されるインパルス応答フィルターの各ブロックのゲイン値へのポインター。\
このバッファーは、[XDspConnect](/reference/audio/xdspaudio/functions/xdspconnect) または [XDspConnectWithMaximumStreamLimit](/reference/audio/xdspaudio/functions/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 を返します。失敗した場合は次のコードを返します (一部の一覧):

| 戻りコード                         | 説明                                                                                                            |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
| E\_INVALIDARG                 | 1 つ以上の引数が無効です。                                                                                                |
| XDSP\_E\_QUEUE\_FULL          | この呼び出しは、ストリームとハードウェア サーバーが最大処理容量に達した場合に XDSP\_E\_QUEUE\_FULL を返します。追加のコマンドを送信する前に、ハードウェアがコマンドを処理するのを待機してください。 |
| XDSP\_E\_DEVICE\_FATAL\_ERROR | ハードウェア サーバーが不良状態にある場合、**XDspSubmitCommandWithEnvelope** は XDSP\_E\_DEVICE\_FATAL\_ERROR エラー コードを返します。         |

## 解説

この呼び出しは、リソースを割り当てたりデータを処理したりせず、コマンドをハードウェア サーバーに送信するだけなので、高速です。

畳み込み処理には *'n'* 個のステージがあり、エンベロープの切り替えやオン/オフは最初のステージでのみ行うことができます。つまり、エンベロープ効果は即時ではなく、いくつかの送信分だけ遅延する場合があります。

エンベロープ パラメーターを無効にするには、**XDspSubmitCommand** または null の envelopeBuffer を指定した **XDspSubmitCommandWithEnvelope** を呼び出す必要があります。

この呼び出しは、後でコマンド結果の準備ができた時点を追跡するために、コマンド シーケンス値 *commandSequence* を返す `uint32_t` へのポインターも受け取ります。この数値は、セッションが開始され、[XDspActivate](/reference/audio/xdspaudio/functions/xdspactivate) が呼び出された後、正常に送信されたコマンドの合計数を表します。この数値は最初のコマンドで 1 になり、その後の正常な **XDspSubmitCommandWithEnvelope** または [XDspSubmitCommand](/reference/audio/xdspaudio/functions/xdspsubmitcommand) 呼び出しごとに 1 ずつ増加します。

ハードウェア サーバーが不良状態にある場合、**XDspSubmitCommandWithEnvelope** は XDSP\_E\_DEVICE\_FATAL\_ERROR エラー コードを返します。この時点で、失敗状態にある XDSP ストリームに対してさらにコマンドを送信することはできません。ストリームの [XDspStatus](/reference/audio/xdspaudio/structs/xdspstatus) にも同じエラーが示されます。影響を受ける XDSP ストリームは、[XDspStatus](/reference/audio/xdspaudio/structs/xdspstatus) をチェックしてハードウェアが送信されたすべてのコマンドを処理するのを待機し、すべてのコマンドが処理されたら [XDspDeactivate](/reference/audio/xdspaudio/functions/xdspdeactivate) を使用して非アクティブ化する必要があります。他の XDSP ストリームは影響を受けず、ハードウェアはそれらのコマンドの処理を続行します。

## 要件

**ヘッダー:** XDspAudio.h

**ライブラリ:** Chad.lib

**サポートされるプラットフォーム:** XBOX Series X|S

## 概念ドキュメント

* [XDSP エンベロープの概要](/build/console-features/audio/overviews/xdsp-overview-enveloping)
* [XDSP API を使用したエンベロープ付き単一ストリーム畳み込みの概要](/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope)
* [XDSP の概要](/build/console-features/audio/overviews/xdsp-overview)

## 関連項目

[XDSP](/reference/audio/xdspaudio/xdspaudio_members)\
[XdspSubmitCommand](/reference/audio/xdspaudio/functions/xdspsubmitcommand)\
[XDSP エラー](/reference/audio/xdspaudio/enums/xdsperrors)\
[XDSP API を使用した単一ストリーム畳み込みの概要](/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution)\
[XDSP API を使用したエンベロープ付き単一ストリーム畳み込みの概要](/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope)
[XDSP API を使用した単一ストリーム FFT/IFFT の概要](/build/console-features/audio/overviews/xdsp-overview-single-stream-fft-ifft)


## Related topics

- [XDspSubmitCommand](/ja-jp/reference/audio/xdspaudio/functions/xdspsubmitcommand.md)
- [XDSP エンベロープ処理の概要](/ja-jp/build/console-features/audio/overviews/xdsp-overview-enveloping.md)
- [XDSP の概要](/ja-jp/build/console-features/audio/overviews/xdsp-overview.md)
- [XDSP API を使用したエンベロープ付きシングル ストリーム コンボリューション](/ja-jp/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope.md)
- [XDSP audio](/ja-jp/reference/audio/xdspaudio/xdspaudio_members.md)