XDspSubmitCommandWithEnvelope
為指定的 XDSP 串流提交一個命令至硬體佇列。此 API 類似於 XDspSubmitCommand,會將一個命令提交至硬體,差別在於它多接受一個參數 envelopeBuffer,其中包含脈衝回應濾波器每個區塊的增益值。這些增益值會在摺積期間套用至脈衝回應。需要使用 Envelope 時,應使用 Envelope 緩衝區的有效指標來呼叫此 API。呼叫端有責任確保 Envelope 緩衝區在不再需要之前保持有效。若要停止使用 Envelope,應使用 XDspSubmitCommand,或使用 envelopeBuffer 為 nullptr 的 XDspSubmitCommandWithEnvelope。 此 API 只應用於針對 XDspProcessType::Convolution 啟用的串流。
語法
參數
handle _In_類型:XDspStreamHandle 有效的 XDSP 串流控制代碼。 command _In_
類型:XDspCommand* XDspCommand 結構的指標。 envelopeBuffer _In_
類型:float* 指向摺積期間要套用之脈衝回應濾波器每個區塊增益值的指標。
此緩衝區必須是由 XDspConnect 或 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。如果方法失敗,會傳回下列代碼 (部分清單):備註
此呼叫速度很快,因為它不會配置資源或處理資料,只會將命令傳送至硬體伺服器。 摺積處理有 ‘n’ 個階段,而 Envelope 只能在第一個階段切換或開啟/關閉。這表示 Envelope 效果可能不會立即生效,可能會延遲數次提交。 若要停用 Envelope 參數,應呼叫 XDspSubmitCommand,或使用 null envelopeBuffer 呼叫 XDspSubmitCommandWithEnvelope。 此呼叫也會接受uint32_t 的指標,以傳回命令序列值 commandSequence,用於稍後追蹤命令結果何時就緒。此數字代表自工作階段開始且呼叫 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 進行單一串流 Convolution 的概觀
使用 XDSP API 進行含 Envelope 的單一串流 Convolution 的概觀 使用 XDSP API 進行單一串流 FFT/IFFT 的概觀