IAcpHal::SubmitCommand
Soumet une commande à l’ACP.Syntaxe
Paramètres
commandType : ACP_COMMAND_TYPE La commande. Reportez-vous à l’énumération 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_ASAPindique à l’ACP de traiter la commande dès que possible, soit sur la trame audio en cours si possible.ACP_SUBMIT_PROCESS_COMMAND_NEXT_FRAMEindique à 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.
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) :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éthodeSubmitCommand 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 :
- À l’aide de 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é.
- 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.