> ## 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](/reference/audio/shapeflowgraph/structs/shape_flowgraph_command) 命令。

*contextId*   \
类型:UINT32

此命令将引用的滤波器/音量上下文 ID(索引)。

*inputMixBuffer*   \
类型:UINT32

输入混音缓冲区 ID。

*outputMixBuffer*   \
类型:UINT32

输出混音缓冲区 ID。

### 返回值

类型:HRESULT

如果函数成功,则返回 `S_OK`。如果一个或多个参数无效,函数返回 `E_INVALIDARG`。

## 注解

滤波器/音量(FLTVOL)模块用于模拟声音的遮挡效果(即声音绕过或穿过物体),并将声音能量分配给多个扬声器,以模拟声音到达的方向。FLTVOL 模块从一个混音缓冲区获取单个声道的输入数据,对其进行滤波和音量缩放,然后将输出写入混音缓冲区。通常会使用多个 FLTVOL 控件来生成一进多出的声像平移,例如环绕声平移。声像平移器通常用于对声音进行 *n* 声道扬声器平移,加上一个或多个混响效果。状态变量滤波器的加入使得游戏可以轻松地创建增强的距离效果以及 I3DL2 风格的遮蔽和阻挡效果。

状态变量滤波器的本质使其可能产生共振,导致中间值超过 1.0(或 -1.0)。为缓解中间值饱和带来的问题,FLTVOL 模块具备可编程的余量缩放,该缩放会应用于输入信号,并在输出时进行补偿。缩放通过对数据进行算术右移一定位数来实现。上下文的 headroom 字段指定输入信号在 FLTVOL 处理前接收的右移位数(0、1、2 或 3)。因此,通过指定 headroom 值为 3,状态变量滤波器可以为内部产生的共振和溢出保留额外 3 位(18 dB)的余量。

当然,将输入数据右移必然会降低低位的精度。输入音频信号中最低的 headroom 位将永远丢失。因此,通常应仅在确定状态变量滤波器已发生内部饱和时,才将 headroom 位指定为非零。这可以通过检查 FLTVOL 上下文中的 Internal Overflow 位的值来判断。在原始源数据为 16 位的情况下,例如原始源数据为 XBOX 媒体音频(XMA)时,通常可以将 headroom 位设置为最大值(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](/build/console-features/audio/overviews/xaudio2-overview) 中的完全一致。

## 要求

**头文件:** shapeflowgraph.h

**支持的平台:** XBOX One 系列主机和 XBOX Series 主机

## 另请参阅

[ACP 概述](/build/console-features/audio/overviews/acp-overview)

[SHAPE 概述](/build/console-features/audio/overviews/shape-overview)

[shapeflowgraph](/reference/audio/shapeflowgraph/shapeflowgraph_members)


## Related topics

- [ShapeFlowGraph](/zh-CN/reference/audio/shapeflowgraph/shapeflowgraph_members.md)
- [SetShapeFiltVolQ](/zh-CN/reference/audio/shapefiltvolcontext/functions/setshapefiltvolq.md)
- [SetShapeFiltVolFrequency](/zh-CN/reference/audio/shapefiltvolcontext/functions/setshapefiltvolfrequency.md)
- [SetShapeFiltVolMode](/zh-CN/reference/audio/shapefiltvolcontext/functions/setshapefiltvolmode.md)
- [SetShapeFiltVolQTarget](/zh-CN/reference/audio/shapefiltvolcontext/functions/setshapefiltvolqtarget.md)