IAcpHal::SubmitCommand
Envia um comando para o ACP.Sintaxe
Parâmetros
commandTipo: ACP_COMMAND_TYPE O comando. Consulte a enumeração 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_ASAPinstrui 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_FRAMEinstrui 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.
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):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étodoSubmitCommand é 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:
- Usando 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.
- 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.