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

Soumet une commande à l'ACP.

## Syntaxe

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

### Paramètres

*command*   \
Type : [ACP\_COMMAND\_TYPE](/fr/reference/audio/acphal/enums/acp_command_type.md)

La commande. Reportez-vous à l'énumération [ACP\_COMMAND\_TYPE](/fr/reference/audio/acphal/enums/acp_command_type.md).

*commandId*   \
Type : UINT64

Identificateur arbitraire facultatif de la commande. Cet ID est retourné avec certains messages. Il s'agit d'un UINT64 afin de permettre de passer un pointeur comme ID de commande.

*audioFrame*   \
Type : UINT32

Si un numéro de trame audio est spécifié, la commande est traitée au début de cette trame audio, sauf si celle-ci est déjà passée, auquel cas le traitement commence à la trame audio suivante. Ce paramètre accepte également deux valeurs spéciales :

* `ACP_SUBMIT_PROCESS_COMMAND_ASAP` indique à l'ACP de traiter la commande dès que possible, sur la trame audio en cours si possible.
* `ACP_SUBMIT_PROCESS_COMMAND_NEXT_FRAME` indique à l'ACP de traiter la commande au début de la trame audio suivante. Si la commande consiste à mettre à jour un contexte, ce contexte est mis à jour avant le début du traitement du graphe de flux. Cela retarde le début du traitement du graphe de flux, ce qui peut entraîner la perte de voix dans les graphes comportant un nombre élevé de voix.

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

Données facultatives associées à la commande. La plupart des commandes nécessitent une structure de données.

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

Adresse physique facultative d'un élément UINT32 qui sera défini sur une valeur non nulle à la fin de la commande. Le pointeur correspondant vers l'adresse virtuelle doit être déclaré **volatile**. Ce mécanisme est similaire à un message de commande terminée, sauf qu'aucun message n'est nécessaire pour signaler la fin d'une commande. Lorsque XAudio2 soumet une commande à l'ACP, il utilise ce pointeur de notification pour déterminer si la commande est terminée.

### Valeur de retour

Type : HRESULT

Si la méthode réussit, elle retourne S\_OK. Si la méthode échoue, elle retourne l'un des codes suivants (liste partielle) :

| Code de retour | Description |
| - | - |
| E\_INVALIDARG | Un ou plusieurs arguments ne sont pas valides. |
| ACP\_E\_QUEUE\_FULL | La file d'attente des commandes est pleine. |

## Remarques

Il s'agit de la seule API qui permet à un titre de communiquer avec l'Audio Control Processor (ACP), le Scalable Hardware Audio Processing Engine (SHAPE) et XMA.

La durée de vie des données soumises à l'aide de cette méthode `SubmitCommand` est variable. Le pointeur vers la structure passée en entrée n'est référencé que pendant l'appel d'API ; un développeur peut donc utiliser des variables locales en toute sécurité. Si la commande contient un pointeur vers un autre bloc de données, ces données ne sont pas copiées et doivent rester présentes jusqu'à ce que l'ACP ait traité la commande. Cela permet de réduire la quantité de données à copier en interne. Si la gestion de la durée de vie des données supplémentaires de la commande pose problème, une application peut s'inscrire aux messages de *commande terminée* afin de recevoir un message exactement au moment où les données supplémentaires de la commande ne sont plus référencées.

Si un titre soumet une ou plusieurs commandes avec l'indicateur `ACP_SUBMIT_PROCESS_COMMAND_NEXT_FRAME` défini ou avec un numéro de trame audio spécifique, toutes ces commandes sont traitées au début de la trame audio spécifiée et avant tout autre traitement.

Notez que, comme toutes les commandes ACP sont asynchrones sur le processeur principal, un appel à `IAcpHal::SubmitCommand` ne bloque pas le traitement.

Voici la méthode la plus efficace pour qu'un titre utilise les notifications :

1. À l'aide de [ApuCreateHeap](/fr/reference/audio/apu/functions/apucreateheap.md), créez un tas APU dont la taille non mise en cache est suffisante pour contenir tous les contextes nécessaires au titre et toutes les notifications qu'il utilisera. Si cette méthode n'est pas appelée avant toute autre méthode ACP, un tas par défaut est alloué.

2. Allouez un tableau non mis en cache de UINT32 dont la taille est égale au nombre de notifications nécessaires, c'est-à-dire au nombre total de mises à jour de contexte qui seront émises par trame audio. Notez qu'il est très inefficace d'allouer une notification à la fois.

## Configuration requise

**En-tête :** acphal.h

**Plateformes prises en charge :** consoles de la famille XBOX One et consoles XBOX Series

## Voir aussi

[ACP\_COMMAND\_TYPE](/fr/reference/audio/acphal/enums/acp_command_type.md)
[AcpHal](/fr/reference/audio/acphal/acphal_members.md)


## Related topics

- [IAcpHal](/fr/reference/audio/acphal/interfaces/IAcpHal/iacphal.md)
- [Bonnes pratiques de construction de graphes de flux audio SHAPE](/fr/build/console-features/audio/overviews/best-practices-audio-flowgraph-construction.md)
- [IAcpHal::Connect](/fr/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_connect.md)
- [ACP_COMMAND_TYPE](/fr/reference/audio/acphal/enums/acp_command_type.md)
- [ACP_COMMAND_UPDATE_CONTEXTS](/fr/reference/audio/acphal/structs/acp_command_update_contexts.md)