> ## 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.

# XDSP 包絡概觀

> XDSP 包絡概觀

在本主題中，我們將逐步說明如何在使用 XDSP 於 XBOX Series X|S 裝置上執行摺積時使用包絡。此機制是為開發人員所開發的彈性方法，可在現有串流上動態變更部分脈衝回應篩選器，而不需要重新啟用新的串流。我們提供了 [XDspSubmitCommandWithEnvelope](/zh-TW/reference/audio/xdspaudio/functions/xdspsubmitcommandwithenvelope) API，除了提供給 [XDspSubmitCommand](/zh-TW/reference/audio/xdspaudio/functions/xdspsubmitcommand) API 的參數之外，它還會接受一個 *envelopeBuffer*，其中包含脈衝回應篩選器每個區塊的增益值。在摺積過程中，增益值會與脈衝回應篩選器中對應的區塊相乘，以提供所需的效果。在此過程中，原始的脈衝回應篩選器不會被修改。

為了更了解包絡機制，讓我們在頻域中定義下列變數：

* 令區塊 ***m*** 之頻率箱 ***n*** 的脈衝回應篩選器訊號為 ***f\[n,m] = f\_Real\[n,m] + if\_Imag\[n,m]***。
* 令區塊 ***m*** 之頻率箱 ***n*** 的輸入訊號為 ***s\[n,m] = s\_Real\[n,m] + is\_Imag\[n,m]***。
* 令篩選器區塊 ***m*** 的增益值表示為 ***K\[m]*** (區塊 ***m*** 的包絡增益)。

則包絡的數學表示法如下：

***r\[n,m] = K\[m] \* f\[n,m] \* s\[n,m]***
***r\[n,m] = K\[m] \* (f\_Real\[n,m] + if\_Imag\[n,m]) \* (s\_Real\[n,m] + is\_Imag\[n,m])***

其中 ***r\[n,m]*** 是每個頻率箱和區塊依相關聯的包絡增益縮放之後的摺積輸出。如果未指定包絡增益，則所有區塊 ***m*** 的 ***K\[m] = 1.0f***。

## 包絡緩衝區

包絡緩衝區包含要在摺積期間套用至脈衝回應篩選器每個區塊的浮點數增益值。對於單聲道脈衝回應篩選器，此緩衝區的大小下限應為 8 個浮點數值；對於立體聲脈衝回應篩選器，則為 16 個浮點數值。在立體聲脈衝回應的情況下，包絡緩衝區包含兩個聲道的增益值，先是整個左聲道的增益值，接著是整個右聲道的增益值。每個聲道的包絡長度應為 16 位元組的倍數，否則輸出可能不正確。因無條件進位到最接近的 16 位元組倍數而產生的任何額外值都會被忽略。所有緩衝區指標都應以 16 位元組對齊。
此緩衝區必須是由 [XDspConnect](/zh-TW/reference/audio/xdspaudio/functions/xdspconnect) 或 [XDspConnectWithMaximumStreamLimit](/zh-TW/reference/audio/xdspaudio/functions/xdspconnectwithmaximumstreamlimit) 註冊之記憶體的一部分，而且應以 16 位元組對齊。此緩衝區由硬體使用，在所有使用此緩衝區的命令完成且回應已被取回之前，無法修改或釋放。
包絡緩衝區中的增益值數目，應為脈衝回應篩選器中的區塊數目無條件進位到最接近的 16 位元組倍數，計算方式如下。

```cpp theme={null}
#define ROUND_UP_TO_16BYTE_ALIGNED(x) (((x) + (15)) & ~(0xF))

// XDspActivationParameters::impulseResponseLengthInFloats is the impulse response length of each channel in case of stereo IR
uint32_t irLengthInComplexes = XDspActivationParameters::impulseResponseLengthInFloats/2;  
uint32_t numFilterBlocks = irLengthInComplexes/XDspActivationParameters::blockFrameCount;

// Round up the envelope size to the nearest multiple of 16 bytes. Additional values resulting from the rounding will be ignored.
// envelopeGainCount represents the number of gain values an envelope buffer holds. In case of a stereo impulse response filter,
// this is the number of gain values per channel.
uint32_t envelopeLengthInBytes = ROUND_UP_TO_16BYTE_ALIGNED(numFilterBlocks * sizeof(float));
uint32_t envelopeGainCount = envelopeSize / sizeof(float)  

// Account for left and right channel envelopes in case of stereo impulse response
if (stereoImpulseRespone)
{
    envelopeLengthInBytes = envelopeLengthInBytes * 2;
}
```

此緩衝區在性質上遵循脈衝回應篩選器。對於立體聲脈衝回應，整個左聲道的增益值後面接著整個右聲道的增益值，就像左聲道脈衝回應後面接著右聲道脈衝回應一樣。
對於單聲道脈衝回應，相同的增益值會套用至立體聲輸入訊號的左聲道和右聲道。

## API 使用方式

以下是 API 使用模式範例。如需其他詳細資料，請參閱下方的注意事項。

```cpp theme={null}
XDspSubmitCommand(...)/XDspSubmitCommandWithEnvelope(.., nullptr, ...);  // _envelopeState = Off;  
XDspSubmitCommand(...)/XDspSubmitCommandWithEnvelope(.., nullptr, ...);  // _envelopeState = Off;  
:::::::::::::::::::::::     
XDspSubmitCommandWithEnvelope(..., envelopeBuffer1, ...); // _envelopeState = Engaged with envelopeBuffer1  
XDspSubmitCommandWithEnvelope(..., envelopeBuffer1, ...); // _envelopeState = Engaged with envelopeBuffer1  
:::::::::::::::::::::: 
XDspSubmitCommandWithEnvelope(..., envelopeBuffer2, ...); // _envelopeState = Engaged with envelopeBuffer2  
XDspSubmitCommandWithEnvelope(..., envelopeBuffer2, ...); // _envelopeState = Engaged with envelopeBuffer2  
::::::::::::::::::::::  
XDspSubmitCommand(...)/XDspSubmitCommandWithEnvelope(.., nullptr, ...);  // _envelopeState = Off;  
XDspSubmitCommand(...)/XDspSubmitCommandWithEnvelope(.., nullptr, ...);  // _envelopeState = Off;  
:::::::::::::::::::::::
```

## 注意事項

摺積是以多階段程序實作，每個輸入封包都會經過其中一個階段。為了保持輸出平順，只能在第一個階段開啟或關閉包絡。這表示提交命令時，包絡效果可能不會立即關閉/開啟。可能需要幾次呼叫才會生效。

## 參考 API 文件

* [XDspAudio (API 內容)](/zh-TW/reference/audio/xdspaudio/xdspaudio_members)
  * 函式
    * [XDspSubmitCommandWithEnvelope](/zh-TW/reference/audio/xdspaudio/functions/xdspsubmitcommandwithenvelope)
    * [XDspSubmitCommand](/zh-TW/reference/audio/xdspaudio/functions/xdspsubmitcommand)
    * [XDspConnect](/zh-TW/reference/audio/xdspaudio/functions/xdspconnect)
    * [XDspConnectWithMaximumStreamLimit](/zh-TW/reference/audio/xdspaudio/functions/xdspconnectwithmaximumstreamlimit)

## 另請參閱

[XDSP 概觀](/zh-TW/build/console-features/audio/overviews/xdsp-overview)
[XDspSubmitCommandWithEnvelope](/zh-TW/reference/audio/xdspaudio/functions/xdspsubmitcommandwithenvelope)
[使用 XDSP API 進行含包絡的單一串流摺積概觀](/zh-TW/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope)


## Related topics

- [服務 C API 概觀 - PFLocalization.h](/zh-TW/services/playfab/api-references/c/pflocalization/pflocalization_members.md)
- [服務 C API 概觀 - PFStatistics.h](/zh-TW/services/playfab/api-references/c/pfstatistics/pfstatistics_members.md)
- [服務 C API 概觀 - PFLeaderboards.h](/zh-TW/services/playfab/api-references/c/pfleaderboards/pfleaderboards_members.md)
- [服務 C API 概觀 - PFPlatformSpecific.h](/zh-TW/services/playfab/api-references/c/pfplatformspecific/pfplatformspecific_members.md)
- [服務 C API 概觀 - PFStatisticsTypes.h](/zh-TW/services/playfab/api-references/c/pfstatisticstypes/pfstatisticstypes_members.md)