> ## 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 コマンドを初期化します。

## Syntax

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

### Parameters

*command*   \_Inout\_\
Type: SHAPE\_FLOWGRAPH\_COMMAND\*

初期化する [SHAPE\_FLOWGRAPH\_COMMAND](/reference/audio/shapeflowgraph/structs/shape_flowgraph_command) コマンド。

*contextId*   \
Type: UINT32

このコマンドが参照するフィルター/ボリュームコンテキスト ID (インデックス)。

*inputMixBuffer*   \
Type: UINT32

入力ミックスバッファー ID。

*outputMixBuffer*   \
Type: UINT32

出力ミックスバッファー ID。

### Return value

Type: HRESULT

関数が成功した場合は `S_OK` を返します。1 つ以上の引数が無効な場合は `E_INVALIDARG` を返します。

## Remarks

フィルター/ボリューム (FLTVOL) ブロックは、音のオクルージョン (音がオブジェクトを回り込んだり通り抜けたりする現象) をモデル化するために使用され、音がどの方向から到来するかをモデル化するため、複数のスピーカーに音のエネルギーを分配します。FLTVOL ブロックは、ミックスバッファーから 1 チャンネル分の入力データを受け取り、フィルタリングとボリュームスケーリングを行って、ミックスバッファーに出力を書き込みます。通常、サラウンドサウンドのパンなど、1 入力/複数出力のパンを生成するために複数の FLTVOL コントロールが使用されます。パンナーは通常、サウンドを取得して *n* 個のスピーカーへのパンと 1 つ以上のリバーブエフェクトを実行するために使用されます。状態変数フィルターの追加により、タイトルは強化された距離エフェクトや I3DL2 スタイルのオクルージョン/オブストラクションエフェクトを簡単に作成できます。

状態変数フィルターは、その特性上、中間値が 1.0 (または -1.0) を超えるような共振を生じることがあります。中間値の飽和による問題を軽減するため、FLTVOL ブロックにはプログラム可能なヘッドルームスケーリングが用意されており、入力信号に適用され、出力時に補正されます。スケーリングは、データを一定ビット数だけ算術右シフトすることで実現されます。コンテキストのヘッドルームフィールドは、FLTVOL 処理前に入力信号を右シフトするビット数 (0、1、2、または 3) を指定します。したがって、ヘッドルーム値を 3 に指定することで、状態変数フィルターは内部で生成される共振やオーバーフローに対して追加 3 ビット (18 dB) のヘッドルームを確保できます。

もちろん、入力データを右シフトすると、必然的に低次側の精度が低下します。入力オーディオ信号の最下位のヘッドルームビットは永久に失われます。したがって、ヘッドルームビットは、状態変数フィルターで内部飽和が発生したと判断された場合にのみ、非ゼロに指定するのが一般的です。これは、FLTVOL コンテキストの Internal Overflow ビットの値を確認することで確認できます。元のソースデータが XBOX Media Audio (XMA) など 16 ビットの場合、下位ビットは元々ゼロパディングされているため、通常、音の変化を意識せずにヘッドルームビットを最大値 (3) に設定できます。

柔軟な状態変数フィルターの実装により、共振フィルタリングをボイスに適用して、興味深いオーディオエフェクトやバリエーションの作成を支援することもできます。フィルターパラメーターとボリューム属性は、サンプル単位で徐々に調整され、入力と出力の設定点間のスムーズな遷移が実現します。FLTVOL ブロックは Chamberlin フィルターとして実装されています。フィルターは 3 つのモード (ハイパス、ローパス、バンドパス) を提供し、可変 *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* のパラメーターは Scalable Hardware Audio Processing Engine (SHAPE) ブロックの外部のソフトウェアで計算されます。係数が更新されると、1 オーディオフレームの間に新しい値へランプします。制御ビットによって、FLTVOL ブロックの最終出力としてどの出力 (バンドリジェクト、ハイパス、バンドパス、ローパス) を使用するかが決定されます。

各チャンネルまたはストリームのコンテキストデータはシステムメモリに保存されます。パフォーマンスは 48 kHz の同時ストリーム 2560 本、すなわち SHAPE は 1 オーディオフレームあたり最大 2560 個の FLTVOL コンテキストを処理できますが、ストリームの再利用シナリオを簡素化するため、メモリでアドレス指定可能なコンテキスト数はこれより多くなっています。

フィルタリング動作は [XAudio2](/build/console-features/audio/overviews/xaudio2-overview) と同一になるように設計されています。

## Requirements

**Header:** shapeflowgraph.h

**Supported platforms:** XBOX One ファミリー本体および XBOX Series 本体

## See also

[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](/ja-jp/reference/audio/shapeflowgraph/shapeflowgraph_members.md)
- [SetShapeFiltVolQ](/ja-jp/reference/audio/shapefiltvolcontext/functions/setshapefiltvolq.md)
- [SetShapeFiltVolFrequency](/ja-jp/reference/audio/shapefiltvolcontext/functions/setshapefiltvolfrequency.md)
- [SetShapeFiltVolMode](/ja-jp/reference/audio/shapefiltvolcontext/functions/setshapefiltvolmode.md)
- [SetShapeFiltVolQTarget](/ja-jp/reference/audio/shapefiltvolcontext/functions/setshapefiltvolqtarget.md)