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

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. É preferível o uso deste pacote redistribuível ao invés de redistribuir o XAudio 2.7 do SDK do DirectX, pois o XAudio 2.7 não é 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, Windows 10 e Windows 11. Há também uma versão ARM64 da DLL para Windows 11 no ARM.

Quando a DLL é usada em um sistema Windows 10/Windows 11, 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 ou Xbox Series X|S. Se usada no Xbox, a DLL sempre delegará todas as chamadas à API para XAUDIO2_9.DLL no sistema operacional Xbox.

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 fará sua .DLL ou .EXE se vincular a XAUDIO2REDIST.LIB e XAPOBASEREDIST.LIB.

A biblioteca XAPOBASEREDIST.LIB é necessária apenas se você pretende implementar um XAPO (Objeto de Processamento XAudio) personalizado e pode removê-la do Microsoft.XAudio2.Redist.targets caso não seja utilizado.

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 de extrator ZIP.

Há também 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 cabeçalho XAUDIO2.H, ele utilizará o cabeçalho multiplataforma do pacote NuGet. Normalmente, esse é o comportamento desejado.

Você deve ter cuidado ao adicionar o caminho para os cabeçalhos de inclusão manualmente ao projeto, pois especificá-los na ordem errada pode fazer com que o XAUDIO2.H específico da versão do sistema operacional seja incluído a partir do 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 a versão -REDIST.H de um arquivo de cabeçalho, a ordem na qual os diretórios de inclusão de arquivos são listados no arquivo de projeto não importa.

Observe que, se o aplicativo também estiver sendo compilado para 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 do XAUDIO2REDIST.H. Esse 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 o XAUDIO2_9REDIST.DLL seja carregado 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 o aplicativo nem sempre precisar usar as APIs XAudio2. No entanto, se você fizer isso, deverá manter o XAUDIO2_9REDIST.DLL carregado até que o aplicativo seja encerrado, pois a tentativa de descarregar a DLL poderá causar uma falha se um thread em segundo plano ainda estiver executando o 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 a 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 do 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 do teclado Win+G para abrir a Barra de Jogos enquanto o jogo está em execução. Em seguida, clique no ícone "Configurações" e marque a caixa de seleção que diz: "Lembre-se de que este é um jogo".

Desativar o som espacial

Há uma maneira de recusar que o 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:

• CategoriaDeAudio_ApenasMídiaEmPrimeiroPlano
• CategoriaDeÁudio_EfeitosDeJogo
• CategoriaDeÁudio_MídiaDeJogo
• CategoriaDeÁudio_Filme
• CategoriaDeÁudio_Mídia

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

• CategoriaDeÁudio_Outro
• AudioCategory_Comunicações
• CategoriaDeAudio_Alertas
• CategoriaDeÁudio_EfeitosSonoros
• CategoriaDeÁudio_BatePapoDoJogo
• 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 só dão suporte 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 terminal de áudio virtual não está disponível no Windows 7 SP1.

O código de erro retornado pelo XAudio 2.9 quando não consegue se recuperar automaticamente de uma mudança no dispositivo de áudio é XAUDIO2_E_DEVICE_INVALIDATED. No entanto, recomendamos que os aplicativos não codifiquem 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 de IXAudio2EngineCallback::OnCriticalError do aplicativo 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 for pausado. 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 pausada, 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 esses formatos de entrada no PC:

• 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 O 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 sozinho. Isso é feito definindo o parâmetro XAudio2Processor na chamada para XAudio2Create 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.

Terminal de áudio virtual

O XAudio 2.9 usará um ponto de extremidade de áudio virtual por padrão, ao ser executado no 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. Em seguida, o usuário desconecta os fones de ouvido. Isso fará com que os alto-falantes sejam o novo dispositivo 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 determinou que o Mastering Voice deve utilizar uma taxa de amostragem de 48 kHz e o novo dispositivo de áudio apenas suporta 44,1 kHz, a troca automática falhará e o XAudio 2.9 relatará o erro XAUDIO2_E_DEVICE_INVALIDATED.

É possível que o aplicativo opte por não utilizar o endpoint de áudio virtual passando a flag XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT para IXAudio2::CreateMasteringVoice.

Os endpoints 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, CategoriaDeAudio_EfeitosDeJogo. 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 afeta se o som surround virtual estiver habilitado automaticamente.

Duração do processamento de áudio quântico

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. Os aplicativos que precisam saber o quantum exato podem invocar o método IXAudio2Extension::GetProcessingQuantum para recuperar o valor.

Som espacial e surround virtual

A partir da atualização do 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. Consulte a seção testando som espacial para uma discussão sobre como testar esse recurso.

Normalmente, o XAudio 2.9 realiza uma redução do áudio multicanal para ajustar-se ao número real de canais de áudio compatíveis com o endpoint de áudio. Por exemplo, se o jogo fornecer uma fonte de áudio em canais 7.1 mas o som for reproduzido em fones de ouvido, o XAudio 2.9 converterá o áudio 7.1 em estéreo, usando uma matriz de redução padrão da indústria. Se o computador estiver conectado a um ponto de extremidade de áudio HDMI, o áudio do canal 7.1 será transmitido as-is pela conexão HDMI.

O Windows 10 adiciona suporte para áudio espacial, usando um codificador centralizado que codifica o áudio em um formato de som espacial selecionado pelo usuário. O Windows 10 vem incluído com um formato de som espacial chamado Windows Sonic. Outros formatos, como Dolby Atmos para Fones de Ouvido, podem ser baixados da Microsoft Store. Alguns dos formatos de som espacial, como o Windows Sonic e o Dolby Atmos para Headphones, foram projetados para serem usados em dispositivos de áudio estéreo. Esses formatos convertem o som surround em estéreo utilizando algoritmos proprietários que criam um efeito de som 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 principal diferença é que o 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.

No Windows 10, versão 1903 e versões mais recentes, os jogos que usam o XAudio 2.9 usarão o formato de som espacial do sistema que o usuário habilitou no dispositivo de áudio, se houver. Isso significa que o XAudio 2.9 não executará a redução habitual 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 de som surround virtual.

CreateHrtfApo

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