> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão geral do XMA2

> Como funciona a descompactação de áudio por hardware do XMA2 no XBOX One e como ela se compara à decodificação por software do xWMA para conteúdo de áudio de jogos com XAudio2.

No XBOX One, a descompactação de áudio XMA2 é implementada em hardware. No entanto, o xWMA não é, e requer decodificação por software. O XMA2 e o xWMA usam os mesmos algoritmos de compactação, mas o xWMA oferece uma variedade maior de formatos de codificação. Codifique para XMA2 para obter benefícios de desempenho e compactação, mas observe que algumas músicas de alta fidelidade podem soar melhor se renderizadas por meio do xWMA - isso exigiria testes de audição. Codificar XMA2 por meio do `XAudio2` deve ser a abordagem mais simples, mas o XMA2 pode ser codificado diretamente para o hardware usando os comandos do ACP (Audio Control Processor).

<Note>Tanto o xWMA quanto o XMA2 têm origem nos codecs desenvolvidos para o WMA (Windows Media Audio), e ambos foram desenvolvidos especificamente para jogos XBOX. O subconjunto dos codecs e parâmetros disponíveis usado pelo XMA2 é menor que o subconjunto usado pelo xWMA. Embora tanto o xWMA quanto o XMA2 tenham sido desenvolvidos para XBOX, eles não são intercambiáveis: os cabeçalhos de cada formato de arquivo são diferentes, e os formatos são incompatíveis com as versões do Windows para PC. Os codecs usados para XMA2 e xWMA também são ligeiramente diferentes, portanto, cada um terá seus próprios artefatos do sistema de compactação usado.</Note>

Este tópico aborda o seguinte:

* [Codificação XMA2](#ID4E3)
* [Erro de barramento AXI do XMA2](#ID4ENC)

<a id="ID4E3" />

## Codificação XMA2

Codifique dados de áudio para XMA2 usando a [ferramenta de codificação XMA2](/pt-BR/build/console-features/audio/tools/xma2encodertool), fornecida como parte do Microsoft Game Development Kit (GDK). Arquivos XMA2 são arquivos .wav que têm o cabeçalho de formato [XMA2WAVEFORMATEX](/pt-BR/reference/audio/xma2defs/structs/xma2waveformatex) e um bloco `seek` adicional na tabela de localização `Seek`.

O formato XMA2 é compatível com o XBOX 360, e a tabela `Seek` deve ter os bytes invertidos como `ULONG` para o XBOX One. Se a entrada for um arquivo .wav, a saída poderá ser usada sem alteração.

Para inverter os bytes da tabela `Seek`, use as linhas de código a seguir.

```cpp theme={null}
      for(UINT32 i = 0;(i < xmaformat->BlockCount);i++)
      {
      rgpXMASeekTable[i] = _byteswap_ulong(rgpXMASeekTable[i]);
      }  
```

Considere adicionar esse código primeiro ao seu aplicativo para testar a funcionalidade e, depois, talvez escrever uma ferramenta separada para realizar a inversão, de modo que nenhum pré-processamento seja exigido do seu aplicativo.

Para o XBOX One, todos os buffers de entrada e saída de DMA (Direct Memory Access) usados com grafos de fluxo, e todo o conteúdo XMA enviado a um buffer de origem, devem ser alocados usando o método [ApuAlloc](/pt-BR/reference/audio/apu/functions/apualloc) e liberados usando o método [ApuFree](/pt-BR/reference/audio/apu/functions/apufree). Isso é mostrado no código a seguir. Observe o uso do sinalizador `SHAPE_XMA_INPUT_BUFFER_ALIGNMENT` para ajudar a garantir que os blocos estejam alinhados corretamente.

```cpp theme={null}
      HRESULT ApuVirtualAllocate(void** virtualAddress,UINT32 sizeInBytes)
      {
        DWORD dwsize = sizeInBytes;
        DWORD change = 0;
        if(FixBlockAlign((DWORD*)&sizeInBytes,SHAPE_XMA_INPUT_BUFFER_SIZE_ALIGNMENT,&change)) // Returns TRUE if an alignment was needed; else, returns FALSE.
        {
          return E_INVALIDARG;
        }
        return ApuAlloc(virtualAddress,NULL,sizeInBytes,SHAPE_XMA_INPUT_BUFFER_ALIGNMENT);
      }

      void ApuVirtualFree(void* virtualAddress)
      {
        if(virtualAddress)
        {
          ApuFree(virtualAddress);
        }
      }

      BOOL FixBlockAlign(DWORD* pBYTES,DWORD BLOCKALIGN,DWORD* pChange)
      {
        if(pBYTES && (BLOCKALIGN > 1))
        {
          DWORD bytes = (*pBYTES);
          (*pBYTES) /=  BLOCKALIGN;
          (*pBYTES) *=  BLOCKALIGN;
          if(pChange)
          {
            (*pChange) = bytes&mdash;(*pBYTES);
            if((*pChange) > 0)
            {
              return TRUE;
            }
          }
        }
        return FALSE;
      }  
```

Para obter detalhes sobre como usar os campos da estrutura com um arquivo codificado em XMA2, consulte a estrutura [XMA2WAVEFORMATEX](/pt-BR/reference/audio/xma2defs/structs/xma2waveformatex).

<a id="ID4ENC" />

## Erro de barramento AXI do XMA2

Um bug antigo no decodificador de hardware XMA (e no XBOX 360) exige que os títulos forneçam uma solução alternativa caso usem `AcpHal` diretamente. O `XAudio2` já fornece a solução alternativa. No entanto, até que a ferramenta de codificação XMA2 seja atualizada, observe as informações a seguir.

Ao decodificar fluxos de bits XMA e usar apenas um único buffer de entrada XMA, você pode disparar um erro de barramento AXI se os últimos 64 bytes do buffer XMA contiverem dados codificados. Um fluxo de bits XMA raramente contém dados codificados nos últimos 64 bytes. Mesmo assim, isso deve ser tratado para evitar o erro de barramento AXI. Até que a ferramenta de codificação XMA2 seja atualizada para garantir que nenhum arquivo codificado contenha dados codificados nos últimos 64 bytes do fluxo de bits, você pode evitar esse problema usando um dos métodos a seguir.

* Sempre use ambos os buffers de entrada XMA e nunca defina o ponteiro de qualquer um dos buffers de entrada como um valor inválido.

* Defina o ponteiro do buffer de entrada não utilizado como igual ao ponteiro do outro buffer de entrada, mesmo que você não vá habilitar o outro buffer. Veja um exemplo a seguir.

```cpp theme={null}
      context->ptrRead1 = context->ptrRead0  
```

* Ao gerar conteúdo, use uma ferramenta offline para verificar seus arquivos XMA. Se qualquer um dos últimos 64 bytes do fluxo de bits XMA codificado tiver um valor diferente de 0xFF, codifique o arquivo novamente.

Qualquer um desses métodos impede que o pré-buscador do XMA leia um endereço inválido.

<a id="ID4EFD" />

## Documentação de referência da API

* [APU (conteúdo da API)](/pt-BR/reference/audio/apu/apu_members)
  * Funções
    * [ApuAlloc](/pt-BR/reference/audio/apu/functions/apualloc)
    * [ApuFree](/pt-BR/reference/audio/apu/functions/apufree)
* [XMA2Defs (conteúdo da API)](/pt-BR/reference/audio/xma2defs/xma2defs_members)
  * Estruturas
    * [XMA2WAVEFORMATEX](/pt-BR/reference/audio/xma2defs/structs/xma2waveformatex)

## Confira também

[Ferramenta de codificação XMA2](/pt-BR/build/console-features/audio/tools/xma2encodertool)


## Related topics

- [XMA2STREAMFORMAT](/pt-BR/reference/audio/xma2defs/structs/xma2streamformat.md)
- [XMA2WAVEFORMAT](/pt-BR/reference/audio/xma2defs/structs/xma2waveformat.md)
- [XMA2WAVEFORMATEX](/pt-BR/reference/audio/xma2defs/structs/xma2waveformatex.md)
- [XMA2PACKET](/pt-BR/reference/audio/xma2defs/structs/xma2packet.md)
- [Ferramenta de codificação XMA2](/pt-BR/build/console-features/audio/tools/xma2encodertool.md)