Skip to main content

​
SetShapeFiltVolCommand

Initializes a SHAPE FLTVOL command.

​
Syntax

​
Parameters

command   _Inout_
Type: SHAPE_FLOWGRAPH_COMMAND* The SHAPE_FLOWGRAPH_COMMAND command to initialize. contextId   
Type: UINT32 Filter/Volume context ID (index) this command will reference. inputMixBuffer   
Type: UINT32 Input mix buffer ID. outputMixBuffer   
Type: UINT32 Output mix buffer ID.

​
Return value

Type: HRESULT If the function succeeds, it returns S_OK. If one or more of the arguments are invalid, the function returns E_INVALIDARG.

​
Remarks

The Filter/Volume (FLTVOL) block is used to model the occlusion of sounds that is, sound going around or through an object and distributes sound energy to multiple speakers to model the direction in which sound arrives. The FLTVOL block takes a single channel of input data from a mix buffer, filters and volume-scales it and writes the output to a mix buffer. Typically, several FLTVOL controls are used to generate a one-in, multi-out pan such as a surround-sound pan. The panner is typically used for taking a sound and performing an n-speaker pan, plus one or more reverb effects. The addition of the State Variable filter enables a title to easily create enhanced distance effects as well as I3DL2 style occlusion and obstruction effects. The state variable filter, by its nature, can create resonances causing intermediate values to exceed 1.0 (or -1.0). To mitigate the issues created by intermediate value saturation, the FLTVOL block has a programmable amount of headroom scaling that is applied to the incoming signal and then compensated for upon output. Scaling is achieved by arithmetically right-shifting the data by a certain number of bits. The headroom field of the context specifies the number of bits of right shift the incoming signal receives before FLTVOL processing (0, 1, 2, or 3). Therefore, by specifying a headroom value of 3, the state variable filter can maintain an extra 3 bits (18 dB) of headroom for internally created resonances and overflow. Of course, shifting the incoming data to the right necessarily reduces precision at the low end. The lowest headroom bits of the incoming audio signal are lost forever. Therefore, the headroom bits should generally be specified as non-zero only if it is determined that internal saturation has occurred in the state variable filter. This can be done by checking the value of the Internal Overflow bit in the FLTVOL context. In the case where the original source data is 16 bits, such as if the original source data is XBOX Media Audio (XMA), the headroom bits can usually be set to their maximum (3) without a noticeable change in sound, since the lower order bits are zero-padded anyway. The flexible state variable filter implementation also allows for resonant filtering to be applied to a voice to aid in the creation of interesting audio effects and creating variation. The filter parameters and volume attributes are gradually adjusted on a per-sample basis to provide a smooth transition between entry and exit set points. The FLTVOL block is implemented as a Chamberlin filter. The filter provides three modes, high-pass, low-pass and band-pass with a variable Q (bandwidth) control. The parameters for the Chamberlin filter are calculated as follows.
The f and q parameters are calculated by software outside the Scalable Hardware Audio Processing Engine (SHAPE) block. When a coefficient is updated, it is ramped to the new value over the course of one audio frame. Control bits are used to determine which output (band reject, high-pass, band-pass, or low-pass) is used as the final output of the FLTVOL block. The context data for each channel or stream is stored in system memory. Though performance is limited to 2560 48-kHz simultaneous streams, meaning SHAPE can process up to 2560 FLTVOL contexts per audio frame, the number of contexts addressable in memory is larger to simplify stream-reuse scenarios. The filtering behavior is designed to be identical to that in XAudio2.

​
Requirements

Header: shapeflowgraph.h Supported platforms: XBOX One family consoles and XBOX Series consoles

​
See also

ACP Overview SHAPE Overview shapeflowgraph
Last modified on August 20, 2026

Related topics

ShapeFlowGraphSetShapeFiltVolQSetShapeFiltVolQTargetSetShapeFiltVolFrequencySetShapeFiltVolMode