XAudio 2.9'un yeniden dağıtılabilir sürümü için geliştirici kılavuzu

XAudio 2.9 sürümü, NuGet paketiolarak kullanılabilir. Geliştiriciler, XAudio 2.9'un bu sürümünü uygulamalarıyla yeniden dağıtabilir. Bu, bir uygulamanın işletim sistemi görüntüsünün bir parçası olarak XAudio 2.9 içermeyen eski Windows sürümlerinde XAudio 2.9 kullanmasına olanak tanır. XAudio 2.7 2010'dan beri güncelleştirilmediğinden, bu yeniden dağıtılabilir özelliğin kullanılması DirectX SDK'dan XAudio 2.7'nin yeniden dağıtılması yerine tercih edilir.

DirectX geliştiricileri için daha fazla kaynak için DirectX Giriş Sayfası ziyaret ettiğinizden emin olun.

Desteklenen platformlar

XAudio 2.9 NuGet paketi (Microsoft.XAudio2.Redist.*.nupkg), XAudio 2.9 API'sini uygulayan bir DLL'nin 32 bit ve 64 bit sürümünü içerir. DLL XAUDIO2_9REDIST.DLL olarak adlandırılır. Bu DLL, Windows 7 SP1, Windows 8, Windows 8.1 ve Windows 10'da çalışır.

DLL, Windows 10 sisteminde kullanıldığında, işletim sisteminin parçası olan XAUDIO2_9.DLL'in sürüm numarasını kontrol eder ve eğer işletim sistemi daha yeniyse, tüm API çağrılarını işletim sistemindeki XAUDIO2_9.DLL'e yönlendirir. Bu, uygulamaların her zaman geçerli platformda bulunan en son XAudio 2.9 sürümünü kullanmasını sağlar.

DLL, Xbox One için tasarlanmamıştır. Xbox One'da kullanıldığında, DLL her zaman tüm API çağrılarını Xbox One işletim sistemindeki XAUDIO2_9.DLL'e devreder.

DLL, UWP uygulamaları için tasarlanmamıştır. UWP uygulamaları işletim sisteminin parçası olan XAUDIO2_9.DLL kullanmalıdır.

NuGet paketini yükleme

NuGet paketini yüklemenin en kolay yolu, Microsoft Visual Studio'da nuget paket yöneticisi kullanmaktır. Bunu yaparsanız, Visual Studio proje dosyanız Microsoft.XAudio2.Redist.targetsiçerecek şekilde otomatik olarak güncelleştirilir. .targets dosyası, XAudio2 için başlık dosyalarını içeren Include klasörünü proje ekleme yolu koleksiyonunuza ekler. .targets dosyası, .DLL veya .EXE'nizi XAUDIO2REDIST.LIB ve XAPOBASEREDIST.LIB ile bağlantılı hale getirecektir.

XAPOBASEREDIST.LIB kitaplığı, yalnızca özel bir XAudio İşleme Nesnesi (XAPO) uygulamak istiyorsanız gereklidir ve kullanılmıyorsa Microsoft.XAudio2.Redist.targets'tan kaldırabilirsiniz.

NuGet paketinin içeriğini ayıklamak için başka araçlar da kullanabilir, hatta dosya uzantısını .zip olarak yeniden adlandırabilir ve herhangi bir ZIP ayıklayıcı aracıyla dosyaları ayıklayabilirsiniz.

VC++ Paket Yöneticisiiçin bir xaudio2redist bağlantı noktası da vardır.

Uygulamanızı derleme

Eklenecek üst bilgileri seçme

XAudio 2.9 NuGet paketi, Windows 10 SDK'sında bulunan aynı XAudio2 üst bilgi dosyalarını içerir. Ancak, Windows'un eski sürümleri de dahil olmak üzere tüm destekliplatformlarını açıkça hedef alarak üst bilgi dosyalarını kullanabilmenizi sağlamak için bazı ayarlamalar yapıldı.

NuGet paketi Microsoft Visual Studio'da NuGet Paket Yöneticisi'ni kullanarak yüklerseniz, üst bilgi dosyalarının yolu Windows SDK üst bilgi dosyalarının yolunun önüne yerleştirilir. Bu durumda, projenizdeki kod XAUDIO2.H üst bilgisi içeriyorsa, platformlar arası üst bilgiyi NuGet paketinden alır. Bu normalde istenen davranıştır.

Ekleme başlıklarının yolunu projeye elle eklerken dikkatli olmalısınız çünkü bunları yanlış sırada belirtmek, XAUDIO2.H'nin platformlar arası sürümü yerine Windows SDK'sından dahil edilmesine neden olabilir.

Üst bilgilerin eklenmesini daha az hataya açık hale getirmek için NuGet paketi, sonuna "REDIST" eklenmiş her üst bilginin bir sürümünü içerir. Örneğin, XAUDIO2.H ile birlikte, NuGet paketi ayrıca XAUDIO2REDIST.H dosyasını da içerir. İsterseniz kodunuz, hangi başlık dosyasının kullanıldığında dair belirsizliği ortadan kaldırmak için doğrudan XAUDIO2REDIST.H dosyasını içerebilir. -REDIST.H başlıklı dosyasının bir sürümünü eklerken, ekleme dosyası dizinlerinin proje dosyasında listelenme sırası önemli değildir.

Uygulamanızın Xbox One için de derlendiğini unutmayın; Xbox One için derleme yaparken XAUDIO2.H'yi dahil etmeye devam etmelisiniz, çünkü Xbox One'a özgü bazı API'ler XAUDIO2REDIST.H'nin dışında tutulmuştur. Bu NuGet paketi Xbox One için tasarlanmamıştır.

DLL'yi yükleme

Uygulamanızı XAUDIO2REDIST.LIB ile bağlamanızı ve XAUDIO2_9REDIST.DLL dosyasını uygulamanızın yürütülebilir dosyasıyla aynı klasöre yüklemenizi öneririz. Yürütülebilir dosyanız başlatıldığında XAUDIO2_9REDIST.DLL'nin yüklenmesine neden olur. Ancak isterseniz LoadLibraryEx ve GetProcAddress kullanarak isteğe bağlı olarak XAUDIO2_9REDIST.DLL yükleyebilirsiniz. Uygulamanızın her zaman XAudio2 API'lerini kullanması gerekmiyorsa bu iyi bir çözümdür. Ancak bunu yaparsanız, uygulamadan çıkana kadar XAUDIO2_9REDIST.DLL yüklü tutmanız gerekir çünkü DLL'yi kaldırmaya çalışmak, bir arka plan iş parçacığı DLL'de kod yürütmeye devam ediyorsa kilitlenmeye neden olabilir.

Eski XAudio 2.7'nin aksine, DLL'yi yüklemek için CoCreateInstance kullanmak mümkün değildir.

DLL imzasını doğrulama

XAUDIO2_9REDIST.DLL ikili dosyası Microsoft tarafından SHA-2 imzası kullanılarak imzalanır. İmzayı doğrulamaya çalışan tüm kodlar, örneğin oyunlar için hile önleme modülleri, bu nedenle SHA-2'yi desteklemelidir. Windows 7 SP1'in başlangıçta SHA-2'yi desteklemediğini ve bu işlevselliği eklemek için bir güncelleştirme gerektirdiğini unutmayın. Güncelleştirme KB4474419olarak kullanılabilir.

Test etme

Windows 10'un daha yeni sürümlerinde uzamsal ses

Windows 10 1903 güncelleştirmesiyle başlayan XAudio 2.9, belirli koşullar karşılanırsa otomatik olarak sanal surround seskullanır. Oyunun beklendiği gibi göründüğünü doğrulamak için Windows 10 1903'te (veya daha yeni bir sürümde) çok kanallı ses oluşturan oyunu test etmenizi öneririz.

Uzamsal sesi etkinleştirme

Kullanıcı, Windows sistem tepsisindeki hoparlör simgesine sağ tıklayarak uzamsal ses biçimini etkinleştirebilir.

XAudio 2.9 yalnızca XAudio2 API'sini kullanan işlem Windows Game Bar tarafından bir oyun olarak kabul edilirse kullanıcının seçtiği uzamsal ses biçimini kullanır. Geliştirme sırasında, sürecin henüz Game Bar tarafından bir oyun olarak tanınmamış olması mümkündür. Bunu değiştirmek için Win+G klavye kısayolunu kullanarak oyun çalışırken Oyun Çubuğu'nu açın. Ardından "Ayarlar" simgesine tıklayın ve "Bunun bir oyun olduğunu unutmayın" onay kutusunu işaretleyin.

Uzamsal sesten vazgeçme

IXAudio2::CreateMasteringVoiceiçinde AUDIO_STREAM_CATEGORY parametresi için belirli değerleri belirterek XAudio2'nin uzamsal ses kodlayıcısını kullanmasını geri çevirmenin bir yolu vardır.

Uzamsal ses şu kategoriler için etkinleştirilir:

• SesKategori_SadeceÖnPlandaMedya
• SesKategori_OyunEfektleri
• SesKategori_OyunMedya
• SesKategori_Film
• AudioKategori_Medya

Aşağıdaki kategorilerden herhangi biri belirtilirse uzamsal ses etkinleştirilmez:

• SesKategorisi_Diğer
• SesKategori_İletişim
• SesKategori_Uyarmalar
• AudioCategory_SesEfektleri
• Ses Kategorisi_Oyun Sohbeti
• Ses_Kategorisi_Konuşma

Hata işleme

Ses cihazında, örneğin kulaklık takılıyken veya fişsizken bir değişikliğin üstesinden gelebildiğinizi test etmek önemlidir. Bu, yalnızca 44,1 kHz örnekleme hızını destekleyen kulaklıklarla test edilmelidir. Birçok alt uç USB kulaklık ve Bluetooth kulaklık yalnızca 44,1 kHz'i destekler. 48 kHz örnekleme hızı ile 44,1 kHz örnekleme hızı arasındaki geçiş, sanal ses uç noktası özelliği kullanıldığında bile hataya neden olabilir. Kulaklıklar 48 kHz'i de destekliyorsa hata oluşmaz. Sanal ses uç noktası özelliğinin Windows 7 SP1'de kullanılamadığını unutmayın.

XAudio 2.9, ses uç noktasındaki bir değişiklikten otomatik olarak kurtulamadığında döndürülen hata kodu XAUDIO2_E_DEVICE_INVALIDATED. Ancak, uygulamaların hata kodunun belirli bir değere sahip olmasına bağlı sabit bir kod kullanmamasını öneriyoruz.

Hatanın bildirilmesi için uygulama IXAudio2EngineCallbackarabiriminiuygulamalı ve IXAudio2::RegisterForCallbacks yöntemini çağırarak bu arabirime bir işaretçi sağlamalıdır. Uygulamanın IXAudio2EngineCallback::OnCriticalError uygulaması, oynatma sırasında bir hata oluşması durumunda XAudio2 API'si tarafından çağrılacaktır.

Lütfen dikkat edin, ses işlem hattı duraklatıldığında IXAudio2EngineCallback::OnCriticalError'in mutlaka çağrılması gerekmez. Örneğin, kullanıcı uygulamayı simge durumuna küçültürse veya uygulama herhangi bir nedenle askıya alınırsa ses çalma duraklatılabilir. Ses cihazında değişiklik bu süre boyunca gerçekleşirse, hata yalnızca uygulama IXAudio2::StartEngineçağırdığında ve/veya IXAudio2SourceVoice::Startçağırdığında döndürülür. Uygulamanızda oynatma duraklatılabiliyorsa, uygulamanın durumdan çıkabildiğini doğrulamak için oynatma duraklatılırken ses cihazını değiştirmeyi test etmelisiniz.

XAudio 2.7 ile karşılaştırıldığında XAudio 2.9 API farklılıkları

Bu bölüm, XAudio 2.7 ile XAudio 2.9'un yeniden dağıtılabilir sürümü arasındaki API farklarının bir özetini sağlar.

Desteklenen biçimler

XAudio 2.9, bilgisayarda şu giriş biçimlerini destekler:

• Doğrusal 16 bit PCM
• Doğrusal 32 bit Float PCM
• 16-bit ADPCM
• xWMA

XMA biçimi yalnızca Xbox One'da desteklenir.

Tercih edilen CPU çekirdeği

Ses işleme iş parçacığı için hangi CPU çekirdeği XAudio 2.9'un kullanılması gerektiğini belirtmek mümkündür. Ancak, genellikle XAudio 2.9'un bu değeri kendi başına seçmesine izin vermek tercih edilir. Bu, XAudio2XAudio2İşlemci parametresini XAUDIO2_USE_DEFAULT_PROCESSORoluşturmaolarak ayarlanarak yapılır.

XAudio 2.9, Xbox One'da bilgisayardakinden farklı bir CPU çekirdeği seçer. IXAudio2Extension::GetProcessor yöntemi, hangi CPU çekirdeği XAudio2'nin seçtiğini belirlemek için kullanılabilir.

Sanal ses uç noktası

XAudio 2.9, Windows 8 veya sonraki sürümlerde çalışırken varsayılan olarak bir sanal ses uç noktası kullanır. Bu, XAudio 2.9 kullanılırken varsayılan ses uç noktası değişirse otomatik olarak yeni ses uç noktasına geçiş yapmaya çalışacağı anlamına gelir. Varsayılan ses uç noktası USB üzerinden bağlanan bir çift kulaklık olduğunda ve ardından kullanıcı kulaklığı çıkardığında bunun ne zaman gerçekleşebileceğini gösteren bir örnek. Bu, hoparlörlerin yeni varsayılan ses uç noktası olmasını sağlar.

Uygulama, IXAudio2::CreateMasteringVoiceçağrılırken belirli bir ses formatı belirtiyorsa, XAudio 2.9'un bu format değişikliğini gerçekleştirmesi mümkün olmayabilir. Örneğin, uygulama Mastering Voice'un 48 kHz örnekleme hızı kullanacağını belirttiyse ve yeni ses cihazı yalnızca 44,1 kHz'yi destekliyorsa otomatik anahtar başarısız olur ve XAudio 2.9 XAUDIO2_E_DEVICE_INVALIDATED hatasını bildirir.

IXAudio2::CreateMasteringVoiceXAUDIO2_NO_VIRTUAL_AUDIO_CLIENT bayrağını geçirerek uygulamanın sanal ses uç noktasını kullanmaktan vazgeçmesi mümkündür.

Sanal ses uç noktaları Windows 7 SP1'de kullanılamaz. XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT bayrağının Windows 7 SP1 üzerinde hiçbir etkisi yoktur.

Ses kategorileri

Uygulama, ses akışı için bir kategori belirtmelidir. Bu, IXAudio2::CreateMasteringVoice yöntemi çağrılırken AudioCategory numaralandırmasından bir değer sağlayarak yapılır. Örneğin, AudioCategory_GameEffects (Ses Kategorisi_Oyun Efektleri). Ses kategorisi, Windows'un sesi nasıl işlediğini veya ses akışını ses denetim masasında nasıl temsil ettiği etkileyebilir. Ses kategorisi, sanal surround ses otomatik olarak etkinleştirilip etkinleştirilmediğini de etkiler.

Kuantum ses işleme süresi

Çoğu bilgisayarda XAudio 2.9, sesi 10 milisaniyelik parçalar halinde işler. Buna işleme kuantumu denir. Ancak bu kuantumun süresi bazı donanımlarda 10 milisaniyeden farklı olabilir. Tam kuantumu bilmesi gereken uygulamalar, değeri almak için IXAudio2Extension::GetProcessingQuantum yöntemini çağırabilir.

Uzamsal ses ve sanal çevre

Windows 10 1903 güncelleştirmesiyle başlayan XAudio 2.9, belirli koşullar karşılanırsa otomatik olarak sanal surround ses kullanır. Oyunun beklendiği gibi göründüğünü doğrulamak için Windows 10 1903'te (veya daha yeni bir sürümde) çok kanallı ses oluşturan oyunu test etmenizi öneririz. Uzamsal ses test bölümüne, bu özelliği nasıl test edeceğiniz hakkında bir tartışma için bakın.

Normalde XAudio 2.9, ses uç noktası tarafından desteklenen "fiziksel" ses kanalı sayısıyla eşleşecek şekilde çok kanallı seslerde katlama gerçekleştirir. Örneğin, oyun bir 7.1 kanal ses kaynağı sağlıyorsa, ancak ses kulaklıkta çalınıyorsa, XAudio 2.9 endüstri standardı bir katlama yöntemi kullanarak 7.1 kanal sesini stereoya indirger. Bilgisayar bir HDMI ses uç noktasına bağlıysa, 7.1 kanal sesi HDMI bağlantısı üzerinden as-is iletilir.

Windows 10, sesi kullanıcı tarafından seçilen uzamsal ses biçimine kodlayan merkezi bir kodlayıcı kullanarak uzamsal ses desteği ekler. Windows 10, Windows Sonic adlı uzamsal ses biçimiyle birlikte gelir. Dolby Atmos for Headphones gibi diğer biçimler Microsoft Store'dan indirilebilir. Windows Sonic ve Dolby Atmos for Headphones gibi uzamsal ses biçimlerinden bazıları stereo ses uç noktalarında kullanılmak üzere tasarlanmıştır. Bu biçimler, "sanal" surround ses efekti elde eden özel algoritmalar kullanarak surround sesi stereoya dönüştürür. Başka bir deyişle, dinleyici yalnızca kulaklık takarken veya tek bir stereo hoparlör çiftinde dinlerken bile sesin 3B alanda farklı konumlardan göründüğünü algılayabilir.

Benzer etkiler, XAudio 2.9 ile birlikte gelen X3DAudio API'leri kullanılarak elde edilebilir. Temel fark, X3DAudio'da uygulama geliştiricisinin 3B ses için açıkça program oluşturmasını gerektirmesi, sanal surround sesin ise tradional kanal tabanlı herhangi bir ses kaynağına otomatik olarak uygulanmasıdır.

Windows 10 1903 ve daha yeni sürümlerde XAudio 2.9 kullanan oyunlar, varsa kullanıcının ses uç noktasında etkinleştirdiği sistem genelinde uzamsal ses biçimini kullanır. Bu, XAudio 2.9'un surround sesi stereoya indirgeme işlemini gerçekleştirmeyeceği anlamına gelir. Bunun yerine surround ses sinyali, sanal surround ses efekti elde etmek için uzamsal ses kodlayıcıya (örneğin, Windows Sonic) teslim edilecek.

CreateHrtfApo

CreateHrtfApo işlevi yalnızca Windows 10'da kullanılabilir. XAudio 2.9 yeniden dağıtılabilir sürümde uygulanmaz.