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

# SetShapeFiltVolCommand

> SetShapeFiltVolCommand

# SetShapeFiltVolCommand

初始化 SHAPE FLTVOL 命令。

## 語法

```cpp theme={null}
HRESULT SetShapeFiltVolCommand(  
         SHAPE_FLOWGRAPH_COMMAND* command,  
         UINT32 contextId,  
         UINT32 inputMixBuffer,  
         UINT32 outputMixBuffer  
)  
```

### 參數

*command*   \_Inout\_\
類型：SHAPE\_FLOWGRAPH\_COMMAND\*

要初始化的 [SHAPE\_FLOWGRAPH\_COMMAND](/zh-TW/reference/audio/shapeflowgraph/structs/shape_flowgraph_command) 命令。

*contextId*   \
類型：UINT32

此命令將參考的濾波器/音量內容識別碼 (索引)。

*inputMixBuffer*   \
類型：UINT32

輸入混音緩衝區識別碼。

*outputMixBuffer*   \
類型：UINT32

輸出混音緩衝區識別碼。

### 傳回值

類型：HRESULT

如果函式成功，會傳回 `S_OK`。如果一或多個引數無效，函式會傳回 `E_INVALIDARG`。

## 備註

濾波器/音量 (FLTVOL) 區塊用於模擬聲音的遮蔽 (也就是聲音繞過或穿過物體)，並將聲音能量分配到多個喇叭，以模擬聲音抵達的方向。FLTVOL 區塊會從混音緩衝區取得單一聲道的輸入資料，對其進行濾波和音量縮放，然後將輸出寫入混音緩衝區。通常會使用多個 FLTVOL 控制項來產生一進多出的聲像定位，例如環繞音效聲像定位。聲像定位器通常用於對聲音執行 *n* 喇叭聲像定位，再加上一或多個殘響效果。加入狀態變數濾波器後，遊戲就能輕鬆建立增強的距離效果，以及 I3DL2 樣式的遮蔽與阻擋效果。

狀態變數濾波器本質上可能會產生共振，導致中間值超過 1.0 (或 -1.0)。為了減輕中間值飽和所造成的問題，FLTVOL 區塊具有可程式化的動態餘裕縮放量，此縮放會套用至傳入的訊號，然後在輸出時加以補償。縮放是透過將資料算術右移特定位元數來達成。內容的 headroom 欄位會指定傳入訊號在 FLTVOL 處理之前所要右移的位元數 (0、1、2 或 3)。因此，藉由指定動態餘裕值 3，狀態變數濾波器可以為內部產生的共振和溢位保留額外 3 個位元 (18 dB) 的動態餘裕。

當然，將傳入資料右移必然會降低低端的精確度。傳入音訊訊號最低的動態餘裕位元會永久遺失。因此，一般而言，只有在判斷狀態變數濾波器已發生內部飽和時，才應將動態餘裕位元指定為非零值。這可以透過檢查 FLTVOL 內容中 Internal Overflow 位元的值來完成。如果原始來源資料為 16 位元 (例如原始來源資料為 XBOX Media Audio (XMA))，通常可以將動態餘裕位元設定為最大值 (3)，而不會有明顯的聲音變化，因為較低位的位元原本就會補零。

彈性的狀態變數濾波器實作也允許對語音套用共振濾波，以協助建立有趣的音訊效果並產生變化。濾波器參數和音量屬性會以每個取樣為單位逐漸調整，以在進入與結束設定點之間提供平滑的轉換。FLTVOL 區塊是以 Chamberlin 濾波器實作。此濾波器提供三種模式：高通、低通和帶通，並具有可變的 *Q* (頻寬) 控制。Chamberlin 濾波器的參數計算方式如下。

```cpp theme={null}
f := 2*Sin( ( PI * FC )/FS)
```

```cpp theme={null}
q := 1/Q, where Q ranges from 0.5 to 5 
```

*f* 和 *q* 參數是由可調整硬體音訊處理引擎 (SHAPE) 區塊以外的軟體計算。當係數更新時，會在一個音訊框架的期間內逐漸調整至新值。控制位元用於決定要使用哪一個輸出 (帶拒、高通、帶通或低通) 作為 FLTVOL 區塊的最終輸出。

每個聲道或串流的內容資料都儲存在系統記憶體中。雖然效能限制為 2560 個同時進行的 48 kHz 串流 (表示 SHAPE 每個音訊框架最多可處理 2560 個 FLTVOL 內容)，但為了簡化串流重複使用的案例，記憶體中可定址的內容數目會更多。

濾波行為的設計與 [XAudio2](/zh-TW/build/console-features/audio/overviews/xaudio2-overview) 中的濾波行為完全相同。

## 需求

**標頭：** shapeflowgraph.h

**支援的平台：** XBOX One 系列主機與 XBOX Series 主機

## 另請參閱

[ACP 概觀](/zh-TW/build/console-features/audio/overviews/acp-overview)

[SHAPE 概觀](/zh-TW/build/console-features/audio/overviews/shape-overview)

[shapeflowgraph](/zh-TW/reference/audio/shapeflowgraph/shapeflowgraph_members)


## Related topics

- [SetShapeFiltVolCommand](/reference/audio/shapeflowgraph/functions/setshapefiltvolcommand.md)
- [ShapeFlowGraph](/reference/audio/shapeflowgraph/shapeflowgraph_members.md)