> ## 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 串流提交一個命令至硬體佇列。此 API 類似於 XDspSubmitCommand,會將一個命令提交至硬體,差別在於它多接受一個參數 envelopeBuffer,其中包含脈衝回應濾波器每個區塊的增益值。這些增益值會在摺積期間套用至脈衝回應。\
需要使用 Envelope 時,應使用 Envelope 緩衝區的有效指標來呼叫此 API。呼叫端有責任確保 Envelope 緩衝區在不再需要之前保持有效。若要停止使用 Envelope,應使用 XDspSubmitCommand,或使用 envelopeBuffer 為 nullptr 的 XDspSubmitCommandWithEnvelope。
此 API 只應用於針對 XDspProcessType::Convolution 啟用的串流。

## 語法

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

### 參數

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

有效的 XDSP 串流控制代碼。

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

[XDspCommand](/zh-TW/reference/audio/xdspaudio/structs/xdspcommand) 結構的指標。

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

指向摺積期間要套用之脈衝回應濾波器每個區塊增益值的指標。\
此緩衝區必須是由 [XDspConnect](/zh-TW/reference/audio/xdspaudio/functions/xdspconnect) 或 [XDspConnectWithMaximumStreamLimit](/zh-TW/reference/audio/xdspaudio/functions/xdspconnectwithmaximumstreamlimit) 所註冊記憶體的一部分,且應以 16 位元組對齊。此緩衝區由硬體使用,在使用此緩衝區的所有命令完成且已取回回應之前,不可修改或釋放。
Envelope 緩衝區中的增益值數目至少應為脈衝回應濾波器中的區塊數目,計算方式如下。\
*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 | 一或多個引數無效。 |
| XDSP\_E\_QUEUE\_FULL | 如果串流和硬體伺服器已達到最大處理容量,此呼叫將會傳回 XDSP\_E\_QUEUE\_FULL。請等待硬體處理命令,再提交更多命令。 |
| XDSP\_E\_DEVICE\_FATAL\_ERROR | 如果硬體伺服器處於不良狀態,**XDspSubmitCommandWithEnvelope** 將會傳回 XDSP\_E\_DEVICE\_FATAL\_ERROR 錯誤碼。 |

## 備註

此呼叫速度很快,因為它不會配置資源或處理資料,只會將命令傳送至硬體伺服器。

摺積處理有 *'n'* 個階段,而 Envelope 只能在第一個階段切換或開啟/關閉。這表示 Envelope 效果可能不會立即生效,可能會延遲數次提交。

若要停用 Envelope 參數,應呼叫 **XDspSubmitCommand**,或使用 null envelopeBuffer 呼叫 **XDspSubmitCommandWithEnvelope**。

此呼叫也會接受 `uint32_t` 的指標,以傳回命令序列值 *commandSequence*,用於稍後追蹤命令結果何時就緒。此數字代表自工作階段開始且呼叫 [XDspActivate](/zh-TW/reference/audio/xdspaudio/functions/xdspactivate) 之後已成功提交的命令總數。第一個命令的此數字為 1,之後每次成功呼叫 **XDspSubmitCommandWithEnvelope** 或 [XDspSubmitCommand](/zh-TW/reference/audio/xdspaudio/functions/xdspsubmitcommand) 都會遞增 1。

如果硬體伺服器處於不良狀態,**XDspSubmitCommandWithEnvelope** 將會傳回 XDSP\_E\_DEVICE\_FATAL\_ERROR 錯誤碼。此時,無法再為處於失敗狀態的 XDSP 串流提交任何命令。該串流的 [XDspStatus](/zh-TW/reference/audio/xdspaudio/structs/xdspstatus) 也會指出相同的錯誤。受影響的 XDSP 串流應透過檢查 [XDspStatus](/zh-TW/reference/audio/xdspaudio/structs/xdspstatus) 等待硬體處理所有已提交的命令,並在所有命令處理完畢後使用 [XDspDeactivate](/zh-TW/reference/audio/xdspaudio/functions/xdspdeactivate) 將其停用。其他 XDSP 串流不會受到影響,硬體會繼續處理其命令。

## 需求

**標頭:** XDspAudio.h

**程式庫:** Chad.lib

**支援的平台:** XBOX Series X|S

## 概念文件

* [XDSP Envelope 概觀](/zh-TW/build/console-features/audio/overviews/xdsp-overview-enveloping)
* [使用 XDSP API 進行含 Envelope 的單一串流 Convolution 的概觀](/zh-TW/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope)
* [XDSP 概觀](/zh-TW/build/console-features/audio/overviews/xdsp-overview)

## 另請參閱

[XDSP](/zh-TW/reference/audio/xdspaudio/xdspaudio_members)\
[XdspSubmitCommand](/zh-TW/reference/audio/xdspaudio/functions/xdspsubmitcommand)\
[XDSP 錯誤](/zh-TW/reference/audio/xdspaudio/enums/xdsperrors)\
[使用 XDSP API 進行單一串流 Convolution 的概觀](/zh-TW/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution)\
[使用 XDSP API 進行含 Envelope 的單一串流 Convolution 的概觀](/zh-TW/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope)
[使用 XDSP API 進行單一串流 FFT/IFFT 的概觀](/zh-TW/build/console-features/audio/overviews/xdsp-overview-single-stream-fft-ifft)


## Related topics

- [XDspSubmitCommandWithEnvelope](/reference/audio/xdspaudio/functions/xdspsubmitcommandwithenvelope.md)
- [XDspSubmitCommand](/reference/audio/xdspaudio/functions/xdspsubmitcommand.md)
- [Single-stream convolution with envelope using the XDSP API](/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope.md)
- [XDSP overview](/build/console-features/audio/overviews/xdsp-overview.md)
- [XDSP Enveloping Overview](/build/console-features/audio/overviews/xdsp-overview-enveloping.md)