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 esta 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 deste redistribuível é preferível à redistribuição do XAudio 2.7 a partir do SDK do DirectX, uma vez que o XAudio 2.7 não foi atualizado desde 2010.

Certifique-se de visitar o da página inicial do DirectX para obter mais recursos para desenvolvedores do DirectX.

Plataformas suportadas

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

Quando a DLL é usada em um sistema Windows 10, ela verifica o número da 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 de 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 de 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, seu arquivo de projeto do Visual Studio será atualizado automaticamente para incluir Microsoft.XAudio2.Redist.targets. O arquivo de .targets adiciona a pasta Include com os arquivos de cabeçalho para o XAudio2 à sua coleção de caminhos de inclusão de projeto. O arquivo .targets também fará com que o seu .DLL ou .EXE se ligue com XAUDIO2REDIST.LIB e XAPOBASEREDIST.LIB.

A biblioteca XAPOBASEREDIST.LIB só é necessária caso pretenda implementar um XAudio Processing Object (XAPO) personalizado e poderá removê-la do Microsoft.XAudio2.Redist.targets se não for 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 porta xaudio2redist disponível para o VC++ Package Manager.

Compilando seu aplicativo

Escolher os cabeçalhos a 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 ficheiros de cabeçalho foram ajustados para garantir que podem ser utilizados ao direcionar explicitamente todas as plataformas suportadas , 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á posicionado antes do caminho para os arquivos de cabeçalho do SDK do Windows. Isso significa que, se o código no seu projeto incluir o cabeçalho XAUDIO2.H, ele irá buscar o cabeçalho multiplataforma do pacote NuGet. Este é normalmente o comportamento desejado.

Você deve ter cuidado ao adicionar manualmente o caminho para os cabeçalhos de inclusão no projeto, pois especificá-los na ordem errada pode fazer com que o XAUDIO2.H específico da versão do sistema operativo 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" anexado 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 ficheiro de cabeçalho, a ordem em que os diretórios do ficheiro de inclusão são listados no ficheiro de projeto não é importante.

Tenha em atenção que, se a sua aplicação também estiver a ser compilada para a Xbox One, deverá continuar a incluí-XAUDIO2. H ao compilar para Xbox One, pois algumas APIs específicas do Xbox One são excluídas do XAUDIO2REDIST.H. Este pacote NuGet não se destina à 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 seu aplicativo. Isso fará com que XAUDIO2_9REDIST.DLL seja carregado assim que o executável for iniciado. No entanto, se preferir, você pode usar LoadLibraryEx e GetProcAddress para carregar XAUDIO2_9REDIST.DLL sob demanda. Esta é uma boa solução se o seu aplicativo nem sempre precisa usar as APIs XAudio2. Mas se você fizer isso, você deve manter o XAUDIO2_9REDIST.DLL carregado até que o aplicativo saia, pois tentar descarregar a DLL pode 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 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 suportar SHA-2. Observe que o Windows 7 SP1 originalmente não suportava SHA-2 e requer uma atualização para adicionar essa funcionalidade. A atualização está disponível como KB4474419.

Testes

Som espacial em versões mais recentes do Windows 10

A partir da atualização 1903 do Windows 10, o XAudio 2.9 usa automaticamente o som surround virtual, se determinadas condições forem cumpridas. Recomendamos testar jogos que geram som multicanal no Windows 10 1903 (ou mais recente) para verificar se o jogo soa conforme o esperado.

Ativar o som espacial

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

O XAudio 2.9 só usará o formato de som espacial selecionado pelo 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 Game Bar. Para alterar isso, use o atalho de teclado Win+G para abrir a Barra de Jogo 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 que este é um jogo".

Optar por não participar no som espacial

Há uma maneira de optar por não fazer com que o XAudio2 use o codificador de som espacial especificando certos valores para o parâmetro AUDIO_STREAM_CATEGORY em IXAudio2::CreateMasteringVoice.

O som espacial está ativado para estas categorias:

• CategoriaDeÁudio_ApenasMídiaEmPrimeiroPlano
• CategoriaÁudio_EfeitosJogo
• CategoriaÁudio_MídiaJogo
• CategoriaÁudio_Filme
• ÁudioCategoria_Mídia

O som espacial não é ativado se qualquer uma das seguintes categorias for especificada:

• CategoriaÁudio_Outros
• AudioCategory_Comunicações
• CategoriaÁudio_Alertas
• CategoriaDeÁudio_EfeitosSonoros
• CategoriaDeÁudio_ConversaDeJogo
• CategoriaDeÁudio_Fala

Tratamento de erros

É importante testar se você pode lidar com uma mudança 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 suportam apenas uma taxa de amostragem de 44,1 kHz. Muitos auscultadores USB low-end e auriculares Bluetooth suportam apenas 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 é utilizado. O erro não acontecerá se os auscultadores também suportarem 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 não consegue recuperar-se automaticamente de uma alteração no dispositivo de áudio é XAUDIO2_E_DEVICE_INVALIDATED. No entanto, recomendamos que os aplicativos não codificem uma dependência do código de erro com um valor específico.

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

Nota que IXAudio2EngineCallback::OnCriticalError não será necessariamente chamado se o canal de áudio estiver pausado. Por exemplo, se o usuário minimizar o aplicativo ou 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ê deve testar a alteração do dispositivo de áudio enquanto a reprodução está pausada, para verificar se o aplicativo ainda pode se recuperar dessa situação.

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

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

Formatos suportados

XAudio 2.9 suporta estes formatos de entrada no PC:

• PCM linear de 16 bits
• PCM flutuante linear de 32 bits
• ADPCM de 16 bits
• xWMA

O formato XMA só é suportado na Xbox One.

Núcleo de CPU preferido

É possível especificar qual núcleo da CPU XAudio 2.9 deve usar para seu thread de processamento de áudio. No entanto, geralmente é preferível deixar XAudio 2.9 escolher este valor por si só. 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 PC. O método IXAudio2Extension::GetProcessor pode ser usado para determinar qual núcleo da CPU XAudio2 escolheu.

Ponto de extremidade de áudio virtual

O XAudio 2.9 usará um ponto de extremidade de áudio virtual por padrão, quando executado no Windows 8 ou posterior. Isso significa que, se o ponto de extremidade de áudio padrão mudar 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 para o XAudio 2.9 executar 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 suporta apenas 44,1 kHz, o interruptor automático falhará e o XAudio 2.9 relatará o erro XAUDIO2_E_DEVICE_INVALIDATED.

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

Interfaces 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 afeta se o som surround virtual está ativado automaticamente.

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

Na maioria dos PCs, o XAudio 2.9 processa áudio em blocos de 10 milissegundos. Isso é chamado de quantum de processamento. No entanto, a duração deste 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 usa automaticamente o som surround virtual, se determinadas condições forem satisfeitas. Recomendamos testar jogos que geram som multicanal no Windows 10 1903 (ou mais recente) para verificar se o jogo soa conforme o esperado. Consulte a seção testando o som espacial para obter uma discussão sobre como testar esse recurso.

Normalmente, o XAudio 2.9 reduz qualquer áudio multicanal para corresponder ao número "físico" de canais de áudio suportados pelo dispositivo de áudio. Por exemplo, se o jogo fornecer uma fonte de áudio de 7.1 canais, mas o som for reproduzido em fones de ouvido, o XAudio 2.9 converterá o áudio de 7.1 canais para estéreo, utilizando uma matriz de conversão padrão da indústria. Se o PC estiver ligado a um terminal de áudio HDMI, o áudio de 7.1 canais será transmitido as-is através da ligação HDMI.

O Windows 10 adiciona suporte para áudio espacial, usando um codificador centralizado que codifica o áudio em um formato de 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 auscultadores, foram concebidos para serem utilizados em terminais de áudio estéreo. Esses formatos convertem o som surround em estéreo usando algoritmos proprietários que alcançam 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 enquanto usa apenas fones de ouvido, ou enquanto ouve em um único par de alto-falantes estéreo.

Efeitos semelhantes podem ser alcançados usando os APIs X3DAudio que estão incluídos no XAudio 2.9. A principal diferença é que o X3DAudio requer 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 tradicional.

Nos Windows 10 1903 e mais recentes, os jogos que usam XAudio 2.9 utilizarão o formato de som espacial do sistema que o utilizador habilitou na saída de áudio, caso tenha sido habilitada. Isto significa que o XAudio 2.9 não irá realizar a habitual dobragem 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. Não está implementado no XAudio 2.9 redistributável.