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

아티클
08/28/2023

마스터 음성을 만들고 구성합니다.

구문

HRESULT CreateMasteringVoice(
  [out]          IXAudio2MasteringVoice     **ppMasteringVoice,
  [in]           UINT32                     InputChannels,
  [in]           UINT32                     InputSampleRate,
  [in]           UINT32                     Flags,
  [in]           LPCWSTR                    szDeviceId,
  [in, optional] const XAUDIO2_EFFECT_CHAIN *pEffectChain,
  [in, optional] AUDIO_STREAM_CATEGORY      StreamCategory
);

매개 변수

[out] ppMasteringVoice

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

[in] InputChannels

마스터링 음성이 입력 오디오에서 기대하는 채널 수입니다. InputChannels 는 XAUDIO2_MAX_AUDIO_CHANNELS 작거나 같아야 합니다.

InputChannels를 XAUDIO2_DEFAULT_CHANNELS 설정하여 XAudio2가 시스템 스피커 구성 설정을 검색하도록 할 수 있습니다.

[in] InputSampleRate

마스터링 음성의 입력 오디오 데이터의 샘플 속도입니다. 이 속도는 XAUDIO2_QUANTUM_DENOMINATOR 배수여야 합니다. InputSampleRate 는 XAUDIO2_MIN_SAMPLE_RATE XAUDIO2_MAX_SAMPLE_RATE 사이여야 합니다.

InputSampleRate를 XAUDIO2_DEFAULT_SAMPLERATE 설정할 수 있으며 기본값은 현재 플랫폼에 의해 결정됩니다.

Windows XP의 기본값은 44100입니다.

Windows Vista 및 Windows 7은 기본적으로 소리 제어판 지정된 설정으로 설정됩니다. 이 설정의 기본값은 44100(또는 드라이버에서 필요한 경우 48000)입니다.

플래그

[in] Flags

마스터 음성의 동작을 지정하는 플래그입니다. 0 또는 XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT일 수 있습니다.

[in] szDeviceId

출력 오디오를 받을 디바이스의 식별자입니다. NULL의 기본값을 지정하면 XAudio2에서 전역 기본 오디오 디바이스를 선택합니다. Windows 10 이상에서 NULL은 Flags에 전달되지 않는 한 XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT WASAPI 가상화된 클라이언트에 옵트인합니다.

[in, optional] pEffectChain

마스터링 음성에 사용할 효과 체인을 설명하는 XAUDIO2_EFFECT_CHAIN 구조체 또는 효과를 사용하지 않는 NULL에 대한 포인터입니다.

[in, optional] StreamCategory

이 마스터링 음성에 사용할 오디오 스트림 범주입니다.

반환 값

성공하면 S_OK 반환합니다. 그렇지 않으면 오류 코드입니다. 기본 오디오 디바이스가 없고 NULL이 szDeviceId 매개 변수로 전달되면 ERROR_NOT_FOUND 반환합니다.

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

설명

마스터링 음성은 하나 이상의 원본 또는 서브믹스 음성의 출력을 받습니다. 데이터를 처리하고 오디오 출력 디바이스로 보냅니다.

일반적으로 대부분의 타이틀 오디오 콘텐츠에서 사용되는 입력 샘플 속도로 마스터링 음성을 만들어야 합니다. 마스터링 음성은 이 입력 샘플 속도에서 실제 디바이스 출력 속도로 샘플 속도 변환을 수행합니다.

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

마스터링 음성은 항상 모든 원본 및 서브믹스 음성 후에 처리됩니다. 즉, 처리 순서를 제어하기 위해 ProcessingStage 매개 변수를 지정할 필요가 없습니다.

XAudio2는 마스터링 음성 하나만 한 번에 존재할 수 있습니다. 둘 이상의 음성을 만들려고 하면 XAUDIO2_E_INVALID_CALL 반환됩니다. 다른 오디오 범주가 설정된 출력 디바이스와 같은 추가 마스터링 음성이 필요한 경우 추가 XAudio2 instance 만들어야 합니다.

처음 만들면 음성 마스터가 시작됨 상태가 됩니다.

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

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

DirectX SDK XAUDIO2 버전의 CreateMasteringVoice 는 szDeviceId 및 StreamCategory 인수 대신 DeviceIndex 인수를 사용했습니다. 이는 표준 Windows 디바이스 열거형 모델에 필요한 변경 내용을 반영합니다.