Guida per sviluppatori per la versione ridistribuibile di XAudio 2.9

Una versione di XAudio 2.9 è disponibile come pacchetto NuGet. Gli sviluppatori possono ridistribuire questa versione di XAudio 2.9 con le app. Ciò consente a un'app di usare XAudio 2.9 nelle versioni precedenti di Windows che non includono XAudio 2.9 come parte dell'immagine del sistema operativo. L'uso di questo ridistribuibile è preferibile per ridistribuire XAudio 2.7 da DirectX SDK, poiché XAudio 2.7 non è stato aggiornato dal 2010.

Assicurarsi di visitare la pagina di destinazione DirectX per altre risorse per gli sviluppatori DirectX.

Piattaforme supportate

Il pacchetto NuGet XAudio 2.9 (Microsoft.XAudio2.Redist.*.nupkg) include una versione a 32 bit e una versione a 64 bit di una DLL che implementa l'API XAudio 2.9. La DLL viene chiamata XAUDIO2_9REDIST.DLL. Questa DLL funzionerà in Windows 7 SP1, Windows 8, Windows 8.1 e Windows 10.

Quando la DLL viene usata in un sistema Windows 10, controlla il numero di versione del XAUDIO2_9.DLL che fa parte del sistema operativo e, se il sistema operativo è più recente, delega tutte le chiamate API a XAUDIO2_9.DLL nel sistema operativo. In questo modo, le app usano sempre la versione più recente di XAudio 2.9 disponibile nella piattaforma corrente.

La DLL non è destinata a Xbox One. Se usato in Xbox One, la DLL delega sempre tutte le chiamate API a XAUDIO2_9.DLL nel sistema operativo Xbox One.

La DLL non è destinata alle app UWP. Le app UWP devono usare il XAUDIO2_9.DLL che fa parte del sistema operativo.

Installazione del pacchetto NuGet

Il modo più semplice per installare il pacchetto NuGet consiste nell'usare Gestione pacchetti NuGet in Microsoft Visual Studio. In questo caso, il file di progetto di Visual Studio verrà aggiornato automaticamente per includere Microsoft.XAudio2.Redist.targets. Il file con estensione targets aggiunge la cartella Include con i file di intestazione per xAudio2 alla raccolta di percorsi di inclusione del progetto. Il file con estensione targets eseguirà anche il collegamento .DLL o .EXE con XAUDIO2REDIST. LIB e XAPOBASEREDIST. LIB.

Libreria XAPOBASEREDIST. LIB è necessario solo se si intende impementare un oggetto XAudio Processing Object (XAPO) personalizzato e è possibile rimuoverlo da Microsoft.XAudio2.Redist.targets se è inutilizzato.

È anche possibile usare altri strumenti per estrarre il contenuto del pacchetto NuGet o anche rinominare l'estensione del file in .zip ed estrarre i file con qualsiasi strumento di estrazione ZIP.

È disponibile anche una xaudio2redist porta per VC++ Package Manager.

Compilazione dell'app

Scelta delle intestazioni da includere

Il pacchetto NuGet XAudio 2.9 include gli stessi file di intestazione XAudio2 inclusi nell'SDK di Windows 10. Tuttavia, i file di intestazione hanno avuto alcune modifiche per assicurarsi che sia possibile usarli in modo esplicito per tutte le piattaforme supportate, incluse le versioni precedenti di Windows.

Se si installa il pacchetto NuGet usando Gestione pacchetti NuGet in Microsoft Visual Studio, il percorso dei file di intestazione viene posizionato davanti al percorso dei file di intestazione di Windows SDK. Ciò significa che se il codice nel progetto include XAUDIO2. Intestazione H, verrà selezionata l'intestazione multipiattaforma dal pacchetto NuGet. Questo è normalmente il comportamento desiderato.

È consigliabile prestare attenzione se si aggiunge il percorso alle intestazioni di inclusione manualmente al progetto, come specificarli nell'ordine errato può causare la versione del sistema operativo specifica XAUDIO2. H da includere in Windows SDK anziché dalla versione multipiattaforma di XAUDIO2.H.

Per rendere l'inclusione di intestazioni meno soggette a errori, il pacchetto NuGet contiene una versione di ogni intestazione con "REDIST" aggiunta. Ad esempio, oltre a XAUDIO2. H, il pacchetto NuGet include anche XAUDIO2REDIST.H. Se si preferisce, il codice può includere direttamente XAUDIO2REDIST. H per eliminare qualsiasi ambiguità su quale file di intestazione viene usato. Quando si include -REDIST. La versione H di un file di intestazione, l'ordine in cui le directory di file di inclusione sono elencate nel file di progetto non importa.

Si noti che se l'app viene compilata anche per Xbox One, è consigliabile continuare a includere XAUDIO2. H durante la compilazione per Xbox One, poiché alcune API specifiche di Xbox One sono escluse da XAUDIO2REDIST.H. Questo pacchetto NuGet non è destinato a Xbox One.

Caricamento della DLL

È consigliabile collegare l'app con XAUDIO2REDIST. LIB e installare XAUDIO2_9REDIST.DLL nella stessa cartella dell'eseguibile dell'app. Ciò causerà il caricamento XAUDIO2_9REDIST.DLL non appena viene avviato l'eseguibile. Tuttavia, se si preferisce, è possibile usare LoadLibraryEx e GetProcAddress per caricare XAUDIO2_9REDIST.DLL su richiesta. Questa è una soluzione ottimale se l'app non deve sempre usare le API XAudio2. Tuttavia, se si esegue questa operazione, è necessario mantenere il XAUDIO2_9REDIST.DLL caricato fino all'uscita dell'app, in quanto il tentativo di scaricare la DLL può causare un arresto anomalo se un thread in background è ancora in esecuzione codice nella DLL.

A differenza del precedente XAudio 2.7, non è possibile usare CoCreateInstance per caricare la DLL.

Verifica della firma DLL

Il XAUDIO2_9REDIST.DLL binario viene firmato da Microsoft usando una firma SHA-2. Qualsiasi codice che tenta di convalidare la firma, ad esempio i moduli anti-truffa per i giochi, deve quindi supportare SHA-2. Si noti che Windows 7 SP1 non supporta originariamente SHA-2 e richiede un aggiornamento per aggiungere tale funzionalità. L'aggiornamento è disponibile come KB4474419.

Test

Suono spaziale nelle versioni più recenti di Windows 10

A partire dall'aggiornamento Windows 10 1903, XAudio 2.9 usa automaticamente il suono surround virtuale, se alcune condizioni sono soddisfatte. È consigliabile testare il gioco che genera audio multicanale su Windows 10 1903 (o versione successiva) per verificare che il gioco suoni come previsto.

Abilitazione del suono spaziale

L'utente può abilitare un formato audio spaziale facendo clic con il pulsante destro del mouse sull'icona dell'altoparlante nella barra di sistema di Windows.

XAudio 2.9 userà solo il formato audio spaziale selezionato dell'utente se il processo che usa l'API XAudio2 viene riconosciuto come gioco dalla barra dei giochi di Windows. Durante lo sviluppo, è possibile che il processo non sia ancora riconosciuto come gioco dal Game Bar. Per modificare questa operazione, usare la tastiera Win+G a taglio corto per visualizzare il Game Bar mentre il gioco è in esecuzione. Fare quindi clic sull'icona "Impostazioni" e selezionare la casella di controllo che indica "Ricorda che si tratta di un gioco".

Opting out from spatial sound

È possibile rifiutare esplicitamente l'uso del codificatore audio spaziale XAudio2 specificando determinati valori per il parametro AUDIO_STREAM_CATEGORY in IXAudio2::CreateMasteringVoice.

Il suono spaziale è abilitato per queste categorie:

• AudioCategory_ForegroundOnlyMedia
• AudioCategory_GameEffects
• AudioCategory_GameMedia
• AudioCategory_Movie
• AudioCategory_Media

Il suono spaziale non è abilitato se sono specificate alcune delle categorie seguenti:

• AudioCategory_Other
• AudioCategory_Communications
• AudioCategory_Alerts
• AudioCategory_SoundEffects
• AudioCategory_GameChat
• AudioCategory_Speech

Gestione degli errori

È importante testare che il gioco può gestire una modifica nel dispositivo audio, ad esempio quando le cuffie sono collegate o scollegate. Questa operazione deve essere testata con cuffie che supportano solo la frequenza di campionamento a 44,1 kHz. Molte cuffie USB di basso livello e visori Bluetooth supportano solo 44,1 kHz. La transizione tra la frequenza di campionamento di 48 kHz e la frequenza di campionamento a 44,1 kHz può causare un errore anche quando viene usata la funzionalità dell'endpoint audio virtuale . L'errore non si verifica se le cuffie supportano anche 48 kHz. Si noti che la funzionalità dell'endpoint audio virtuale non è disponibile in Windows 7 SP1.

Il codice di errore restituito da XAudio 2.9 quando non riesce a ripristinare automaticamente da una modifica dell'endpoint audio è XAUDIO2_E_DEVICE_INVALIDATED. È tuttavia consigliabile che le app non eseseguono un codice rigido una dipendenza dal codice di errore con un valore specifico.

Per ricevere una notifica dell'errore, l'app deve implementare l'interfaccia IXAudio2EngineCallback e fornire un puntatore a tale interfaccia richiamando il metodo IXAudio2::RegisterForCallbacks . L'implementazione dell'app di IXAudio2EngineCallback::OnCriticalError verrà richiamata dall'API XAudio2 se si verifica un errore durante la riproduzione.

Si noti che IXAudio2EngineCallback::OnCriticalError non viene necessariamente richiamato se la pipeline audio viene sospesa. Ad esempio, se l'utente riduce al minimo l'app o l'app viene sospesa per qualsiasi motivo, la riproduzione audio potrebbe essere sospesa. Se la modifica nel dispositivo audio si verifica durante questa volta, l'errore viene restituito solo quando l'app richiama IXAudio2::StartEngine e/o richiama IXAudio2SourceVoice::Start. Se la riproduzione può essere sospesa con l'app, è necessario testare la modifica del dispositivo audio mentre la riproduzione viene sospesa, per verificare che l'app possa comunque recuperare da questa situazione.

Differenze api XAudio 2.9 rispetto a XAudio 2.7

Questa sezione fornisce un riepilogo delle differenze api tra XAudio 2.7 e la versione ridistribuibile di XAudio 2.9.

Formati supportati

XAudio 2.9 supporta questi formati di input nel PC:

• PCM a 16 bit lineare
• PCM float a 32 bit lineare
• ADPCM a 16 bit
• xWMA

Il formato XMA è supportato solo in Xbox One.

Core CPU preferito

È possibile specificare quale cpu core XAudio 2.9 deve usare per il thread di elaborazione audio. Tuttavia, in genere è preferibile consentire a XAudio 2.9 di scegliere questo valore da solo. Questa operazione viene eseguita impostando il parametro XAudio2Processor nella chiamata a XAudio2Create su XAUDIO2_USE_DEFAULT_PROCESSOR.

XAudio 2.9 sceglierà un core CPU diverso su Xbox One rispetto al PC. Il metodo IXAudio2Extension::GetProcessor può essere usato per determinare quale cpu core XAudio2 ha scelto.

Endpoint audio virtuale

XAudio 2.9 userà un endpoint audio virtuale per impostazione predefinita, quando in esecuzione in Windows 8 o versioni successive. Ciò significa che se l'endpoint audio predefinito cambia mentre viene usato XAudio 2.9, tenterà di passare automaticamente al nuovo endpoint audio. Un esempio di quando questo può verificarsi quando l'endpoint audio predefinito è una coppia di cuffie connesse tramite USB e quindi l'utente scollega le cuffie. In questo modo gli altoparlanti saranno il nuovo endpoint audio predefinito.

Se l'app specifica un formato audio specifico quando si richiama IXAudio2::CreateMasteringVoice, potrebbe non essere possibile eseguire questo commutatore XAudio 2.9. Ad esempio, se l'app ha specificato che Mastering Voice userà una frequenza di campionamento a 48 kHz e il nuovo dispositivo audio supporta solo 44,1 kHz, il commutatore automatico avrà esito negativo e XAudio 2.9 segnala l'errore di XAUDIO2_E_DEVICE_INVALIDATED .

È possibile che l'app non usi l'endpoint audio virtuale passando il flag XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT a IXAudio2::CreateMasteringVoice.

Gli endpoint audio virtuali non sono disponibili in Windows 7 SP1. Il flag di XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT non ha effetto su Windows 7 SP1.

Categorie audio

L'app deve specificare una categoria per il flusso audio. Questa operazione viene eseguita fornendo un valore dall'enumerazione AudioCategory quando si richiama il metodo IXAudio2::CreateMasteringVoice . Ad esempio, AudioCategory_GameEffects. La categoria audio può influire sul modo in cui Windows elabora il suono o su come rappresenta il flusso audio nel pannello di controllo del volume. La categoria audio influisce anche se il suono surround virtuale è abilitato automaticamente.

Durata dell'elaborazione audio quantistica

Nella maggior parte dei PC, XAudio 2.9 elabora l'audio in 10 blocchi di millisecondi. Viene chiamato quantistico di elaborazione. Tuttavia, la durata di questo quantistico può essere diversa da 10 millisecondi in alcuni hardware. Le app che devono conoscere il quantum esatto possono richiamare il metodo IXAudio2Extension::GetProcessingQuantum per recuperare il valore.

Suono spaziale e circondato virtuale

A partire dall'aggiornamento Windows 10 1903, XAudio 2.9 usa automaticamente il suono surround virtuale, se sono soddisfatte determinate condizioni. È consigliabile testare il gioco che genera audio multicanale su Windows 10 1903 (o versione successiva) per verificare che il gioco suoni come previsto. Per informazioni su come testare questa funzionalità, vedere la sezione test del suono spaziale .

In genere, XAudio 2.9 esegue una piega verso il basso qualsiasi audio multicanale per corrispondere al numero di canali audio "fisici" supportati dall'endpoint audio. Ad esempio, se il gioco fornisce un'origine audio da 7.1 canali, ma il suono viene riprodotto sulle cuffie, XAudio 2.9 piega l'audio del canale 7.1 nello stereo, usando una matrice di piegatura standard del settore. Se il PC è connesso a un endpoint audio HDMI, l'audio del canale 7.1 verrà trasmesso come si trova sulla connessione HDMI.

Windows 10 aggiunge il supporto per l'audio spaziale usando un codificatore centralizzato che codifica l'audio in un formato audio spaziale selezionato dall'utente. Windows 10 include un formato audio spaziale denominato Windows Sonic. Altri formati, ad esempio Dolby Atmos for Headphones, possono essere scaricati da Microsoft Store. Alcuni dei formati audio spaziali, ad esempio Windows Sonic e Dolby Atmos for Headphones, sono progettati per essere usati negli endpoint audio stereo. Questi formati si piegano verso il basso il suono circondato da stereo usando algoritmi proprietari che ottengono un effetto suono "virtuale". In altre parole, il listener può percepire il suono da posizioni diverse nello spazio 3D anche mentre indossa solo cuffie o mentre si ascolta su una singola coppia di altoparlanti stereo.

Gli effetti simili possono essere ottenuti usando le API X3DAudio incluse in XAudio 2.9. La differenza principale è che X3DAudio richiede allo sviluppatore di app di programmare in modo esplicito l'audio 3D, mentre il suono surround virtuale viene applicato automaticamente a qualsiasi origine audio basata su canale tradzionale.

In Windows 10 1903 e versioni successive, i giochi che usano XAudio 2.9 useranno il formato audio spaziale a livello di sistema abilitato dall'utente nell'endpoint audio, se presente. Ciò significa che XAudio 2.9 non eseguirà il solito piegamento del suono circondato allo stereo. Al contrario, il segnale audio circondato verrà recapitato al codificatore audio spaziale (ad esempio, Windows Sonic) per ottenere un effetto audio circondato virtuale.

CreateHrtfApo

La funzione CreateHrtfApo è disponibile solo in Windows 10. Non viene implementato nella ridistribuibile XAudio 2.9.