Fejlesztői útmutató az XAudio 2.9 terjeszthető verziójához

Az XAudio 2.9 verziója NuGet-csomagként érhető el. A fejlesztők az alkalmazásokkal terjeszthetik újra az XAudio 2.9 ezen verzióját. Ez lehetővé teszi, hogy az alkalmazás xAudio 2.9-et használjon a Windows régebbi verzióin, amelyek nem tartalmazzák az XAudio 2.9-et az operációs rendszer lemezképének részeként. Ennek az újraterjeszthetőnek a használata előnyben részesíthető az XAudio 2.7 DirectX SDK-ból való újraelosztásával szemben, mivel az XAudio 2.7 2010 óta nem frissült.

A DirectX-fejlesztőknek szánt további erőforrásokért látogasson el a DirectX kezdőlapjára.

Támogatott platformok

Az XAudio 2.9 NuGet-csomag (Microsoft.XAudio2.Redist.*.nupkg) tartalmazza az XAudio 2.9 API-t implementáló DLL 32 bites és 64 bites verzióját. A DLL neve XAUDIO2_9REDIST.DLL. Ez a DLL Windows 7 SP1, Windows 8, Windows 8.1 és Windows 10 rendszeren fog működni.

Ha a DLL-t windows 10-es rendszeren használják, ellenőrzi az operációs rendszer részét képező XAUDIO2_9.DLL verziószámát, és ha az operációs rendszer újabb, az operációs rendszer minden API-hívását delegálja az operációs rendszer XAUDIO2_9.DLL. Ez biztosítja, hogy az alkalmazások mindig az aktuális platformon elérhető XAudio 2.9 legújabb verzióját használják.

A DLL nem Xbox One-hoz készült. Ha Xbox One konzolon használják, a DLL mindig minden API-hívást delegál az Xbox One operációs rendszer XAUDIO2_9.DLL fájljának.

A DLL nem UWP-alkalmazásokhoz készült. Az UWP-alkalmazásoknak az operációs rendszer részét képező XAUDIO2_9.DLL kell használniuk.

A NuGet-csomag telepítése

A NuGet-csomag telepítésének legegyszerűbb módja a NuGet Package Manager használata a Microsoft Visual Studióban. Ha ezt teszi, a Visual Studio-projektfájl automatikusan frissül, hogy tartalmazza Microsoft.XAudio2.Redist.targets. A .targets fájl hozzáadja az XAudio2 fejlécfájljait tartalmazó Belefoglalás mappát a projektbefoglalási útvonalak gyűjteményéhez. A .targets fájl hozzáfűzi a .DLL vagy .EXE fájlokat az XAUDIO2REDIST.LIB és XAPOBASEREDIST.LIB fájlokhoz.

A XAPOBASEREDIST.LIB kódtárra csak akkor van szükség, ha egyéni XAudio Processing Object (XAPO) megvalósítását tervezi, és eltávolíthatja azt a Microsoft.XAudio2.Redist.targets fájlból, ha használaton kívüli.

Más eszközökkel is kinyerheti a NuGet-csomag tartalmát, vagy átnevezheti a fájlkiterjesztést .zip, és bármely ZIP-elszívó eszközzel kinyerheti a fájlokat.

A VC++ Csomagkezelőszámára egy xaudio2redist port is elérhető.

Az alkalmazás összeállítása

A belefoglalandó fejlécek kiválasztása

Az XAudio 2.9 NuGet csomag ugyanazokat az XAudio2 fejlécfájlokat tartalmazza, amelyek a Windows 10 SDK-ban találhatók. A fejlécfájlokat azonban módosították, hogy biztosan használhassa őket, miközben kifejezetten megcélozza az összes támogatott platformot, beleértve a Windows régebbi verzióit is.

Ha telepíteni a NuGet-csomagot a Microsoft Visual Studióban a NuGet Csomagkezelővel, akkor a fejlécfájlok elérési útja a Windows SDK fejlécfájljainak elérési útja elé kerül. Ez azt jelenti, hogy ha a projekt kódjában szerepel a XAUDIO2. H fejléc, akkor felveszi a platformfüggetlen fejlécet a NuGet-csomagból. Ez általában a kívánt viselkedés.

Óvatosnak kell lennie, ha a fejlécek elérési útját manuálisan adja hozzá a projekthez. Ha azokat helytelen sorrendben adja meg, előfordulhat, hogy az operációs rendszer verzióspecifikus XAUDIO2.H a Windows SDK-ból lesz bevonva ahelyett, hogy a platformfüggetlen XAUDIO2.H változatot használná.

Annak érdekében, hogy a fejlécek kevésbé hajlamosak legyenek a hibázásra, a NuGet-csomag tartalmazza az egyes fejlécek egy verzióját, amelyhez hozzá van adva a "REDIST". Például a XAUDIO2 mellett. H, a NuGet-csomag XAUDIO2REDIST.H-t is tartalmaz. Ha szeretné, a kód közvetlenül is tartalmazhatja az XAUDIO2REDIST.H fájlt, hogy megszüntesse a fejlécfájllal kapcsolatos bármilyen kétértelműséget. Amikor a fejlécfájl -REDIST.H verzióját tartalmazza, nem számít, hogy a mellékelt fájl könyvtárak milyen sorrendben vannak felsorolva a projektfájlban.

Vegye figyelembe, hogy ha az alkalmazást Xbox One-ra is lefordítják, akkor továbbra is be kell vonni a XAUDIO2.H fájlt az Xbox One-ra történő fordítás során, mivel egyes Xbox One-specifikus API-k ki vannak zárva a XAUDIO2REDIST.H-ból. Ez a NuGet-csomag nem Xbox One-hoz készült.

A DLL betöltése

Javasoljuk, hogy kapcsolja össze az alkalmazását az XAUDIO2REDIST.LIB fájllal, és telepítse az XAUDIO2_9REDIST.DLL fájlt ugyanabban a mappában, ahol az alkalmazás futtatható fájlja található. Ez azt eredményezi, hogy az XAUDIO2_9REDIST.DLL amint a végrehajtható fájl elindul, betöltődik. Tetszés szerint azonban LoadLibraryEx és GetProcAddress is használhatja a XAUDIO2_9REDIST.DLL igény szerinti betöltéséhez. Ez jó megoldás, ha az alkalmazásnak nem mindig kell használnia az XAudio2 API-kat. Ha azonban ezt teszi, a XAUDIO2_9REDIST.DLL-t be kell töltenie, amíg az alkalmazás ki nem lép, mivel a DLL kiürítési kísérlete összeomlást okozhat, ha egy háttérszál még mindig kódot futtat a DLL-ben.

A régebbi XAudio 2.7-sel ellentétben a CoCreateInstance nem használható a DLL betöltéséhez.

A DLL-aláírás ellenőrzése

A XAUDIO2_9REDIST.DLL bináris fájlt a Microsoft sha-2 aláírással írja alá. Minden olyan kódnak, amely megpróbálja ellenőrizni az aláírást, például a játékok csalás elleni moduljait, támogatnia kell az SHA-2-t. Vegye figyelembe, hogy a Windows 7 SP1 eredetileg nem támogatja az SHA-2-t, és frissítést igényel a funkció hozzáadásához. A frissítés KB4474419érhető el.

Vizsgálat

Térbeli hang a Windows 10 újabb verzióiban

A Windows 10 1903 frissítéstől az XAudio 2.9 automatikusan használja a virtuális térhatású hangot, ha bizonyos feltételek teljesülnek. Javasoljuk, hogy tesztelje a játékot, amely többcsatornás hangot hoz létre a Windows 10 1903 -on (vagy újabb) annak ellenőrzéséhez, hogy a játék a várt módon hangzik-e el.

Térbeli hang engedélyezése

A felhasználó úgy engedélyezheti a térbeli hangformátumot, hogy a jobb gombbal a Windows rendszertálcájában lévő hangszóró ikonra kattint.

Az XAudio 2.9 csak akkor használja a felhasználó által kiválasztott térbeli hangformátumot, ha az XAudio2 API-t használó folyamatot a Windows Játéksáv játékként ismeri fel. A fejlesztés során lehetséges, hogy a folyamatot még nem ismeri fel játékként a Játéksáv. Ennek módosításához használja a Win+G billentyűkombinációt a játék közbeni játéksáv megjelenítéséhez. Ezután kattintson a "Beállítások" ikonra, és jelölje be a "Ne feledje, hogy ez egy játék" jelölőnégyzetet.

Kilépés a térbeli hangból

Van egy módja annak, hogy letiltsa, hogy az XAudio2 használja a térbeli hangkódolót az AUDIO_STREAM_CATEGORY paraméter bizonyos értékeinek megadásával IXAudio2::CreateMasteringVoice.

A térbeli hang az alábbi kategóriákban engedélyezve van:

• HangKategória_CsakElőtérMédia
• AudioCategory_Játékeffektek
• Hangkategória_Játékmédia
• Hangkategória_Film
• AudióKategória_Média

A térbeli hang nem engedélyezett, ha a következő kategóriák valamelyike van megadva:

• Hangkategória_Egyéb
• AudioKategória_Kommunikáció
• Hangkategória_Figyelmeztetések
• AudioCategory_Hanghatások
• Hangkategória_Játékcsevegés
• Hangkategória_Beszéd

Hibakezelés

Fontos tesztelni, hogy a játék képes-e kezelni a hangeszköz változásait, például a fejhallgató csatlakoztatásakor vagy kihúzásakor. Ezt olyan fejhallgatóval kell tesztelni, amely csak a 44,1 kHz-es mintavételi sebességet támogatja. Számos alsókategóriás USB-fejhallgató és Bluetooth-fejhallgató csak 44,1 kHz-et támogat. A 48 kHz-es mintavételezési sebesség és a 44,1 kHz-es mintavételezési sebesség közötti átmenet akkor is hibát okozhat, ha a virtuális hangvégpont funkciót használja. A hiba nem fordul elő, ha a fejhallgató is támogatja a 48 kHz-es. Vegye figyelembe, hogy a virtuális hangvégpont szolgáltatás nem érhető el a Windows 7 SP1 rendszeren.

Az XAudio 2.9 által visszaadott hibakód, amikor nem tud automatikusan helyreállni hangvégpont változásakor, XAUDIO2_E_DEVICE_INVALIDATED. Azt javasoljuk azonban, hogy az alkalmazások ne kódozzanak függőséget egy adott értékkel rendelkező hibakódhoz.

A hibáról való értesítéshez az alkalmazásnak implementálnia kell az IXAudio2EngineCallback felületet, és a IXAudio2::RegisterForCallbacks metódus meghívásával mutatót kell megadnia erre a felületre. Az IXAudio2EngineCallback::OnCriticalError implementációját az XAudio2 API hívja meg, amennyiben hiba történik a lejátszás során.

Vegye figyelembe, hogy IXAudio2EngineCallback::OnCriticalError nem feltétlenül hívható meg, ha a hangfolyamat fel van függesztve. Ha például a felhasználó minimalizálja az alkalmazást, vagy az alkalmazás bármilyen okból fel van függesztve, a hanglejátszás szüneteltethető. Ha ez idő alatt a hangeszköz megváltozik, a hiba csak akkor jelenik meg, ha az alkalmazás meghívja IXAudio2::StartEngine és/vagy meghívja IXAudio2SourceVoice::Start. Ha az alkalmazással szüneteltethető a lejátszás, tesztelje a hangeszköz módosítását, amíg a lejátszás szünetel, és ellenőrizze, hogy az alkalmazás továbbra is képes-e helyreállítani ezt a helyzetet.

XAudio 2.9 API-különbségek az XAudio 2.7-hez képest

Ez a szakasz összefoglalja az XAudio 2.7 és az XAudio 2.9 terjeszthető verziója közötti API-különbségeket.

Támogatott formátumok

Az XAudio 2.9 támogatja ezeket a bemeneti formátumokat PC-n:

• Lineáris 16-bites PCM
• Lineáris 32 bites lebegőpontos PCM
• 16 bites ADPCM
• xWMA

Az XMA formátum csak Xbox One konzolon támogatott.

Előnyben részesített processzormag

Megadhatja, hogy az XAudio 2.9 processzormag melyik processzormagot használja hangfeldolgozási szálához. Általában azonban inkább hagyja, hogy az XAudio 2.9 önmagában válassza ki ezt az értéket. Ez az XAudio2Processor paraméter XAudio2Createmeghívásában XAUDIO2_USE_DEFAULT_PROCESSOR.

Az XAudio 2.9 egy másik processzormagot fog választani Xbox One-on, mint PC-n. Az IXAudio2Extension::GetProcessor metódus használható annak meghatározására, hogy melyik processzormagot választotta az XAudio2.

Virtuális hangvégpont

Az XAudio 2.9 alapértelmezés szerint egy virtuális hangvégpontot használ Windows 8 vagy újabb rendszeren való futtatáskor. Ez azt jelenti, hogy ha az alapértelmezett hangvégpont megváltozik az XAudio 2.9 használata közben, automatikusan megpróbál váltani az új hangvégpontra. Példa arra, hogy ez mikor fordulhat elő, ha az alapértelmezett hangvégpont egy USB-n keresztül csatlakoztatott fejhallgatópár, majd a felhasználó leválasztja a fejhallgatót. Ez azt eredményezi, hogy a hangszórók lesznek az új alapértelmezett hangvégpont.

Ha az alkalmazás adott hangformátumot ad meg IXAudio2::CreateMasteringVoicemeghívásakor, előfordulhat, hogy az XAudio 2.9 nem tudja végrehajtani ezt a kapcsolót. Ha például az alkalmazás úgy határozott, hogy a Mastering Voice 48 kHz-es mintavételi sebességet használ, és az új hangeszköz csak 44,1 kHz-et támogat, akkor az automatikus kapcsoló meghibásodik, és az XAudio 2.9 jelenti a XAUDIO2_E_DEVICE_INVALIDATED hibát.

Az alkalmazás kikapcsolhatja a virtuális hangvégpont használatát azáltal, hogy az XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT jelölőt átadja az IXAudio2::CreateMasteringVoicemetódusnak.

A virtuális hangvégpontok nem érhetők el a Windows 7 SP1 rendszeren. A XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT jelző nincs hatással a Windows 7 SP1 rendszerre.

Hangkategóriák

Az alkalmazásnak meg kell adnia egy kategóriát a hangstreamhez. Ez úgy történik, hogy megad egy értéket az AudioCategory enumerálásából, amikor meghívja a IXAudio2::CreateMasteringVoice metódust. Például az AudioCategory_GameEffects kategória. A hangkategória befolyásolhatja, hogy a Windows hogyan dolgozza fel a hangot, vagy hogyan képviseli a hangstreamet a hangerő-vezérlési panelen. A hangkategória azt is befolyásolja, hogy virtuális térhatású hang automatikusan engedélyezve van-e.

A hangfeldolgozás kvantum időtartama

A legtöbb pc-n az XAudio 2.9 10 ezredmásodpercben dolgozza fel a hangokat. Ezt nevezzük feldolgozási kvantumnak. Ennek a kvantumnak az időtartama azonban eltérhet bizonyos hardvereken 10 ezredmásodperctől. A pontos kvantumot ismerő alkalmazások meghívhatják az IXAudio2Extension::GetProcessingQuantum metódust az érték lekéréséhez.

Térbeli hang és virtuális térhatás

A Windows 10 1903 frissítéstől kezdve az XAudio 2.9 automatikusan virtuális térhatású hangot használ, ha bizonyos feltételek teljesülnek. Javasoljuk, hogy tesztelje a játékot, amely többcsatornás hangot hoz létre a Windows 10 1903 -on (vagy újabb) annak ellenőrzéséhez, hogy a játék a várt módon hangzik-e el. A térbeli hang szakaszában találja a funkció tesztelésével kapcsolatos vitát.

Az XAudio 2.9 általában konvertálja a többcsatornás audiót, hogy az megfeleljen a hangvégpont által támogatott "fizikai" csatornák számának. Ha például a játék egy 7,1 csatornás hangforrást biztosít, de a hangot fejhallgatón játsszák le, az XAudio 2.9 a 7.1 csatornás hangot sztereóvá alakítja egy iparági szabvány lehajtható mátrix használatával. Ha a számítógép HDMI hangvégponthoz csatlakozik, akkor a 7.1 csatornás hang as-is lesz továbbítva a HDMI-kapcsolaton keresztül.

A Windows 10 támogatja a térbeli hangot egy központi kódolóval, amely a hangot egy felhasználó által kiválasztott térbeli hang formátumba kódolja. A Windows 10 a Windows Sonic nevű térbeli hangformátumot tartalmazza. Más formátumok, például a Dolby Atmos for Headphones letölthetők a Microsoft Store-ból. Egyes térbeli hangformátumok, például a Windows Sonic és a Dolby Atmos for Headphones, sztereó hangvégpontokon való használatra lettek kialakítva. Ezek a formátumok lehajtják a térhatású hangot sztereóra, olyan szabadalmaztatott algoritmusokkal, amelyek "virtuális" térhatású hangeffektust érnek el. Más szóval a figyelő a térbeli tér különböző pozícióiból megjelenő hangot akkor is érzékeli, ha csak fejhallgatót visel, vagy egyetlen sztereó hangszórót hallgat.

Hasonló hatás érhető el az XAudio 2.9 X3DAudio API-kkal. A fő különbség az, hogy az X3DAudio megköveteli, hogy az alkalmazás fejlesztője explicit módon programozza a 3D-hangokat, míg a virtuális térhatású hang automatikusan alkalmazva lesz bármilyen tradional channel-alapú hangforrásra.

Windows 10 1903 és újabb rendszereken az XAudio 2.9-et használó játékok a felhasználó által a hangvégponton engedélyezett térbeli hangformátumot használják, ha a felhasználó engedélyezte azt. Ez azt jelenti, hogy az XAudio 2.9 nem fogja elvégezni a szokásos térhangzás lekeverését sztereóra. Ehelyett a térhatású hangjelzés a térbeli hangkódolóhoz (pl. Windows Sonic) lesz kézbesítve a virtuális térhatású hangeffektus elérése érdekében.

CreateHrtfApo

A CreateHrtfApo függvény csak Windows 10 rendszeren érhető el. Nem implementálható az XAudio 2.9 terjeszthető verziójában.