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 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_ASAPindique à l’ACP de traiter la commande dès que possible, 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 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.
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) :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é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. 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 :
- À l’aide de ApuCreateHeap, 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é.
- 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.