> ## 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-CA/reference/audio/acphal/enums/acp_command_type)

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

*commandId*   \
Type : UINT64

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

*audioFrame*   \
Type : UINT32

Si un numéro de trame audio est spécifié, la commande sera traitée au début de cette trame audio, sauf si elle est déjà passée, auquel cas le traitement commencera à 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, soit 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 vise à mettre à jour un contexte, ce contexte sera 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 pourrait entraîner la perte de voix dans les graphes comportant un grand nombre 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 lorsque la commande se termine. Le pointeur correspondant vers l'adresse virtuelle doit être déclaré **volatile**. Ce mécanisme est semblable à un message de commande terminée, sauf qu'aucun message n'est requis pour signaler la fin d'une commande. Lorsque XAudio2 soumet une commande à l'ACP, il utilise ce pointeur de notification pour vérifier 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'ACP (Audio Control Processor), le SHAPE (Scalable Hardware Audio Processing Engine) et XMA.

La durée de vie des données soumises au moyen 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. Ce comportement vise à réduire au minimum la quantité de données à copier en interne. Si la gestion de la durée de vie des données de commande supplémentaires pose problème, une application peut s'inscrire aux messages *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 précis, toutes ces commandes sont traitées au début de la trame audio spécifiée, avant tout autre traitement.

Notez que, puisque toutes les commandes de l'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-CA/reference/audio/apu/functions/apucreateheap), créez un tas APU dont la taille non mise en cache est suffisante pour contenir tous les contextes dont le titre a besoin et toutes les notifications qu'il utilisera. Si cette méthode n'est pas appelée avant toute autre méthode ou ACP, un tas par défaut sera 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 le 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-CA/reference/audio/acphal/enums/acp_command_type)
[AcpHal](/fr-CA/reference/audio/acphal/acphal_members)


## Related topics

- [IAcpHal::SubmitCommand](/es/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_submitcommand.md)
- [IAcpHal](/reference/audio/acphal/interfaces/IAcpHal/iacphal.md)
- [IAcpHal::Connect](/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_connect.md)
- [ACP_COMMAND_TYPE](/es/reference/audio/acphal/enums/acp_command_type.md)