> ## 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 contents)](/reference/audio/xdspaudio/xdspaudio_members)
  * Functions
    * [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 개요](/ko/build/console-features/audio/overviews/xdsp-overview.md)
- [XDSP API를 사용한 엔벨로프가 있는 싱글 스트림 컨볼루션](/ko/build/console-features/audio/overviews/xdsp-overview-single-stream-convolution-with-envelope.md)
- [XDSP audio](/ko/reference/audio/xdspaudio/xdspaudio_members.md)
- [개요](/ko/build/console-features/audio/overviews/index.md)
- [XDspSubmitCommandWithEnvelope](/ko/reference/audio/xdspaudio/functions/xdspsubmitcommandwithenvelope.md)