Panduan pengembang untuk versi XAudio 2.9 yang dapat didistribusikan ulang

Artikel
06/13/2023

Versi XAudio 2.9 tersedia sebagai paket NuGet. Pengembang dapat mendistribusikan ulang versi XAudio 2.9 ini dengan aplikasi mereka. Ini memungkinkan aplikasi untuk menggunakan XAudio 2.9 pada versi Windows yang lebih lama yang tidak menyertakan XAudio 2.9 sebagai bagian dari gambar sistem operasi. Penggunaan redistributable ini lebih disukai daripada mendistribusikan ulang XAudio 2.7 dari DirectX SDK, karena XAudio 2.7 belum diperbarui sejak 2010.

Pastikan Anda mengunjungi Halaman Arahan DirectX untuk sumber daya lainnya untuk pengembang DirectX.

Platform yang didukung

Paket XAudio 2.9 NuGet (Microsoft.XAudio2.Redist.*.nupkg) menyertakan DLL versi 32-bit dan 64-bit yang mengimplementasikan API XAudio 2.9. DLL disebut XAUDIO2_9REDIST.DLL. DLL ini akan bekerja pada Windows 7 SP1, Windows 8, Windows 8.1 dan Windows 10.

Ketika DLL digunakan pada sistem Windows 10, DLL memeriksa nomor versi XAUDIO2_9.DLL yang merupakan bagian dari sistem operasi, dan jika sistem operasi lebih baru, itu akan mendelegasikan semua panggilan API untuk XAUDIO2_9.DLL dalam sistem operasi. Ini memastikan bahwa aplikasi selalu menggunakan versi terbaru XAudio 2.9 yang tersedia di platform saat ini.

DLL tidak ditujukan untuk Xbox One. Jika digunakan pada Xbox One, DLL akan selalu mendelegasikan semua panggilan API untuk XAUDIO2_9.DLL dalam sistem operasi Xbox One.

DLL tidak ditujukan untuk aplikasi UWP. Aplikasi UWP harus menggunakan XAUDIO2_9.DLL yang merupakan bagian dari sistem operasi.

Menginstal paket NuGet

Cara term mudah untuk menginstal paket NuGet adalah dengan menggunakan NuGet Package Manager di Microsoft Visual Studio. Jika Anda melakukan ini, file proyek Visual Studio Anda akan diperbarui secara otomatis untuk menyertakan Microsoft.XAudio2.Redist.targets. File .targets menambahkan folder Sertakan dengan file header untuk XAudio2 ke kumpulan proyek Anda termasuk jalur. File .targets juga akan membuat tautan .DLL atau .EXE Anda dengan XAUDIO2REDIST. LIB dan XAPOBASEREDIST. LIB.

Pustaka XAPOBASEREDIST. LIB hanya diperlukan jika Anda berniat untuk memberlakukan XAudio Processing Object (XAPO) kustom dan Anda dapat menghapusnya dari Microsoft.XAudio2.Redist.targets jika tidak digunakan.

Anda juga dapat menggunakan alat lain untuk mengekstrak konten paket NuGet, atau bahkan mengganti nama ekstensi file menjadi .zip dan mengekstrak file dengan alat ekstraktor ZIP apa pun.

Ada juga port yang xaudio2redist tersedia untuk Manajer Paket VC++.

Mengkompilasi aplikasi Anda

Memilih header mana yang akan disertakan

Paket XAudio 2.9 NuGet menyertakan file header XAudio2 yang sama yang disertakan dalam SDK Windows 10. Namun, file header telah memiliki beberapa penyesuaian untuk memastikan bahwa Anda dapat menggunakannya sambil secara eksplisit menargetkan semua platform yang didukung, termasuk versi Windows yang lebih lama.

Jika Anda menginstal paket NuGet menggunakan Manajer Paket NuGet di Microsoft Visual Studio, maka jalur ke file header ditempatkan di depan jalur ke file header Windows SDK. Itu berarti bahwa jika kode dalam proyek Anda menyertakan XAUDIO2. Header H, itu akan mengambil header lintas platform dari paket NuGet. Ini biasanya perilaku yang diinginkan.

Anda harus berhati-hati jika menambahkan jalur ke header sertakan secara manual ke proyek, karena menentukannya dalam urutan yang salah dapat menyebabkan XAUDIO2 spesifik versi OS. H yang akan disertakan dari Windows SDK, bukan versi lintas platform XAUDIO2.H.

Untuk membuat penyertaan header kurang rawan kesalahan, paket NuGet berisi versi setiap header dengan "REDIST" yang ditambahkan ke dalamnya. Misalnya, selain XAUDIO2. H, paket NuGet juga mencakup XAUDIO2REDIST.H. Jika mau, kode Anda dapat langsung menyertakan XAUDIO2REDIST. H untuk menghilangkan ambiguitas tentang file header mana yang sedang digunakan. Saat menyertakan -REDIST. Versi H dari file header, urutan di mana direktori file sertakan tercantum dalam file proyek tidak masalah.

Perhatikan bahwa jika aplikasi Anda juga sedang dikompilasi untuk Xbox One, Anda harus terus menyertakan XAUDIO2. H saat mengkompilasi untuk Xbox One, karena beberapa API khusus Xbox One dikecualikan dari XAUDIO2REDIST.H. Paket NuGet ini tidak ditujukan untuk Xbox One.

Memuat DLL

Sebaiknya tautkan aplikasi Anda dengan XAUDIO2REDIST. LIB dan instal XAUDIO2_9REDIST.DLL di folder yang sama dengan aplikasi Anda yang dapat dieksekusi. Ini akan menyebabkan XAUDIO2_9REDIST.DLL dimuat segera setelah executable Anda diluncurkan. Namun, jika mau, Anda dapat menggunakan LoadLibraryEx dan GetProcAddress untuk memuat XAUDIO2_9REDIST.DLL sesuai permintaan. Ini adalah solusi yang baik jika aplikasi Anda tidak selalu perlu menggunakan API XAudio2. Tetapi jika Anda melakukan ini, Anda harus menjaga XAUDIO2_9REDIST.DLL dimuat sampai aplikasi keluar, karena mencoba untuk membongkar DLL dapat menyebabkan crash jika utas latar belakang masih mengeksekusi kode di DLL.

Tidak seperti XAudio 2.7 yang lebih lama, tidak mungkin menggunakan CoCreateInstance untuk memuat DLL.

Memverifikasi tanda tangan DLL

Biner XAUDIO2_9REDIST.DLL ditandatangani oleh Microsoft menggunakan tanda tangan SHA-2. Kode apa pun yang mencoba memvalidasi tanda tangan, misalnya, modul anti-cheat untuk game, oleh karena itu perlu mendukung SHA-2. Perhatikan bahwa Windows 7 SP1 awalnya tidak mendukung SHA-2 dan memerlukan pembaruan untuk menambahkan fungsionalitas tersebut. Pembaruan tersedia sebagai KB4474419.

Pengujian

Suara spasial dalam versi Windows 10 yang lebih baru

Dimulai dengan pembaruan Windows 10 1903, XAudio 2.9 secara otomatis menggunakan suara surround virtual, jika kondisi tertentu terpenuhi. Sebaiknya uji game yang menghasilkan suara multi-saluran pada Windows 10 1903 (atau yang lebih baru) untuk memverifikasi bahwa game terdengar seperti yang diharapkan.

Mengaktifkan suara spasial

Pengguna dapat mengaktifkan format suara spasial dengan mengklik kanan ikon speaker di baki sistem Windows.

XAudio 2.9 hanya akan menggunakan format suara spasial yang dipilih pengguna jika proses yang menggunakan API XAudio2 diakui sebagai game oleh Windows Game Bar. Selama pengembangan, ada kemungkinan bahwa prosesnya belum diakui sebagai game oleh Game Bar. Untuk mengubahnya, gunakan keyboard Win+G short-cut untuk memunculkan Game Bar saat permainan sedang berjalan. Kemudian klik ikon "Pengaturan" dan centang kotak centang yang mengatakan, "Ingat bahwa ini adalah permainan".

Memilih keluar dari suara spasial

Ada cara untuk menolak XAudio2 menggunakan encoder suara spasial dengan menentukan nilai tertentu untuk parameter AUDIO_STREAM_CATEGORY di IXAudio2::CreateMasteringVoice.

Suara spasial diaktifkan untuk kategori ini:

AudioCategory_ForegroundOnlyMedia
AudioCategory_GameEffects
AudioCategory_GameMedia
AudioCategory_Movie
AudioCategory_Media

Suara spasial tidak diaktifkan jika salah satu kategori berikut ditentukan:

AudioCategory_Other
AudioCategory_Communications
AudioCategory_Alerts
AudioCategory_SoundEffects
AudioCategory_GameChat
AudioCategory_Speech

Penanganan kesalahan

Penting untuk menguji bahwa game Dapat menangani perubahan perangkat audio, misalnya, ketika headphone dicolokkan, atau dilepas. Ini harus diuji dengan headphone yang hanya mendukung laju pengambilan sampel 44,1 kHz. Banyak headphone USB low-end dan headset Bluetooth hanya mendukung 44,1 kHz. Transisi antara laju pengambilan sampel 48 kHz dan laju pengambilan sampel 44,1 kHz dapat menyebabkan kesalahan bahkan ketika fitur titik akhir audio virtual digunakan. Kesalahan tidak akan terjadi jika headphone juga mendukung 48 kHz. Perhatikan bahwa fitur titik akhir audio virtual tidak tersedia di Windows 7 SP1.

Kode kesalahan yang dikembalikan oleh XAudio 2.9 ketika tidak dapat memulihkan secara otomatis dari perubahan titik akhir audio XAUDIO2_E_DEVICE_INVALIDATED. Namun, kami menyarankan agar aplikasi tidak mengodekan dependensi secara permanen pada kode kesalahan yang memiliki nilai tertentu.

Untuk diberi tahu tentang kesalahan, aplikasi harus mengimplementasikan antarmuka IXAudio2EngineCallback dan menyediakan pointer ke antarmuka tersebut dengan memanggil metode IXAudio2::RegisterForCallbacks . Implementasi aplikasi dari IXAudio2EngineCallback::OnCriticalError akan dipanggil oleh API XAudio2 jika terjadi kesalahan selama pemutaran.

Perhatikan bahwa IXAudio2EngineCallback::OnCriticalError belum tentu dipanggil jika alur audio dijeda. Misalnya, jika pengguna meminimalkan aplikasi, atau aplikasi ditangguhkan karena alasan apa pun, pemutaran audio mungkin dijeda. Jika perubahan perangkat audio terjadi selama waktu ini, kesalahan hanya dikembalikan saat aplikasi memanggil IXAudio2::StartEngine dan/atau memanggil IXAudio2SourceVoice::Start. Jika pemutaran dapat dijeda dengan aplikasi, Anda harus menguji perubahan perangkat audio saat pemutaran dijeda, untuk memverifikasi bahwa aplikasi masih dapat pulih dari situasi ini.

Perbedaan API XAudio 2.9 dibandingkan dengan XAudio 2.7

Bagian ini menyediakan ringkasan beberapa perbedaan API antara XAudio 2.7 dan versi XAudio 2.9 yang dapat didistribusikan ulang.

Format yang didukung

XAudio 2.9 mendukung format input ini di PC:

Linear 16-bit PCM
Linear 32-bit Float PCM
ADPCM 16-bit
xWMA

Format XMA hanya didukung pada Xbox One.

Inti CPU pilihan

Dimungkinkan untuk menentukan inti CPU XAudio 2.9 mana yang harus digunakan untuk utas pemrosesan audionya. Namun, biasanya lebih disukai untuk membiarkan XAudio 2.9 memilih nilai ini dengan sendirinya. Ini dilakukan dengan mengatur parameter XAudio2Processor dalam panggilan ke XAudio2Buat ke XAUDIO2_USE_DEFAULT_PROCESSOR.

XAudio 2.9 akan memilih core CPU yang berbeda pada Xbox One daripada di PC. Metode IXAudio2Extension::GetProcessor dapat digunakan untuk menentukan inti CPU XAudio2 mana yang telah dipilih.

Titik akhir audio virtual

XAudio 2.9 akan menggunakan titik akhir audio virtual secara default, saat berjalan di Windows 8 atau yang lebih baru. Ini berarti bahwa jika titik akhir audio default berubah saat XAudio 2.9 digunakan, titik akhir audio baru akan mencoba beralih secara otomatis ke titik akhir audio baru. Contoh kapan hal ini dapat terjadi ketika titik akhir audio default adalah sepasang headphone yang terhubung melalui USB, lalu pengguna men cabut headphone. Ini akan menyebabkan speaker menjadi titik akhir audio default baru.

Jika aplikasi menentukan format audio tertentu saat memanggil IXAudio2::CreateMasteringVoice, XAudio 2.9 mungkin tidak dapat melakukan sakelar ini. Misalnya, jika aplikasi menentukan bahwa Suara Mastering akan menggunakan laju pengambilan sampel 48 kHz dan perangkat audio baru hanya mendukung 44,1 kHz, sakelar otomatis akan gagal, dan XAudio 2.9 akan melaporkan kesalahan XAUDIO2_E_DEVICE_INVALIDATED .

Aplikasi dapat menolak menggunakan titik akhir audio virtual dengan meneruskan bendera XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT ke IXAudio2::CreateMasteringVoice.

Titik akhir audio virtual tidak tersedia di Windows 7 SP1. Bendera XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT tidak berpengaruh pada Windows 7 SP1.

Kategori audio

Aplikasi harus menentukan kategori untuk aliran audionya. Ini dilakukan dengan memberikan nilai dari enumerasi AudioCategory saat memanggil metode IXAudio2::CreateMasteringVoice . Misalnya, AudioCategory_GameEffects. Kategori audio dapat memengaruhi cara Windows memproses suara atau bagaimana ia mewakili aliran audio di panel kontrol volume. Kategori audio juga memengaruhi jika suara surround virtual diaktifkan secara otomatis.

Durasi kuantum pemrosesan audio

Pada sebagian besar PC, XAudio 2.9 memproses audio dalam potongan 10 milidetik. Ini disebut kuantum pemrosesan. Namun, durasi kuantum ini mungkin berbeda dari 10 milidetik pada beberapa perangkat keras. Aplikasi yang perlu mengetahui kuantum yang tepat dapat memanggil metode IXAudio2Extension::GetProcessingQuantum untuk mengambil nilai.

Suara spasial dan keliling virtual

Biasanya, XAudio 2.9 melakukan lipatan ke bawah audio multi-saluran agar sesuai dengan jumlah saluran audio "fisik" yang didukung oleh titik akhir audio. Misalnya, jika game menyediakan sumber audio saluran 7.1, tetapi suara diputar di headphone, XAudio 2.9 akan melipat audio saluran 7.1 ke dalam stereo, menggunakan matriks lipatan standar industri. Jika PC terhubung ke titik akhir audio HDMI, audio saluran 7.1 akan ditransmisikan apa adanya melalui koneksi HDMI.

Windows 10 menambahkan dukungan untuk audio spasial, menggunakan encoder terpusat yang mengodekan audio ke dalam format suara spasial yang dipilih pengguna. Windows 10 disertakan dengan format suara spasial yang disebut Windows Sonic. Format lain, seperti Dolby Atmos for Headphones, dapat diunduh dari Microsoft Store. Beberapa format suara spasial, seperti Windows Sonic dan Dolby Atmos for Headphones, dirancang untuk digunakan pada titik akhir audio stereo. Format ini melipat suara surround ke stereo menggunakan algoritma kepemilikan yang mencapai efek suara surround "virtual". Dengan kata lain, pendengar dapat melihat suara yang muncul dari posisi yang berbeda di ruang 3D bahkan saat hanya mengenakan headphone, atau saat mendengarkan satu pasang speaker stereo.

Efek serupa dapat dicapai menggunakan API X3DAudio yang disertakan dengan XAudio 2.9. Perbedaan utamanya adalah bahwa X3DAudio mengharuskan pengembang aplikasi untuk secara eksplisit memprogram audio 3D, sedangkan suara surround virtual diterapkan secara otomatis ke sumber suara berbasis saluran tradional apa pun.

Pada Windows 10 1903, dan yang lebih baru, game yang menggunakan XAudio 2.9 akan menggunakan format suara spasial di seluruh sistem yang telah diaktifkan pengguna pada titik akhir audio, jika ada. Ini berarti bahwa XAudio 2.9 tidak akan melakukan lipatan suara ke stereo biasa. Sebaliknya, sinyal suara surround akan dikirimkan ke encoder suara spasial (misalnya, Windows Sonic) untuk mencapai efek suara surround virtual.

CreateHrtfApo

Fungsi CreateHrtfApo hanya tersedia di Windows 10. Ini tidak diimplementasikan dalam XAudio 2.9 yang dapat didistribusikan ulang.