IXAudio2::CreateSourceVoice 메서드(xaudio2.h)

아티클
08/28/2023

원본 음성을 만들고 구성합니다.

구문

HRESULT CreateSourceVoice(
  [out]          IXAudio2SourceVoice        **ppSourceVoice,
  [in]           const WAVEFORMATEX         *pSourceFormat,
  [in]           UINT32                     Flags,
  [in]           float                      MaxFrequencyRatio,
  [in, optional] IXAudio2VoiceCallback      *pCallback,
  [in, out]      const XAUDIO2_VOICE_SENDS  *pSendList,
  [in, optional] const XAUDIO2_EFFECT_CHAIN *pEffectChain
);

매개 변수

[out] ppSourceVoice

성공하면 새 IXAudio2SourceVoice 개체에 대한 포인터를 반환합니다.

[in] pSourceFormat

아래 표의 구조체 중 하나에 대한 포인터입니다. 이 구조체는 원본 음성에 제출된 모든 오디오 버퍼에 대해 예상되는 형식을 포함합니다. XAudio2는 PCM 및 ADPCM 음성 유형을 지원합니다.

서식 태그	웨이브 형식 구조체	크기(바이트)
WAVE_FORMAT_PCM(0x0001)	PCMWAVEFORMAT	16
또는	WAVEFORMATEX	18
WAVE_FORMAT_IEEE_FLOAT(0x0003) [32비트]	PCMWAVEFORMAT	18
WAVE_FORMAT_ADPCM(0x0002) [MS-ADPCM]	ADPCMWAVEFORMAT	50
WAVE_FORMAT_EXTENSIBLE(0xFFFE)	WAVEFORMATEXTENSIBLE	40

XAudio2는 다음 PCM 형식을 지원합니다.

8비트(부호 없는) 정수 PCM
16비트 정수 PCM(XAudio2에 최적 형식)
20비트 정수 PCM(24비트 또는 32비트 컨테이너)
24비트 정수 PCM(24비트 또는 32비트 컨테이너)
32비트 정수 PCM
32비트 부동 소수점 PCM(16비트 정수 이후 기본 형식)

원본 음성의 채널 수는 XAUDIO2_MAX_AUDIO_CHANNELS 미만이거나 같아야 합니다. 원본 음성의 샘플 속도는 XAUDIO2_MIN_SAMPLE_RATE XAUDIO2_MAX_SAMPLE_RATE 사이여야 합니다.

참고WAVEFORMATEX에서 제공하는 것보다 더 많은 정보가 필요한 PCMWAVEFORMAT 및 ADPCMWAVEFORMAT과 같은 PCM 데이터 형식에는 WAVEFORMATEX 구조체가 해당 형식 구조의 첫 번째 멤버로 있습니다. 이러한 형식 중 하나를 사용하여 소스 음성을 만들 때 형식의 구조를 WAVEFORMATEX 구조체로 캐스팅하고 pSourceFormat의 값으로 사용합니다.

[in] Flags

원본 음성의 동작을 지정하는 플래그입니다. 플래그는 0이거나 다음 중 하나 이상의 조합일 수 있습니다.

값	Description
XAUDIO2_VOICE_NOPITCH	음성에서 피치 컨트롤을 사용할 수 없습니다.
XAUDIO2_VOICE_NOSRC	음성에서 샘플 속도 변환을 사용할 수 없습니다. 음성의 출력은 동일한 샘플 속도를 가져야 합니다. 참고 XAUDIO2_VOICE_NOSRC 플래그를 사용하면 음성이 XAUDIO2_VOICE_NOPITCH 플래그도 지정된 것처럼 동작합니다.
XAUDIO2_VOICE_USEFILTER	필터 효과는 이 음성에서 사용할 수 있어야 합니다.

참고 XAUDIO2_VOICE_MUSIC 플래그는 Windows에서 지원되지 않습니다.

[in] MaxFrequencyRatio

이 음성에서 설정할 수 있는 가장 높은 허용 빈도 비율입니다. 이 인수의 값은 XAUDIO2_MIN_FREQ_RATIO XAUDIO2_MAX_FREQ_RATIO 사이여야 합니다. IXAudio2SourceVoice::SetFrequencyRatio에 대한 후속 호출은 XAUDIO2_MIN_FREQ_RATIO MaxFrequencyRatio 간에 고정됩니다. 이 인수의 최대값은 최대 10 옥타브까지 피치를 발생시키는 XAUDIO2_MAX_FREQ_RATIO 정의됩니다.

MaxFrequencyRatio가 1.0보다 작은 경우 음성은 생성 직후 해당 비율을 사용합니다(기본값인 1.0이 아닌).

Xbox 360
XMA 음성의 경우 MaxFrequencyRatio 인수와 음성의 샘플 속도에 대한 제한이 하나 더 있습니다. 이 두 숫자의 곱은 한 채널 음성의 XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO 초과하거나 다른 수의 채널이 있는 음성에 대한 XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL 초과할 수 없습니다. MaxFrequencyRatio에 지정된 값이 지정된 형식에 비해 너무 높으면 CreateSourceVoice 호출이 실패하고 디버그 메시지가 생성됩니다.

Xbox 360

XMA 음성의 경우 MaxFrequencyRatio 인수와 음성의 샘플 속도에 대한 제한이 하나 더 있습니다. 이 두 숫자의 곱은 한 채널 음성의 XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO 초과하거나 다른 수의 채널이 있는 음성에 대한 XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL 초과할 수 없습니다. MaxFrequencyRatio에 지정된 값이 지정된 형식에 비해 너무 높으면 CreateSourceVoice 호출이 실패하고 디버그 메시지가 생성됩니다.

참고 가능한 가장 낮은 MaxFrequencyRatio 값을 사용하여 XAudio2의 메모리 사용량을 줄일 수 있습니다.

[in, optional] pCallback

클라이언트 제공 콜백 인터페이스 IXAudio2VoiceCallback에 대한 포인터입니다.

[in, out] pSendList

원본 음성의 대상 음성 집합을 설명하는 XAUDIO2_VOICE_SENDS 구조 목록의 포인터입니다. pSendList가 NULL인 경우 전송 목록은 기본적으로 생성된 첫 번째 마스터링 음성에 대한 단일 출력으로 설정됩니다.

[in, optional] pEffectChain

소스 음성에서 사용할 효과 체인을 설명하는 XAUDIO2_EFFECT_CHAIN 구조 목록의 포인터입니다.

반환 값

성공하면 S_OK 반환합니다. 그렇지 않으면 오류 코드입니다.

XAudio2 관련 오류 코드에 대한 설명은 XAudio2 오류 코드를 참조하세요.

설명

원본 음성은 클라이언트에서 오디오 데이터를 읽습니다. 데이터를 처리하고 XAudio2 처리 그래프로 보냅니다.

원본 음성에는 데이터를 원본 형식 샘플 속도에서 음성 보내기 목록에 필요한 출력 속도로 변환하는 가변 속도 샘플 속도 변환이 포함됩니다. NULL 보내기 목록을 사용하는 경우 대상 샘플 속도는 마스터링 음성의 입력 샘플 속도가 됩니다. pSendList에서 단일 음성을 제공하는 경우 해당 음성의 입력 샘플 속도는 대상 속도입니다. pSendList에서 여러 음성을 제공하는 경우 모든 원본 음성의 출력 음성이 동일한 입력 샘플 속도로 실행되어야 합니다.

마스터링 음성이 존재할 때까지 소스 또는 서브믹스 음성을 만들 수 없으며 소스 또는 서브믹스 음성이 여전히 있는 경우 마스터링 음성을 삭제할 수 없습니다.

원본 음성은 항상 서브믹스 또는 마스터링 음성 전에 처리됩니다. 즉, 처리 순서를 제어하기 위해 ProcessingStage 매개 변수가 필요하지 않습니다.

처음 만들면 원본 음성이 중지된 상태입니다.

XAudio2는 동일한 형식의 음성에 내부 메모리 풀러를 사용합니다. 즉, 더 많은 음성이 생성되고 제거되면 음성에 대한 메모리 할당이 덜 자주 발생합니다. Just-In-Time 할당을 최소화하기 위해 타이틀은 미리 필요한 예상 최대 음성 수를 만든 다음 필요에 따라 삭제할 수 있습니다. 그러면 XAudio2 풀에서 음성이 다시 사용됩니다. 메모리 풀은 XAudio2 엔진 instance 연결됩니다. XAudio2 개체를 삭제하고 필요에 따라 다시 만들어 XAudio2 엔진의 instance 사용하는 모든 메모리를 회수할 수 있습니다(필요에 따라 메모리 풀이 사전 할당을 통해 증가하도록 강요).

콜백 내에서 CreateSourceVoice 를 호출하는 것은 잘못되었습니다(즉, IXAudio2EngineCallback 또는 IXAudio2VoiceCallback). 콜백 내에서 CreateSourceVoice 를 호출하면 XAUDIO2_E_INVALID_CALL 반환됩니다.

pEffectChain 인수로 전달되는 XAUDIO2_EFFECT_CHAIN 및 그 안에 포함된 모든 XAUDIO2_EFFECT_DESCRIPTOR 정보는 CreateSourceVoice 가 성공적으로 완료된 후 더 이상 필요하지 않으며 CreateSourceVoice 가 호출된 직후에 삭제될 수 있습니다.