> ## 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 デバイスでコンボリューションを実行する際のエンベロープ処理の使用方法について説明します。このメカニズムは、開発者が新しいストリームを再アクティブ化することなく、既存のストリーム上でインパルス応答フィルターの一部を動的に変更するための柔軟な方法として開発されました。[XDspSubmitCommand](/reference/audio/xdspaudio/functions/xdspsubmitcommand) API に提供されるパラメーターに加えて、インパルス応答フィルターの各ブロックのゲイン値を含む *envelopeBuffer* を取る [XDspSubmitCommandWithEnvelope](/reference/audio/xdspaudio/functions/xdspsubmitcommandwithenvelope) API が提供されています。ゲイン値は、コンボリューション プロセス中にインパルス応答フィルターの対応するブロックと乗算され、目的の効果を提供します。このプロセス中、元のインパルス応答フィルターは変更されません。

エンベロープ処理のメカニズムをよりよく理解するために、周波数領域で次の変数を定義しましょう。

* ブロック ***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*** です。

## エンベロープ バッファー

エンベロープ バッファーには、コンボリューション中に適用されるインパルス応答フィルターの各ブロックに対する float のゲイン値が含まれます。このバッファーの最小サイズは、モノラルのインパルス応答フィルターの場合は 8 個の float 値、ステレオのインパルス応答フィルターの場合は 16 個の float 値である必要があります。ステレオ インパルス応答の場合、エンベロープ バッファーには両チャネルのゲイン値が含まれ、左チャネル全体のゲイン値の後に右チャネル全体のゲイン値が続きます。各チャネルのエンベロープ長は 16 バイトの倍数である必要があります。そうでない場合、出力が正しくない可能性があります。最も近い 16 バイトの倍数に切り上げた結果生じる追加の値は無視されます。すべてのバッファー ポインターは 16 バイトにアラインされている必要があります。
このバッファーは [XDspConnect](/reference/audio/xdspaudio/functions/xdspconnect) または [XDspConnectWithMaximumStreamLimit](/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 内容)](/reference/audio/xdspaudio/xdspaudio_members)
  * 関数
    * [XDspSubmitCommandWithEnvelope](/reference/audio/xdspaudio/functions/xdspsubmitcommandwithenvelope)
    * [XDspSubmitCommand](/reference/audio/xdspaudio/functions/xdspsubmitcommand)
    * [XDspConnect](/reference/audio/xdspaudio/functions/xdspconnect)
    * [XDspConnectWithMaximumStreamLimit](/reference/audio/xdspaudio/functions/xdspconnectwithmaximumstreamlimit)

## 関連項目

[XDSP の概要](/build/console-features/audio/overviews/xdsp-overview)
[XDspSubmitCommandWithEnvelope](/reference/audio/xdspaudio/functions/xdspsubmitcommandwithenvelope)
[XDSP API を使用したエンベロープ付きシングル ストリーム コンボリューションの概要](/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope)


## Related topics

- [XDSP API を使用したエンベロープ付きシングル ストリーム コンボリューション](/ja-jp/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope.md)
- [XDSP の概要](/ja-jp/build/console-features/audio/overviews/xdsp-overview.md)
- [XDSP audio](/ja-jp/reference/audio/xdspaudio/xdspaudio_members.md)
- [XDspSubmitCommandWithEnvelope](/ja-jp/reference/audio/xdspaudio/functions/xdspsubmitcommandwithenvelope.md)
- [XDspConnect](/ja-jp/reference/audio/xdspaudio/functions/xdspconnect.md)