XAudio 2.9의 재배포 가능 버전에 대한 개발자 가이드

아티클
06/13/2023

XAudio 2.9 버전은 NuGet 패키지로 사용할 수 있습니다. 개발자는 이 버전의 XAudio 2.9를 앱으로 재배포할 수 있습니다. 이렇게 하면 앱이 운영 체제 이미지의 일부로 XAudio 2.9를 포함하지 않는 이전 버전의 Windows에서 XAudio 2.9를 사용할 수 있습니다. 이 재배포 가능 패키지는 2010년 이후 XAudio 2.7이 업데이트되지 않았으므로 DirectX SDK에서 XAudio 2.7을 재배포하는 대신 사용하는 것이 좋습니다.

DirectX 개발자를 위한 더 많은 리소스를 보려면 DirectX 방문 페이지를 방문해야 합니다.

지원 플랫폼

XAudio 2.9 NuGet 패키지(Microsoft.XAudio2.Redist.*.nupkg)에는 XAudio 2.9 API를 구현하는 32비트 및 64비트 버전의 DLL이 포함되어 있습니다. DLL을 XAUDIO2_9REDIST.DLL 호출합니다. 이 DLL은 Windows 7 SP1, Windows 8, Windows 8.1 및 Windows 10 작동합니다.

DLL이 Windows 10 시스템에서 사용되는 경우 운영 체제의 일부인 XAUDIO2_9.DLL 버전 번호를 확인하고 운영 체제가 최신인 경우 모든 API 호출을 운영 체제의 XAUDIO2_9.DLL 위임합니다. 이렇게 하면 앱이 항상 현재 플랫폼에서 사용할 수 있는 최신 버전의 XAudio 2.9를 사용할 수 있습니다.

DLL은 Xbox One용이 아닙니다. Xbox One에서 사용되는 경우 DLL은 항상 모든 API 호출을 Xbox One 운영 체제의 XAUDIO2_9.DLL 위임합니다.

DLL은 UWP 앱용이 아닙니다. UWP 앱은 운영 체제의 일부인 XAUDIO2_9.DLL 사용해야 합니다.

NuGet 패키지 설치

NuGet 패키지를 설치하는 가장 쉬운 방법은 Microsoft Visual Studio에서 NuGet 패키지 관리자 를 사용하는 것입니다. 이렇게 하면 Visual Studio 프로젝트 파일이 Microsoft.XAudio2.Redist.targets를 포함하도록 자동으로 업데이트됩니다. .targets 파일은 XAudio2의 헤더 파일이 포함된 Include 폴더를 프로젝트 포함 경로 컬렉션에 추가합니다. .targets 파일은 XAUDIO2REDIST와 .DLL 또는 .EXE 링크를 만듭니다. LIB 및 XAPOBASEREDIST. Lib.

라이브러리 XAPOBASEREDIST입니다. LIB는 사용자 지정 XAudio 처리 개체(XAPO)를 방해하려는 경우에만 필요하며 사용하지 않는 경우 Microsoft.XAudio2.Redist.targets 에서 제거할 수 있습니다.

다른 도구를 사용하여 NuGet 패키지의 콘텐츠를 추출하거나 파일 확장명 이름을 바꿔 ZIP 추출기 도구를 사용하여 파일을 .zip 추출할 수도 있습니다.

VC++ 패키지 관리자에 사용할 수 있는 포트도 xaudio2redist 있습니다.

앱 컴파일

포함할 헤더 선택

XAudio 2.9 NuGet 패키지에는 Windows 10 SDK에 포함된 동일한 XAudio2 헤더 파일이 포함되어 있습니다. 그러나 헤더 파일에는 이전 버전의 Windows를 포함하여 지원되는 모든 플랫폼을 명시적으로 대상으로 지정하는 동안 사용할 수 있도록 일부 조정이 있었습니다.

Microsoft Visual Studio 에서 NuGet 패키지 관리자를 사용하여 NuGet 패키지를 설치 하는 경우 헤더 파일의 경로가 Windows SDK 헤더 파일의 경로 앞에 배치됩니다. 즉, 프로젝트의 코드에 XAUDIO2가 포함됩니다. H 헤더는 NuGet 패키지에서 플랫폼 간 헤더를 선택합니다. 이는 일반적으로 원하는 동작입니다.

포함 헤더의 경로를 프로젝트에 수동으로 추가하는 경우 OS 버전별 XAUDIO2가 발생할 수 있으므로 프로젝트를 잘못 지정하면 주의해야 합니다 . XAUDIO2.H 의 플랫폼 간 버전이 아닌 Windows SDK에서 포함할 H입니다.

헤더 포함을 오류 발생 가능성이 낮게 하기 위해 NuGet 패키지에는 "REDIST"가 추가된 각 헤더 버전이 포함됩니다. 예를 들어 XAUDIO2 외에. H, NuGet 패키지에는 XAUDIO2REDIST.H도 포함됩니다. 원하는 경우 코드에 XAUDIO2REDIST가 직접 포함될 수 있습니다. H - 사용 중인 헤더 파일에 대한 모호성을 제거합니다. -REDIST를 포함하는 경우. 헤더 파일의 H 버전으로, 포함 파일 디렉터리를 프로젝트 파일에 나열하는 순서는 중요하지 않습니다.

앱이 Xbox One용으로 컴파일되는 경우에도 XAUDIO2를 계속 포함해야 합니다. 일부 Xbox One 특정 API는 XAUDIO2REDIST.H에서 제외되기 때문에 Xbox One용으로 컴파일할 때 H입니다. 이 NuGet 패키지는 Xbox One용이 아닙니다.

DLL 로드

앱을 XAUDIO2REDIST와 연결하는 것이 좋습니다. LIB 및 XAUDIO2_9REDIST.DLL 앱의 실행 파일과 동일한 폴더에 설치합니다. 이렇게 하면 실행 파일이 시작되는 즉시 XAUDIO2_9REDIST.DLL 로드됩니다. 그러나 원하는 경우 LoadLibraryEx 및 GetProcAddress 를 사용하여 요청 시 XAUDIO2_9REDIST.DLL 로드할 수 있습니다. 앱이 항상 XAudio2 API를 사용할 필요가 없는 경우 좋은 솔루션입니다. 그러나 이렇게 하면 백그라운드 스레드가 DLL에서 코드를 계속 실행하는 경우 DLL을 언로드하려고 하면 충돌이 발생할 수 있으므로 앱이 종료될 때까지 XAUDIO2_9REDIST.DLL 로드된 상태로 유지해야 합니다.

이전 XAudio 2.7과 달리 CoCreateInstance를 사용하여 DLL을 로드할 수 없습니다.

DLL 서명 확인

XAUDIO2_9REDIST.DLL 이진 파일은 SHA-2 서명을 사용하여 Microsoft에서 서명합니다. 서명의 유효성을 검사하려는 모든 코드(예: 게임의 치트 방지 모듈)는 SHA-2를 지원해야 합니다. Windows 7 SP1은 원래 SHA-2를 지원하지 않았으며 해당 기능을 추가하려면 업데이트가 필요합니다. 업데이트는 KB4474419로 제공됩니다.

테스트

오류 처리

예를 들어 헤드폰이 연결되어 있거나 플러그를 뽑을 때 게임 오디오 장치의 변경을 처리할 수 있는지 테스트하는 것이 중요합니다. 44.1kHz 샘플링 속도만 지원하는 헤드폰으로 테스트해야 합니다. 많은 저사용 USB 헤드폰 및 Bluetooth 헤드셋은 44.1kHz만 지원합니다. 48kHz 샘플링 속도와 44.1kHz 샘플링 속도 간의 전환으로 인해 가상 오디오 엔드포인트 기능을 사용하는 경우에도 오류가 발생할 수 있습니다. 헤드폰도 48kHz를 지원하는 경우에는 오류가 발생하지 않습니다. 가상 오디오 엔드포인트 기능은 Windows 7 SP1에서 사용할 수 없습니다.

오디오 엔드포인트의 변경에서 자동으로 복구할 수 없는 경우 XAudio 2.9에서 반환된 오류 코드는 XAUDIO2_E_DEVICE_INVALIDATED. 그러나 앱은 특정 값이 있는 오류 코드에 대한 종속성을 하드 코딩하지 않는 것이 좋습니다.

오류 알림을 받도록 앱은 IXAudio2EngineCallback 인터페이스를 구현하고 IXAudio2::RegisterForCallbacks 메서드를 호출하여 해당 인터페이스에 대한 포인터를 제공해야 합니다. 재생 중에 오류가 발생하면 XAudio2 API에서 앱의 IXAudio2EngineCallback::OnCriticalError 구현이 호출됩니다.

오디오 파이프라인이 일시 중지된 경우 IXAudio2EngineCallback::OnCriticalError 가 반드시 호출되지는 않습니다. 예를 들어 사용자가 앱을 최소화하거나 어떤 이유로든 앱이 일시 중단되면 오디오 재생이 일시 중지될 수 있습니다. 이 시간 동안 오디오 디바이스가 변경되면 앱이 IXAudio2::StartEngine 및/또는 IXAudio2SourceVoice::Start를 호출할 때만 오류가 반환됩니다. 앱에서 재생을 일시 중지할 수 있는 경우 재생이 일시 중지된 동안 오디오 장치 변경을 테스트하여 앱이 이 상황에서 계속 복구할 수 있는지 확인해야 합니다.

XAudio 2.7과 비교한 XAudio 2.9 API 차이

이 섹션에서는 XAudio 2.7과 XAudio 2.9의 재배포 가능 버전 간의 몇 가지 API 차이점에 대한 요약을 제공합니다.

지원되는 형식

XAudio 2.9는 PC에서 다음 입력 형식을 지원합니다.

선형 16비트 PCM
선형 32비트 Float PCM
16비트 ADPCM
xWMA

XMA 형식은 Xbox One에서만 지원됩니다.

기본 CPU 코어

오디오 처리 스레드에 사용해야 하는 CPU 코어 XAudio 2.9를 지정할 수 있습니다. 그러나 일반적으로 XAudio 2.9에서 이 값을 단독으로 선택할 수 있도록 하는 것이 좋습니다. 이 작업은 XAudio2Create를 XAUDIO2_USE_DEFAULT_PROCESSOR 호출에서 XAudio2Processor 매개 변수를 설정하여 수행됩니다.

XAudio 2.9는 Xbox One에서 PC와 다른 CPU 코어를 선택합니다. IXAudio2Extension::GetProcessor 메서드를 사용하여 선택한 CPU 코어 XAudio2를 확인할 수 있습니다.

가상 오디오 엔드포인트

XAudio 2.9는 Windows 8 이상에서 실행할 때 기본적으로 가상 오디오 엔드포인트를 사용합니다. 즉, XAudio 2.9를 사용하는 동안 기본 오디오 엔드포인트가 변경되면 새 오디오 엔드포인트로 자동 전환하려고 시도합니다. 기본 오디오 엔드포인트가 USB를 통해 연결된 헤드폰 쌍인 경우 사용자가 헤드폰을 분리할 때 이 문제가 발생할 수 있는 경우의 예입니다. 이로 인해 스피커가 새로운 기본 오디오 엔드포인트가 됩니다.

앱이 IXAudio2::CreateMasteringVoice를 호출할 때 특정 오디오 형식을 지정하는 경우 XAudio 2.9에서 이 스위치를 수행하지 못할 수 있습니다. 예를 들어 앱에서 마스터링 음성이 48kHz 샘플링 속도를 사용하고 새 오디오 디바이스가 44.1kHz만 지원한다고 지정하면 자동 스위치가 실패하고 XAudio 2.9가 XAUDIO2_E_DEVICE_INVALIDATED 오류를 보고합니다.

앱은 XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT 플래그를 IXAudio2::CreateMasteringVoice에 전달하여 가상 오디오 엔드포인트 사용을 옵트아웃할 수 있습니다.

가상 오디오 엔드포인트는 Windows 7 SP1에서 사용할 수 없습니다. XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT 플래그는 Windows 7 SP1에 영향을 주지 않습니다.

오디오 범주

앱은 오디오 스트림에 대한 범주를 지정해야 합니다. 이 작업은 IXAudio2::CreateMasteringVoice 메서드를 호출할 때 AudioCategory 열거형의 값을 제공하여 수행됩니다. 예를 들어 AudioCategory_GameEffects. 오디오 범주는 Windows가 소리를 처리하는 방법 또는 볼륨 제어판의 오디오 스트림을 나타내는 방법에 영향을 줄 수 있습니다. 오디오 범주는 가상 서라운드 사운드 를 자동으로 사용하도록 설정하는 경우에도 영향을 줍니다.

오디오 처리 기간 양자

대부분의 PC에서 XAudio 2.9는 오디오를 10밀리초 청크로 처리합니다. 이를 처리 양자라고 합니다. 그러나 이 양자의 기간은 일부 하드웨어에서 10밀리초와 다를 수 있습니다. 정확한 양자를 알아야 하는 앱은 IXAudio2Extension::GetProcessingQuantum 메서드를 호출하여 값을 검색할 수 있습니다.

공간 사운드 및 가상 서라운드

Windows 10 1903 업데이트부터 XAudio 2.9는 특정 조건이 충족되는 경우 가상 서라운드 사운드를 자동으로 사용합니다. Windows 10 1903 이상에서 다중 채널 사운드를 생성하는 게임을 테스트하여 게임이 예상대로 들리는지 확인하는 것이 좋습니다. 이 기능을 테스트하는 방법에 대한 자세한 내용은 공간 사운드 테스트 섹션을 참조하세요.

일반적으로 XAudio 2.9는 오디오 엔드포인트에서 지원하는 "물리적" 오디오 채널 수와 일치하도록 모든 다중 채널 오디오를 접습니다. 예를 들어 게임에서 7.1 채널 오디오 소스를 제공하지만 헤드폰에서 사운드가 재생되는 경우 XAudio 2.9는 업계 표준 접기 매트릭스를 사용하여 7.1 채널 오디오를 스테레오로 접습니다. PC가 HDMI 오디오 엔드포인트에 연결된 경우 7.1 채널 오디오는 HDMI 연결을 통해 있는 그대로 전송됩니다.

Windows 10 오디오를 사용자가 선택한 공간 사운드 형식으로 인코딩하는 중앙 집중식 인코더를 사용하여 공간 오디오에 대한 지원을 추가합니다. Windows 10 Windows Sonic이라는 공간 사운드 형식으로 제공됩니다. Dolby Atmos for Headphones 같은 다른 형식은 Microsoft Store에서 다운로드할 수 있습니다. Windows Sonic 및 Dolby Atmos for Headphones 같은 일부 공간 사운드 형식은 스테레오 오디오 엔드포인트에서 사용하도록 설계되었습니다. 이러한 형식은 "가상" 서라운드 사운드 효과를 달성하는 독점 알고리즘을 사용하여 서라운드 사운드를 스테레오로 접습니다. 즉, 수신기는 헤드폰만 착용하거나 스테레오 스피커 한 켤레에서 듣는 동안에도 3D 공간의 다른 위치에서 나타나는 소리를 인식할 수 있습니다.

XAudio 2.9에 포함된 X3DAudio API를 사용하여 비슷한 효과를 가져올 수 있습니다. 기본 차이점은 X3DAudio를 사용하려면 앱 개발자가 3D 오디오를 명시적으로 프로그래밍해야 하는 반면 가상 서라운드 사운드는 모든 거래 채널 기반 사운드 소스에 자동으로 적용된다는 점입니다.

Windows 10 1903 이상에서는 XAudio 2.9를 사용하는 게임은 오디오 엔드포인트에서 사용자가 사용하도록 설정한 시스템 차원의 공간 사운드 형식(있는 경우)을 사용합니다. 즉, XAudio 2.9는 스테레오로 서라운드 사운드의 일반적인 접이식 다운을 수행하지 않습니다. 대신, 서라운드 사운드 신호는 가상 서라운드 사운드 효과를 얻기 위해 공간 사운드 인코더(예: Windows Sonic)에 전달됩니다.

CreateHrtfApo

CreateHrtfApo 함수는 Windows 10 사용할 수 있습니다. XAudio 2.9 재배포 가능 패키지에서는 구현되지 않습니다.