Guia do desenvolvedor para a versão redistribuível do XAudio 2.9

Artigo
06/13/2023

Uma versão do XAudio 2.9 está disponível como um pacote NuGet. Os desenvolvedores podem redistribuir essa versão do XAudio 2.9 com seus aplicativos. Isso permite que um aplicativo use o XAudio 2.9 em versões mais antigas do Windows que não incluem o XAudio 2.9 como parte da imagem do sistema operacional. O uso desse redistribuível é preferencial em vez de redistribuir o XAudio 2.7 do SDK do DirectX, pois o XAudio 2.7 não foi atualizado desde 2010.

Visite a Página de Aterrissagem do DirectX para obter mais recursos para desenvolvedores do DirectX.

Plataformas com Suporte

O pacote NuGet XAudio 2.9 (Microsoft.XAudio2.Redist.*.nupkg) inclui uma versão de 32 bits e 64 bits de uma DLL que implementa a API XAudio 2.9. A DLL é chamada XAUDIO2_9REDIST.DLL. Essa DLL funcionará no Windows 7 SP1, Windows 8, Windows 8.1 e Windows 10.

Quando a DLL é usada em um sistema de Windows 10, ela verifica o número de versão do XAUDIO2_9.DLL que faz parte do sistema operacional e, se o sistema operacional for mais recente, ele delegará todas as chamadas à API para XAUDIO2_9.DLL no sistema operacional. Isso garante que os aplicativos sempre usem a versão mais recente do XAudio 2.9 que está disponível na plataforma atual.

A DLL não se destina ao Xbox One. Se usada no Xbox One, a DLL sempre delegará todas as chamadas à API para XAUDIO2_9.DLL no sistema operacional Xbox One.

A DLL não se destina a aplicativos UWP. Os aplicativos UWP devem usar o XAUDIO2_9.DLL que faz parte do sistema operacional.

Instalando o pacote NuGet

A maneira mais fácil de instalar o pacote NuGet é usar o Gerenciador de Pacotes NuGet no Microsoft Visual Studio. Se você fizer isso, o arquivo de projeto do Visual Studio será atualizado automaticamente para incluir Microsoft.XAudio2.Redist.targets. O arquivo .targets adiciona a pasta Include com os arquivos de cabeçalho do XAudio2 à coleção de caminhos de inclusão do projeto. O arquivo .targets também tornará seu .DLL ou .EXE link com XAUDIO2REDIST. LIB e XAPOBASEREDIST. LIB.

A biblioteca XAPOBASEREDIST. O LIB só será necessário se você pretende implementar um XAPO (Objeto de Processamento XAudio) personalizado e pode removê-lo do Microsoft.XAudio2.Redist.targets se ele não for usado.

Você também pode usar outras ferramentas para extrair o conteúdo do pacote NuGet ou até mesmo renomear a extensão de arquivo para .zip e extrair os arquivos com qualquer ferramenta extrator ZIP.

Também há uma xaudio2redist porta disponível para o Gerenciador de Pacotes vc++.

Compilando seu aplicativo

Escolhendo quais cabeçalhos incluir

O pacote NuGet XAudio 2.9 inclui os mesmos arquivos de cabeçalho XAudio2 incluídos no SDK do Windows 10. No entanto, os arquivos de cabeçalho tiveram alguns ajustes para garantir que você possa usá-los enquanto direciona explicitamente todas as plataformas com suporte, incluindo versões mais antigas do Windows.

Se você instalar o pacote NuGet usando o Gerenciador de Pacotes NuGet no Microsoft Visual Studio, o caminho para os arquivos de cabeçalho será colocado na frente do caminho para os arquivos de cabeçalho do SDK do Windows. Isso significa que, se o código em seu projeto incluir o XAUDIO2. Cabeçalho H, ele selecionará o cabeçalho multiplataforma do pacote NuGet. Normalmente, esse é o comportamento desejado.

Você deve ter cuidado se adicionar o caminho aos cabeçalhos de inclusão manualmente ao projeto, pois especificá-los na ordem errada pode causar o XAUDIO2 específico da versão do sistema operacional . H a ser incluído no SDK do Windows, em vez da versão multiplataforma do XAUDIO2.H.

Para tornar a inclusão de cabeçalhos menos propensa a erros, o pacote NuGet contém uma versão de cada cabeçalho com "REDIST" acrescentado a ele. Por exemplo, além de XAUDIO2. H, o pacote NuGet também inclui XAUDIO2REDIST.H. Se preferir, seu código pode incluir diretamente XAUDIO2REDIST. H para eliminar qualquer ambiguidade sobre qual arquivo de cabeçalho está sendo usado. Ao incluir o -REDIST. Versão H de um arquivo de cabeçalho, a ordem na qual os diretórios de arquivo de inclusão estão listados no arquivo de projeto não importa.

Observe que, se o aplicativo também estiver sendo compilado para o Xbox One, você deverá continuar a incluir XAUDIO2. H ao compilar para Xbox One, pois algumas APIs específicas do Xbox One são excluídas de XAUDIO2REDIST.H. Este pacote NuGet não se destina ao Xbox One.

Carregando a DLL

Recomendamos que você vincule seu aplicativo ao XAUDIO2REDIST. LIB e instale XAUDIO2_9REDIST.DLL na mesma pasta que o executável do aplicativo. Isso fará com que XAUDIO2_9REDIST.DLL sejam carregados assim que o executável for iniciado. No entanto, se preferir, você poderá usar LoadLibraryEx e GetProcAddress para carregar XAUDIO2_9REDIST.DLL sob demanda. Essa é uma boa solução se seu aplicativo nem sempre precisar usar as APIs XAudio2. Mas, se você fizer isso, deverá manter o XAUDIO2_9REDIST.DLL carregado até que o aplicativo seja encerrado, pois tentar descarregar a DLL poderá causar uma falha se um thread em segundo plano ainda estiver executando código na DLL.

Ao contrário do XAudio 2.7 mais antigo, não é possível usar CoCreateInstance para carregar a DLL.

Verificando a assinatura de DLL

O binário XAUDIO2_9REDIST.DLL é assinado pela Microsoft usando uma assinatura SHA-2. Qualquer código que tente validar a assinatura, por exemplo, módulos anti-cheat para jogos, portanto, precisa dar suporte ao SHA-2. Observe que o Windows 7 SP1 originalmente não dá suporte ao SHA-2 e requer uma atualização para adicionar essa funcionalidade. A atualização está disponível como KB4474419.

Teste

Som espacial em versões mais recentes do Windows 10

A partir da atualização Windows 10 1903, o XAudio 2.9 usará automaticamente o som surround virtual, se determinadas condições forem atendidas. Recomendamos testar o jogo que gera som de vários canais no Windows 10 1903 (ou mais recente) para verificar se o jogo soa conforme o esperado.

Habilitando o som espacial

O usuário pode habilitar um formato de som espacial clicando com o botão direito do mouse no ícone do alto-falante na bandeja do sistema Windows.

O XAudio 2.9 usará apenas o formato de som espacial selecionado do usuário se o processo que está usando a API XAudio2 for reconhecido como um jogo pela Barra de Jogos do Windows. Durante o desenvolvimento, é possível que o processo ainda não seja reconhecido como um jogo pela Barra de Jogos. Para alterar isso, use o atalho de teclado Win+G para abrir a Barra de Jogos enquanto o jogo está em execução. Em seguida, clique no ícone "Configurações" e marcar caixa de seleção que diz "Lembre-se de que este é um jogo".

Recusando-se do som espacial

Há uma maneira de recusar que xAudio2 use o codificador de som espacial especificando determinados valores para o parâmetro AUDIO_STREAM_CATEGORY em IXAudio2::CreateMasteringVoice.

O som espacial está habilitado para estas categorias:

AudioCategory_ForegroundOnlyMedia
AudioCategory_GameEffects
AudioCategory_GameMedia
AudioCategory_Movie
AudioCategory_Media

O som espacial não será habilitado se qualquer uma das seguintes categorias for especificada:

AudioCategory_Other
AudioCategory_Communications
AudioCategory_Alerts
AudioCategory_SoundEffects
AudioCategory_GameChat
AudioCategory_Speech

Tratamento de erros

É importante testar se o jogo pode lidar com uma alteração no dispositivo de áudio, por exemplo, quando os fones de ouvido estão conectados ou desconectados. Isso deve ser testado com fones de ouvido que dão suporte apenas à taxa de amostragem de 44,1 kHz. Muitos fones de ouvido USB de baixo nível e fones de ouvido Bluetooth dão suporte apenas a 44,1 kHz. A transição entre a taxa de amostragem de 48 kHz e a taxa de amostragem de 44,1 kHz pode causar um erro mesmo quando o recurso de ponto de extremidade de áudio virtual é usado. O erro não ocorrerá se os fones de ouvido também oferecerem suporte a 48 kHz. Observe que o recurso de ponto de extremidade de áudio virtual não está disponível no Windows 7 SP1.

O código de erro retornado pelo XAudio 2.9 quando ele não pode se recuperar automaticamente de uma alteração no ponto de extremidade de áudio é XAUDIO2_E_DEVICE_INVALIDATED. No entanto, recomendamos que os aplicativos não embutam em código uma dependência no código de erro com um valor específico.

Para ser notificado sobre o erro, o aplicativo deve implementar a interface IXAudio2EngineCallback e fornecer um ponteiro para essa interface invocando o método IXAudio2::RegisterForCallbacks . A implementação do aplicativo do IXAudio2EngineCallback::OnCriticalError será invocada pela API XAudio2 se ocorrer um erro durante a reprodução.

Observe que IXAudio2EngineCallback::OnCriticalError não será necessariamente invocado se o pipeline de áudio estiver em pausa. Por exemplo, se o usuário minimizar o aplicativo ou se o aplicativo for suspenso por qualquer motivo, a reprodução de áudio poderá ser pausada. Se a alteração no dispositivo de áudio ocorrer durante esse tempo, o erro só será retornado quando o aplicativo invocar IXAudio2::StartEngine e/ou invocar IXAudio2SourceVoice::Start. Se a reprodução puder ser pausada com seu aplicativo, você deverá testar a alteração do dispositivo de áudio enquanto a reprodução estiver em pausa, para verificar se o aplicativo ainda pode se recuperar dessa situação.

Diferenças de API do XAudio 2.9 em comparação com o XAudio 2.7

Esta seção fornece um resumo de algumas das diferenças de API entre o XAudio 2.7 e a versão redistribuível do XAudio 2.9.

Formatos com suporte

O XAudio 2.9 dá suporte a estes formatos de entrada no computador:

PCM linear de 16 bits
PCM Float Linear de 32 bits
ADPCM de 16 bits
xWMA

O formato XMA só tem suporte no Xbox One.

Núcleo de CPU preferencial

É possível especificar qual núcleo de CPU XAudio 2.9 deve usar para seu thread de processamento de áudio. No entanto, geralmente, é preferível permitir que o XAudio 2.9 escolha esse valor por si só. Isso é feito definindo o parâmetro XAudio2Processor na chamada para XAudio2Criar para XAUDIO2_USE_DEFAULT_PROCESSOR.

O XAudio 2.9 escolherá um núcleo de CPU diferente no Xbox One do que no computador. O método IXAudio2Extension::GetProcessor pode ser usado para determinar qual núcleo de CPU XAudio2 escolheu.

Ponto de extremidade de áudio virtual

O XAudio 2.9 usará um ponto de extremidade de áudio virtual por padrão, ao ser executado em Windows 8 ou posterior. Isso significa que, se o ponto de extremidade de áudio padrão for alterado enquanto o XAudio 2.9 for usado, ele tentará alternar automaticamente para o novo ponto de extremidade de áudio. Um exemplo de quando isso pode acontecer quando o ponto de extremidade de áudio padrão é um par de fones de ouvido conectados por USB e, em seguida, o usuário desconecta os fones de ouvido. Isso fará com que os alto-falantes sejam o novo ponto de extremidade de áudio padrão.

Se o aplicativo especificar um formato de áudio específico ao invocar IXAudio2::CreateMasteringVoice, talvez não seja possível que o XAudio 2.9 execute essa opção. Por exemplo, se o aplicativo especificou que o Mastering Voice deve usar uma taxa de amostragem de 48 kHz e o novo dispositivo de áudio só dá suporte a 44,1 kHz, o comutador automático falhará e o XAudio 2.9 relatará o erro XAUDIO2_E_DEVICE_INVALIDATED .

É possível que o aplicativo opte por não usar o ponto de extremidade de áudio virtual passando o sinalizador XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT para IXAudio2::CreateMasteringVoice.

Os pontos de extremidade de áudio virtual não estão disponíveis no Windows 7 SP1. O sinalizador XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT não tem efeito no Windows 7 SP1.

Categorias de áudio

O aplicativo deve especificar uma categoria para seu fluxo de áudio. Isso é feito fornecendo um valor da enumeração AudioCategory ao invocar o método IXAudio2::CreateMasteringVoice . Por exemplo, AudioCategory_GameEffects. A categoria de áudio pode afetar como o Windows processa o som ou como ele representa o fluxo de áudio no painel de controle de volume. A categoria de áudio também afetará se o som surround virtual estiver habilitado automaticamente.

Duração do quantum de processamento de áudio

Na maioria dos computadores, o XAudio 2.9 processa áudio em partes de 10 milissegundos. Isso é chamado de quantum de processamento. No entanto, a duração desse quantum pode ser diferente de 10 milissegundos em algum hardware. Aplicativos que precisam saber o quantum exato podem invocar o método IXAudio2Extension::GetProcessingQuantum para recuperar o valor.

Som espacial e surround virtual

Normalmente, o XAudio 2.9 executa uma dobra para baixo qualquer áudio de vários canais para corresponder ao número "físico" de canais de áudio compatíveis com o ponto de extremidade de áudio. Por exemplo, se o jogo fornecer uma fonte de áudio de canal 7.1, mas o som for reproduzido em fones de ouvido, o XAudio 2.9 dobrará o áudio do canal 7.1 em estéreo, usando uma matriz de dobragem padrão do setor. Se o computador estiver conectado a um ponto de extremidade de áudio HDMI, o áudio do canal 7.1 será transmitido como está pela conexão HDMI.

Windows 10 adiciona suporte para áudio espacial, usando um codificador centralizado que codifica áudio em um formato de som espacial selecionado pelo usuário. Windows 10 vem incluído com um formato de som espacial chamado Windows Sonic. Outros formatos, como Dolby Atmos for Headphones, podem ser baixados da Microsoft Store. Alguns dos formatos de som espacial, como Windows Sonic e Dolby Atmos for Headphones, foram projetados para serem usados em pontos de extremidade de áudio estéreo. Esses formatos dobram o som surround para estéreo usando algoritmos proprietários que alcançam um efeito sonoro surround "virtual". Em outras palavras, o ouvinte pode perceber o som aparecendo de diferentes posições no espaço 3D mesmo usando apenas fones de ouvido ou enquanto escuta em um único par de alto-falantes estéreo.

Efeitos semelhantes podem ser obtidos usando as APIs X3DAudio incluídas no XAudio 2.9. A main diferença é que x3DAudio exige que o desenvolvedor do aplicativo programe explicitamente para áudio 3D, enquanto o som surround virtual é aplicado automaticamente a qualquer fonte de som baseada em canal tradional.

Em Windows 10 1903 e mais recentes, os jogos que usam o XAudio 2.9 usarão o formato de som espacial em todo o sistema que o usuário habilitou no ponto de extremidade de áudio, se houver. Isso significa que o XAudio 2.9 não executará a dobragem usual do som surround para estéreo. Em vez disso, o sinal de som surround será entregue ao codificador de som espacial (por exemplo, Windows Sonic) para obter um efeito sonoro surround virtual.

CreateHrtfApo

A função CreateHrtfApo só está disponível em Windows 10. Ele não é implementado no redistribuível XAudio 2.9.