> ## 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.

# IAcpHal::SubmitCommand

> IAcpHal::SubmitCommand

# IAcpHal::SubmitCommand

Envia um comando para o ACP.

## Sintaxe

```cpp theme={null}
HRESULT SubmitCommand(  
         ACP_COMMAND_TYPE command,  
         UINT64 commandId,  
         UINT32 audioFrame,  
         const void* data= nullptr,  
         APU_ADDRESS notification= 0  
)  
```

### Parâmetros

*command*   \
Tipo: [ACP\_COMMAND\_TYPE](/pt-BR/reference/audio/acphal/enums/acp_command_type)

O comando. Consulte a enumeração [ACP\_COMMAND\_TYPE](/pt-BR/reference/audio/acphal/enums/acp_command_type).

*commandId*   \
Tipo: UINT64

Identificador arbitrário e opcional do comando. Esse ID será retornado com mensagens específicas. É um UINT64 para permitir passar um ponteiro como o ID do comando.

*audioFrame*   \
Tipo: UINT32

Se um número de quadro de áudio for especificado, o comando será processado no início desse quadro de áudio, a menos que ele já tenha passado; nesse caso, o processamento começará no próximo quadro de áudio. Também há dois valores especiais para este parâmetro:

* `ACP_SUBMIT_PROCESS_COMMAND_ASAP` instrui o ACP a processar o comando o mais rápido possível—no quadro de áudio atual, se possível.
* `ACP_SUBMIT_PROCESS_COMMAND_NEXT_FRAME` instrui o ACP a processar o comando no início do próximo quadro de áudio. Se o comando for para atualizar um contexto, esse contexto será atualizado antes do início do processamento do flowgraph. Isso atrasa o início do processamento do flowgraph, o que pode fazer com que grafos com grande número de vozes descartem vozes.

*data*   \_In\_opt\_\
Tipo: void\*

Dados opcionais associados ao comando. A maioria dos comandos exige uma estrutura de dados.

*notification*   \_In\_opt\_\
Tipo: APU\_ADDRESS

Endereço físico opcional de um elemento UINT32 que será definido como um valor diferente de zero quando o comando for concluído. O ponteiro correspondente para o endereço virtual deve ser declarado como **volatile**. Isso é semelhante a uma mensagem de comando concluído, exceto que não é necessária uma mensagem para sinalizar a conclusão de um comando. Quando o XAudio2 envia um comando para o ACP, ele usa esse ponteiro de notificação ao verificar se o comando foi concluído.

### Valor retornado

Tipo: HRESULT

Se o método for bem-sucedido, ele retornará S\_OK. Se o método falhar, ele retornará um dos seguintes códigos (lista parcial):

| Código de retorno | Descrição |
| - | - |
| E\_INVALIDARG | Um ou mais argumentos são inválidos. |
| ACP\_E\_QUEUE\_FULL | A fila de comandos está cheia. |

## Comentários

Esta é a única API que permite que um título se comunique com o Audio Control Processor (ACP), o Scalable Hardware Audio Processing Engine (SHAPE) e o XMA.

O tempo de vida dos dados enviados usando este método `SubmitCommand` é variável. O ponteiro para a estrutura passada como entrada é referenciado apenas durante a chamada da API; isso significa que um desenvolvedor pode usar variáveis locais com segurança. Se o comando contiver um ponteiro para outro bloco de dados, esses dados não serão copiados e deverão permanecer presentes até que o ACP tenha processado o comando. Isso é feito para minimizar a quantidade de dados a serem copiados internamente. Se o gerenciamento do tempo de vida dos dados adicionais do comando for uma preocupação, um aplicativo poderá se registrar para receber mensagens de *comando concluído*, para receber uma mensagem exatamente quando os dados adicionais do comando não estiverem mais sendo referenciados.

Se um título enviar um ou mais comandos com o sinalizador `ACP_SUBMIT_PROCESS_COMMAND_NEXT_FRAME` definido ou com um número de quadro de áudio específico, todos esses comandos serão processados no início do quadro de áudio especificado e antes que qualquer outro processamento seja executado.

Observe que, como todos os comandos do ACP são assíncronos na CPU principal, uma chamada para `IAcpHal::SubmitCommand` não bloqueará o processamento.

Veja a seguir o método mais eficiente para um título usar notificações:

1. Usando [ApuCreateHeap](/pt-BR/reference/audio/apu/functions/apucreateheap), crie um heap da APU em que o tamanho não armazenado em cache seja grande o suficiente para conter todos os contextos de que o título precisa e todas as notificações que ele usará. Se esse método não for chamado antes de qualquer outro método ou ACP, um heap padrão será alocado.

2. Aloque uma matriz não armazenada em cache de UINT32s com tamanho igual ao número de notificações necessárias: ou seja, o número total de atualizações de contexto que serão emitidas por quadro de áudio. Observe que é muito ineficiente alocar uma notificação por vez.

## Requisitos

**Cabeçalho:** acphal.h

**Plataformas com suporte:** consoles da família XBOX One e consoles XBOX Series

## Confira também

[ACP\_COMMAND\_TYPE](/pt-BR/reference/audio/acphal/enums/acp_command_type)
[AcpHal](/pt-BR/reference/audio/acphal/acphal_members)


## Related topics

- [IAcpHal](/pt-BR/reference/audio/acphal/interfaces/IAcpHal/iacphal.md)
- [Práticas recomendadas para construção de flowgraphs de áudio do SHAPE](/pt-BR/build/console-features/audio/overviews/best-practices-audio-flowgraph-construction.md)
- [IAcpHal::Connect](/pt-BR/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_connect.md)
- [ACP_COMMAND_TYPE](/pt-BR/reference/audio/acphal/enums/acp_command_type.md)
- [ACP_COMMAND_UPDATE_CONTEXTS](/pt-BR/reference/audio/acphal/structs/acp_command_update_contexts.md)