> ## 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. # Vue d'ensemble de l'ACP > Guide de programmation de l'Audio Control Processor (ACP) et de la bibliothèque acphal qui gère les graphes de flux audio SHAPE sur les consoles XBOX One. Cette rubrique fournit des descriptions et des exemples des graphes de flux (flowgraphs) utilisés pour diriger l'Audio Control Processor (ACP). ## Vue d'ensemble de l'ACP Cette section décrit l'interface de programmation de l'ACP. La bibliothèque `acphal` (*acphal.lib*) définit l'ensemble d'API du Scalable Hardware Audio Processing Engine (SHAPE). Le Microsoft Game Development Kit (GDK) comprend également un ensemble d'utilitaires audio et de code source pour vous aider à préparer les données audio en vue de leur utilisation avec SHAPE. Les en-têtes des utilitaires définissent les éléments suivants : * Les structures de contexte pour chaque format de données pris en charge * Un ensemble complet de fonctions permettant de lire et d'écrire dans ces contextes Définissez au moins un graphe de flux dans votre application pour acheminer les données audio *à travers* les blocs SHAPE. L'ACP gère les blocs SHAPE et en assure l'efficacité. Pour plus de détails sur l'ensemble d'API, y compris les structures et les énumérations déclarées dans les fichiers d'utilitaires, consultez la référence [AcpHal](/fr-CA/reference/audio/acphal/acphal_members). Pour plus de détails sur l'architecture SHAPE, consultez la [vue d'ensemble de SHAPE](/fr-CA/build/console-features/audio/overviews/shape-overview). Dans les fichiers sources d'un projet de titre, assurez-vous d'inclure le fichier *ShapeContext.h*, et non les fichiers d'en-tête de contexte individuels. Dans cette rubrique : * [Graphes de flux](#ID4EVB) * [Utilitaires DMA](#ID4EZH) * [Utilitaires de compresseur EQ](#ID4EIAAC) * [Utilitaires de filtre de volume](#ID4EWAAC) * [Utilitaires PCM](#ID4EEBAC) * [Utilitaires SRC](#ID4ESBAC) * [Utilitaires XMA](#ID4EACAC) * [Valeurs cibles](#ID4EXEAC) * [Sécurité des threads](#ID4E3NAC) * [Lignes directrices pour l'utilisation du SRC avec les données PCM et XMA](#ID4EUPAC) * [Suspension et reprise d'un titre](#ID4E5BAE) ### Graphes de flux Pour utiliser SHAPE, un titre crée habituellement un graphe de flux SHAPE. Pour une description d'une solution de rechange, consultez la section [Utilitaires XMA](#ID4EACAC). Un graphe de flux SHAPE est un tableau de commandes (une par bloc SHAPE), accompagné de données de contexte, qui décrit l'ordre des opérations des blocs individuels et les données sur lesquelles ils agissent. L'ACP utilise les données du graphe de flux pour planifier correctement les opérations dans les blocs SHAPE. Le titre est responsable de la construction du graphe de flux et de sa soumission à l'ACP. Pour construire un graphe de flux, utilisez [ShapeFlowGraph (méthodes utilitaires de graphe de flux)](/fr-CA/reference/audio/shapeflowgraph/shapeflowgraph_members). Dans les figures suivantes, les blocs verts représentent les composants SHAPE, les blocs cyan sont le matériel source et les cercles jaunes étiquetés sont les tampons de mixage matériels. * [Sons 3D](#ID4EHC) * [Frontal d'un moteur audio logiciel](#ID4ETC) * [Rendu audio](#ID4E6C) * [Analyse des graphes de flux](#ID4EHF) * [Mise à jour des graphes de flux](#ID4EHG) * [Graphes de flux multiples](#ID4ELH) #### Sons 3D **Figure 1. Deux voix, chacune répartie (panoramique) entre deux sorties, avec un envoi vers une sortie commune.** Graphe de flux de deux voix Dans le code, ce graphe de flux peut être représenté comme suit. ```cpp theme={null} typedef enum mixBuffers { noBuffer = 0, mixBuffer_1 = 1, mixBuffer_2 = 2, mixBuffer_3 = 3, mixBuffer_4 = 4, mixBuffer_5 = 5, mixBuffer_6 = 6, mixBuffer_7 = 7, mixBuffer_8 = 8, mixBuffer_9 = 9, mixBuffer_10 = 10, mixBuffer_11 = 11 }; typedef enum DMAcontexts { DMAcontext_0 = 0, DMAcontext_1 = 1, DMAcontext_2 = 2, DMAcontext_3 = 3, DMAcontext_4 = 4, }; typedef enum FLTVOLcontexts { FLTVOLcontext_0 = 0, FLTVOLcontext_1 = 1, FLTVOLcontext_2 = 2, FLTVOLcontext_3 = 3, FLTVOLcontext_4 = 4, FLTVOLcontext_5 = 5, FLTVOLcontext_6 = 6, FLTVOLcontext_7 = 7, }; typedef enum EQcontexts { EQcontext_0 = 0, EQcontext_1 = 1, }; typedef enum SRCcontexts { SRCcontext_0 = 0, SRCcontext_1 = 1, }; typedef enum XMAcontexts { XMAcontext_0 = 0, XMAcontext_1 = 1, }; // // Command structure to be initialized. // #define nSHAPE_3Dpan_commands 28 // SHAPE_FLOWGRAPH_COMMAND cmd[nSHAPE_3Dpan_commands]; // // Shared mix buffer. // // SetShapeAllocMixBufferCommand parameters: // command, virtualID, numIn, numOut, attenuation SetShapeAllocMixBufferCommand(&cmd[0], mixBuffer_1, 2, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); // // Mix buffers for voice A. // // SetShapeAllocMixBufferCommand parameters: // command, virtualID, numIn, numOut, attenuation SetShapeAllocMixBufferCommand(&cmd[1], mixBuffer_2, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[2], mixBuffer_3, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[3], mixBuffer_4, 1, 3, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[4], mixBuffer_5, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[5], mixBuffer_6, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); // // Voice A. // // SetShapeSrcXmaCommand parameters: // command, contextID, XMAContextID, leftorMonoMixBuffer, rightMixBuffer SetShapeSrcXmaCommand( &cmd[6], SRCcontext_0, XMAcontext_0, mixBuffer_2, noBuffer); // SetShapeFiltVolCommand parameters: // command, contextID, inputMixBuffer, outputMixBuffer SetShapeFiltVolCommand(&cmd[7], FLTVOLcontext_0, mixBuffer_2, mixBuffer_3 ); // SetShapeEqCompCommand parameters: // command, contextID, inputMixBuffer, sidechainMixBuffer, outputMixBuffer SetShapeEqCompCommand( &cmd[8], EQcontext0, mixBuffer_3, noBuffer, mixBuffer_4); // SetShapeFiltVolCommand parameters: // command, contextID, inputMixBuffer, outputMixBuffer SetShapeFiltVolCommand(&cmd[9], FLTVOLcontext_1, mixBuffer_4, mixBuffer_5 ); SetShapeFiltVolCommand(&cmd[10], FLTVOLcontext_2, mixBuffer_4, mixBuffer_6 ); SetShapeFiltVolCommand(&cmd[11], FLTVOLcontext_3, mixBuffer_4, mixBuffer_1 ); // // Mix buffers for voice B. // // SetShapeAllocMixBufferCommand parameters: // command, virtualID, numIn, nmmOut, attenuation SetShapeAllocMixBufferCommand(&cmd[12], mixBuffer_7, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[13], mixBuffer_8, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[14], mixBuffer_9, 1, 3, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[15], mixBuffer_10, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[16], mixBuffer_11, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); // // Voice B. // // SetShapeSrcXmaCommand parameters: // command, contextID, XMAContextID, leftorMonoMixBuffer, rightMixBuffer SetShapeSrcXmaCommand( &cmd[17], SRCcontext_1, XMAcontext_1, mixBuffer_7, noBuffer); // SetShapeFiltVolCommand parameters: // command, contextID, inputMixBuffer, outputMixBuffer SetShapeFiltVolCommand(&cmd[18], FLTVOLcontext_4, mixBuffer_7, mixBuffer_8 ); // SetShapeEqCompCommand parameters: // command, contextID, inputMixBuffer, sidechainMixBuffer, outputMixBuffer SetShapeEqCompCommand( &cmd[19], EQcontext1, mixBuffer_8, noBuffer, mixBuffer_9); // SetShapeFiltVolCommand parameters: // command, contextID, inputMixBuffer, outputMixBuffer SetShapeFiltVolCommand(&cmd[20], FLTVOLcontext_5, mixBuffer_9, mixBuffer_10 ); SetShapeFiltVolCommand(&cmd[21], FLTVOLcontext_6, mixBuffer_9, mixBuffer_11 ); SetShapeFiltVolCommand(&cmd[22], FLTVOLcontext_7, mixBuffer_9, mixBuffer_1 ); // // DMA all outputs. // // SetShapeDmaCommand parameters: // command, contextID, mixBuffer, write SetShapeDmaCommand( &cmd[23], DMAcontext_0, mixBuffer_1, true); SetShapeDmaCommand( &cmd[24], DMAcontext_1, mixBuffer_5, true); SetShapeDmaCommand( &cmd[25], DMAcontext_2, mixBuffer_6, true); SetShapeDmaCommand( &cmd[26], DMAcontext_3, mixBuffer_10, true); SetShapeDmaCommand( &cmd[27], DMAcontext_4, mixBuffer_11, true); ``` #### Frontal d'un moteur audio logiciel **Figure 2. Un frontal de base pour un moteur logiciel. Potentiellement, toutes les voix qui utilisent ce modèle utiliseraient la même structure.** Un frontal de base pour un moteur audio logiciel Dans le code, ce graphe de flux peut être représenté comme suit. ```cpp theme={null} typedef enum mixBuffers { noBuffer = 0, mixBuffer_1 = 1, mixBuffer_2 = 2, mixBuffer_3 = 3 }; typedef enum DMAcontexts { DMAcontext_0 = 0, }; typedef enum FLTVOLcontexts { FLTVOLcontext_0 = 0, }; typedef enum EQcontexts { EQcontext_0 = 0, }; typedef enum SRCcontexts { SRCcontext_0 = 0, }; typedef enum XMAcontexts { XMAcontext_0 = 0, }; // // Command structure to be initialized. // #define nSHAPE_frontend_commands 7 // SHAPE_FLOWGRAPH_COMMAND cmd[nSHAPE_frontend_commands]; // // Mix buffer allocation for the voice. // // SetShapeAllocMixBufferCommand parameters: // command, virtualID, numIn, numOut, attenuation SetShapeAllocMixBufferCommand(&cmd[0], mixBuffer_1, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[1], mixBuffer_2, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[2], mixBuffer_3, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); // // SHAPE blocks. // // SetShapeSrcXmaCommand parameters: // command, contextID, XMAContextID, leftorMonoMixBuffer, rightMixBuffer SetShapeSrcXmaCommand( &cmd[3], SRCcontext_0, XMAcontext_0, mixBuffer_1, noBuffer); // SetShapeEqCompCommand parameters: // command, contextID, inputMixBuffer, sidechainMixBuffer, outputMixBuffer SetShapeEqCompCommand( &cmd[4], EQcontext_0, mixBuffer_1, noBuffer, mixBuffer_2); // SetShapeFiltVolCommand parameters: // command, contextID, inputMixBuffer, outputMixBuffer SetShapeFiltVolCommand(&cmd[5], FLTVOLcontext_0, mixBuffer_2, mixBuffer_3 ); // SetShapeDmaCommand parameters: // command, contextID, mixBuffer, write SetShapeDmaCommand( &cmd[6], DMAcontext_0, mixBuffer_3, true ); ``` #### Rendu audio Pour effectuer le rendu audio 1. Créez un graphe de flux semblable à ceux présentés dans les exemples précédents, qui définit le graphe audio à traiter. 2. Créez des structures de contexte qui définissent comment et quoi le graphe de flux traitera. 3. Utilisez la méthode [SubmitCommand](/fr-CA/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_submitcommand) pour soumettre le graphe de flux à l'ACP. Selon les paramètres de `SubmitCommand`, le graphe de flux est traité une seule fois puis abandonné, ou traité à chaque image audio. 4. Le titre est responsable de la mise à jour des données de contexte pour chaque image audio, soit à l'aide des commandes `ACP_COMMAND_UPDATE_*_CONTEXT`, soit en synchronisant correctement les mises à jour avec le traitement du graphe de flux et en mettant à jour manuellement les contextes. * [ACP\_COMMAND\_UPDATE\_DMA\_CONTEXT](/fr-CA/reference/audio/acphal/structs/acp_command_update_dma_context) * [ACP\_COMMAND\_UPDATE\_EQCOMP\_CONTEXT](/fr-CA/reference/audio/acphal/structs/acp_command_update_eqcomp_context) * [ACP\_COMMAND\_UPDATE\_FILTVOL\_CONTEXT](/fr-CA/reference/audio/acphal/structs/acp_command_update_filtvol_context) * [ACP\_COMMAND\_UPDATE\_PCM\_CONTEXT](/fr-CA/reference/audio/acphal/structs/acp_command_update_pcm_context) * [ACP\_COMMAND\_UPDATE\_SRC\_CONTEXT](/fr-CA/reference/audio/acphal/structs/acp_command_update_src_context) * [ACP\_COMMAND\_UPDATE\_XMA\_CONTEXT](/fr-CA/reference/audio/acphal/structs/acp_command_update_xma_context) Lorsque vous mettez à jour des contextes, notez qu'un paramètre d'indicateur de [SubmitCommand](/fr-CA/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_submitcommand) détermine si la mise à jour a lieu dès que possible ou à l'image audio suivante. Pour plus de détails sur la méthode de synchronisation manuelle de la mise à jour des contextes, reportez-vous à la commande [ACP\_COMMAND\_LOAD\_SHAPE\_FLOWGRAPH](/fr-CA/reference/audio/acphal/structs/acp_command_load_shape_flowgraph). En général, utilisez les commandes `ACP_COMMAND_TYPE_UPDATE_*_CONTEXT` pour mettre à jour un petit nombre de contextes par image audio. Utiliser ces commandes pour mettre à jour un grand nombre de contextes n'est pas efficace, car une grande quantité de données de contexte doit être copiée et transmise à l'ACP, en plus du traitement des commandes. Si vous voulez mettre à jour un grand nombre de contextes, un titre doit modifier les données de contexte, puis soumettre des graphes de flux non persistants à l'ACP, ou bien tirer parti de la commande `ACP_COMMAND_TYPE_START_FLOWGRAPH` et du paramètre `waitForStart` de la commande [ACP\_COMMAND\_LOAD\_SHAPE\_FLOWGRAPH](/fr-CA/reference/audio/acphal/structs/acp_command_load_shape_flowgraph) pour suspendre le traitement jusqu'à ce que le contexte soit mis à jour. Lorsque le traitement du graphe de flux est terminé, les contextes peuvent de nouveau être mis à jour. Une troisième solution de rechange pour mettre à jour les contextes consiste à utiliser un processus de double mise en mémoire tampon. Le titre peut mettre à jour la seconde copie des contextes pendant le traitement du graphe de flux, puis permuter les contextes au début d'une image audio. #### Analyse des graphes de flux L'ACP met fin à l'analyse des graphes de flux persistants à la fin de l'image audio, c'est-à-dire une image audio de l'ACP limitée à 2,667 ms. Si un titre a un graphe de flux dont le traitement prend 75 % d'une image audio, mais que le titre ne laisse pas le traitement commencer avant que 30 % de l'image audio se soit écoulée, les portions du graphe de flux qui n'ont pas été analysées sont purgées. Le graphe de flux lui-même n'est pas modifié. Lorsque cela se produit, l'ACP envoie le message `ACP_MESSAGE_TYPE_FLOWGRAPH_TERMINATED` si le titre s'est inscrit pour recevoir des messages. Pour déterminer quelles commandes n'ont pas été insérées dans les files d'attente SHAPE internes, le titre examine l'indicateur `queued` de la commande de graphe de flux. Les graphes de flux non persistants sont habituellement traités jusqu'au bout, peu importe le moment de leur soumission. L'une des exceptions est le blocage d'une ou de plusieurs commandes en raison de la non-disponibilité des données sources ou d'une mauvaise utilisation de l'indicateur `disabled`. Un titre peut soumettre un graphe de flux non persistant à n'importe quel moment pendant une image audio de l'ACP et être certain (sauf dans quelques cas limites) qu'il sera traité jusqu'au bout. L'avantage est qu'un titre n'a pas besoin d'être parfaitement synchrone avec l'horloge audio, tant qu'il continue de traiter les graphes de flux dans l'intervalle d'image audio de l'ACP de 2,667 ms. Le risque est qu'un titre peut provoquer des coupures audio s'il ne soumet pas ses graphes de flux de façon régulière ou si les graphes de flux nécessitent plus de 2,667 ms. Voici un résumé de la durée de vie des graphes de flux. * Un graphe de flux persistant reste actif sur l'ACP jusqu'à ce qu'il soit remplacé par la soumission d'un nouveau graphe de flux ou d'un graphe de flux nul, ce qui le retire effectivement. * L'ACP commence à traiter un graphe de flux persistant au début d'une image audio, sauf si le client indique à l'ACP d'attendre une commande de démarrage. * L'ACP cesse de traiter un graphe de flux persistant peu avant la fin de l'image audio, même s'il n'a pas été entièrement traité. * Un graphe de flux non persistant n'est actif que jusqu'à ce qu'il soit terminé, puis il est retiré. * Un graphe de flux non persistant reste actif d'une image audio à l'autre. Il n'est retiré qu'une fois terminé. Le traitement des commandes n'est pas lié à l'analyse des graphes de flux. L'ACP recherche constamment de nouvelles commandes, puis les traite le plus rapidement possible pendant qu'il analyse un graphe de flux ou effectue d'autres tâches. #### Mise à jour des graphes de flux Les options de mise à jour des graphes de flux sont semblables à celles de la mise à jour des contextes décrites précédemment. La règle de base est la même : ne mettez pas à jour les graphes de flux pendant leur traitement. Vous pouvez utiliser trois stratégies pour mettre à jour les graphes de flux. 1. Utilisez des graphes de flux non persistants, reconstruisez-les au besoin et soumettez-les au début de l'image audio. Un titre peut réutiliser le même graphe de flux autant de fois que nécessaire. Si le graphe de flux ne change pas, le titre n'a pas besoin de le reconstruire. Vous pouvez aussi appliquer la double mise en mémoire tampon à cette approche en construisant un nouveau graphe de flux pendant le traitement de l'ancien. Lors de la reconstruction, non seulement les graphes de flux peuvent être construits à partir de zéro, mais leurs sections peuvent aussi être stockées et liées au besoin en définissant de façon appropriée les ID des tampons de mixage. 2. Utilisez des graphes de flux persistants et reconstruisez-les et remplacez-les seulement lorsque des changements sont nécessaires. La double mise en mémoire tampon fonctionne ici aussi. On peut laisser l'ACP fonctionner librement en n'utilisant pas le paramètre `waitForStart` de [ACP\_COMMAND\_LOAD\_SHAPE\_FLOWGRAPH](/fr-CA/reference/audio/acphal/structs/acp_command_load_shape_flowgraph). L'ACP commence à traiter le graphe de flux dès le début de l'image audio, juste après le traitement des commandes marquées pour cette image audio. Sinon, le paramètre `waitForStart` peut être défini pour empêcher le traitement du graphe de flux jusqu'à l'envoi de la commande `ACP_COMMAND_TYPE_START_FLOWGRAPH`. Cela n'a pas d'incidence directe sur les mises à jour des graphes de flux, mais permet une légère amélioration de la synchronisation. 3. Utilisez l'indicateur `disabled` des commandes de graphe de flux pour désactiver des portions d'un graphe de flux. Par exemple, un graphe de flux maître peut être construit, mais seules les sections requises sont activées pour chaque exécution. Cette méthode doit être combinée à l'option 1 ou 2 pour transmettre le nouveau graphe de flux à l'ACP. Notez que l'ACP ne parcourt pas actuellement le graphe de flux pour rechercher les blocs orphelins. Un titre doit désactiver des chemins complets dans le graphe de flux (pas seulement les premiers nœuds). Sinon, les commandes SHAPE bloquent temporairement le matériel. Ces blocages peuvent être simples, comme un seul bloc qui ne peut pas être traité et qui est retiré à faible coût. Ils peuvent aussi être assez graves pour bloquer une voix entière. Utilisez la technique de double mise en mémoire tampon pour un titre qui a un grand nombre de voix ou qui effectue de nombreuses mises à jour par image audio. Si un titre utilise `ACP_MESSAGE_TYPE_FLOWGRAPH_COMPLETED` pour gérer les mises à jour, l'ACP peut rester inactif pendant une période prolongée entre le moment où l'ACP ajoute le message à la file d'attente des messages et celui où le titre appelle `PopMessage`. N'utilisez pas cette approche pour gérer les mises à jour : gardez l'ACP actif. #### Graphes de flux multiples Un titre peut traiter plusieurs graphes de flux par image audio si leurs exigences combinées ne dépassent pas les capacités du matériel. L'avantage est qu'un titre peut exécuter plusieurs moteurs audio, intergiciels comme personnalisés, ou diviser leur analyse en morceaux plus faciles à gérer. L'inconvénient est que le matériel SHAPE ne fonctionne pas aussi efficacement dans ce mode. Pour atteindre le débit maximal de SHAPE, chaque bloc SHAPE doit être occupé à 100 %, ce qui est impossible lorsque plusieurs graphes de flux sont traités. Un seul graphe de flux peut être chargé par client ACP. Si un client soumet un nouveau graphe de flux, celui-ci remplace le graphe existant. Un titre qui doit prendre en charge plusieurs graphes de flux doit soit avoir des clients distincts pour chaque type de graphe de flux (chaque client ayant ses propres files d'attente de commandes et de messages), soit attendre qu'un graphe de flux soit terminé avant d'en soumettre un nouveau. La prise en charge de plusieurs graphes de flux est conçue pour être utilisée par plusieurs clients, et non par un seul client. Cela permet à un moteur intergiciel de soumettre son graphe de flux et au titre de soumettre un graphe de flux distinct pour un traitement personnalisé supplémentaire. Pour chaque client ACP requis par le titre, créez une instance de l'interface `IACPHAL`. Comme toutes les ressources de l'ACP et de SHAPE sont partagées entre tous les clients (en particulier les tableaux de contextes), les clients doivent coordonner l'allocation et le partage de ces ressources. ### Utilitaires DMA Incluez les utilitaires d'accès direct à la mémoire (DMA) du fichier *ShapeDMAContext.h*. Les utilitaires suivants agissent sur une structure [SHAPE\_DMA\_CONTEXT](/fr-CA/reference/audio/shapedmacontext/structs/shape_dma_context). Pour plus de renseignements, consultez [ShapeDmaContext (méthodes utilitaires DMA)](/fr-CA/reference/audio/shapedmacontext/shapedmacontext_members). ### Utilitaires de compresseur EQ Incluez les utilitaires EQCOMP du fichier *ShapeEqCompContext.h*. Ces utilitaires agissent sur une structure [SHAPE\_EQCOMP\_CONTEXT](/fr-CA/reference/audio/shapeeqcompcontext/structs/shape_eqcomp_context). Pour plus de renseignements, consultez [ShapeEqCompContext (méthodes utilitaires EQCOMP)](/fr-CA/reference/audio/shapeeqcompcontext/shapeeqcompcontext_members). ### Utilitaires de filtre de volume Incluez les utilitaires de filtre de volume du fichier *ShapeFiltVolContext.h*. Ces utilitaires agissent sur une structure [SHAPE\_FILTVOL\_CONTEXT](/fr-CA/reference/audio/shapefiltvolcontext/structs/shape_filtvol_context). Pour plus de renseignements, consultez [ShapeFiltVolContext (méthodes utilitaires FLTVOL)](/fr-CA/reference/audio/shapefiltvolcontext/shapefiltvolcontext_members). ### Utilitaires PCM Incluez les utilitaires de modulation par impulsions codées (PCM) du fichier *ShapePCMContext.h*. Ces utilitaires agissent sur une structure [SHAPE\_PCM\_CONTEXT](/fr-CA/reference/audio/shapepcmcontext/structs/shape_pcm_context). Pour plus de renseignements, consultez [ShapePcmContext (méthodes utilitaires PCM)](/fr-CA/reference/audio/shapepcmcontext/shapepcmcontext_members). ### Utilitaires SRC Incluez les utilitaires de convertisseur de fréquence d'échantillonnage (SRC) du fichier *ShapeSRCContext.h*. Ces utilitaires agissent sur une structure [SHAPE\_SRC\_CONTEXT](/fr-CA/reference/audio/shapesrccontext/structs/shape_src_context). Pour plus de renseignements, consultez [ShapeSrcContext (méthodes utilitaires SRC)](/fr-CA/reference/audio/shapesrccontext/shapesrccontext_members). ### Utilitaires XMA Incluez les utilitaires XMA du fichier *ShapeXMAContext.h*. Ces utilitaires agissent sur une structure [SHAPE\_XMA\_CONTEXT](/fr-CA/reference/audio/shapexmacontext/structs/shape_xma_context). Pour plus de renseignements, consultez [ShapeXmaContext (méthodes utilitaires XMA)](/fr-CA/reference/audio/shapexmacontext/shapexmacontext_members). Les capacités de décodage XMA de l'émulation matérielle sont limitées. Pour plus de détails, consultez la rubrique sur la structure [SHAPE\_XMA\_CONTEXT](/fr-CA/reference/audio/shapexmacontext/structs/shape_xma_context). Un titre peut utiliser des données XMA sans utiliser de graphes de flux, mais les données doivent tout de même passer par l'ACP à l'aide des commandes [ACP\_COMMAND\_TYPE](/fr-CA/reference/audio/acphal/enums/acp_command_type) présentées dans le tableau suivant. | Commande | Description | | - | - | | `ACP_COMMAND_TYPE_ENABLE_XMA_CONTEXT` | Active un seul contexte XMA, et l'ACP commence à décoder le tampon spécifié dans le contexte. | | `ACP_COMMAND_TYPE_ENABLE_XMA_CONTEXTS` | Active un bloc de contextes XMA, et l'ACP commence à décoder les tampons définis dans les contextes. | | `ACP_COMMAND_TYPE_DISABLE_XMA_CONTEXT` | Désactive un seul contexte XMA, et l'ACP cesse de décoder le tampon spécifié dans le contexte. | | `ACP_COMMAND_TYPE_DISABLE_XMA_CONTEXTS` | Désactive un bloc de contextes XMA, et l'ACP cesse de décoder les tampons définis dans les contextes. | | `ACP_COMMAND_TYPE_UPDATE_XMA_CONTEXT` | Met à jour un ou plusieurs champs du contexte XMA. Cela peut se faire de façon synchrone, sur l'ACP, ou de façon asynchrone. | À l'aide de ces commandes, un titre peut utiliser l'ACP HAL de la XBOX One de façon presque identique à la façon dont il utilise le XMA HAL de la XBOX 360, selon l'ordre d'opérations suivant. 1. Remplissez le ou les contextes avec les données pertinentes : tampons, décalages, etc. 2. Activez les contextes. 3. Mettez à jour les contextes. Si le contexte est désactivé, le titre peut en modifier directement le contenu. Si le contexte est activé, le titre peut d'abord le désactiver ou utiliser la commande `ACP_COMMAND_TYPE_UPDATE_XMA_CONTEXT`, ce qui peut être plus efficace, car l'ACP se charge de la désactivation, de l'attente et de la mise à jour. En général, un titre ne devrait pas utiliser uniquement le composant XMA de SHAPE. Il est presque trivial de créer un graphe de flux « frontal » qui ne nécessite qu'un entretien mineur et qui offre au titre un SRC gratuit de haute qualité, ainsi que d'autres fonctionnalités. Les graphes de flux sont faciles à créer et à gérer, et ils déchargent le CPU principal du SRC tout en améliorant la qualité. ### Valeurs cibles Les valeurs cibles qui peuvent être définies dans les fonctions utilitaires représentent les valeurs finales du paramètre à la fin de l'image audio. Par exemple, la structure [SHAPE\_FILTVOL\_CONTEXT](/fr-CA/reference/audio/shapefiltvolcontext/structs/shape_filtvol_context) contient des valeurs pour `gain` et `gainTarget`. Pendant le traitement de l'image, le `gain` est calculé par interpolation linéaire à l'aide de l'équation suivante. ```cpp theme={null} gain = ((gainTarget - gain) / 127) * i + gain ``` Où i va de 0 à 127. À la fin de l'image, `gain` sera égal à `gainTarget`. Les paramètres cibles peuvent être définis pour l'ACP comme le montre le tableau suivant. | Composant | Cible | Description | | - | - | - | | EQCOMP | `eqAB0Target` | Cible du coefficient b0 de l'EQ A | | EQCOMP | `eqAB1Target_L` | Cible du coefficient b1 de l'EQ A, 8 bits de poids faible | | EQCOMP | `eqAB1Target_H` | Cible du coefficient b1 de l'EQ A, 16 bits de poids fort | | EQCOMP | `eqAB2Target_L` | Cible du coefficient b2 de l'EQ A, 16 bits de poids faible | | EQCOMP | `eqAB2Target_H` | Cible du coefficient b2 de l'EQ A, 8 bits de poids fort | | EQCOMP | `eqAA1Target` | Cible du coefficient a1 de l'EQ A | | EQCOMP | `eqAA2Target` | Cible du coefficient a2 de l'EQ A | | EQCOMP | `eqBB0Target_L` | Cible du coefficient b0 de l'EQ B, 8 bits de poids faible | | EQCOMP | `eqBB0Target_H` | Cible du coefficient b0 de l'EQ B, 16 bits de poids fort | | EQCOMP | `eqBB1Target_L` | Cible du coefficient b1 de l'EQ B, 16 bits de poids faible | | EQCOMP | `eqBB1Target_H` | Cible du coefficient b1 de l'EQ B, 8 bits de poids fort | | EQCOMP | `eqBB2Target` | Cible du coefficient b2 de l'EQ B | | EQCOMP | `eqBA1Target` | Cible du coefficient a1 de l'EQ B | | EQCOMP | `eqBA2Target_L` | Cible du coefficient a2 de l'EQ B, 8 bits de poids faible | | EQCOMP | `eqBA2Target_H` | Cible du coefficient a2 de l'EQ B, 16 bits de poids fort | | EQCOMP | `eqCB0Target_L` | Cible du coefficient b0 de l'EQ C, 16 bits de poids faible | | EQCOMP | `eqCB0Target_H` | Cible du coefficient b0 de l'EQ C, 8 bits de poids fort | | EQCOMP | `eqCB1Target` | Cible du coefficient b1 de l'EQ C | | EQCOMP | `eqCB2Target` | Cible du coefficient b2 de l'EQ C | | EQCOMP | `eqCA1Target_L` | Cible du coefficient a1 de l'EQ C, 8 bits de poids faible | | EQCOMP | `eqCA1Target_H` | Cible du coefficient a1 de l'EQ C, 16 bits de poids fort | | EQCOMP | `eqCA2Target_L` | Cible du coefficient a2 de l'EQ C, 16 bits de poids faible | | EQCOMP | `eqCA2Target_H` | Cible du coefficient a2 de l'EQ C, 8 bits de poids fort | | EQCOMP | `compGainTarget` | Cible du gain de sortie définissable par l'utilisateur | | FILTVOL | `gainTarget` | Niveau cible du volume | | FILTVOL | `qRecipTarget` | Valeur cible de 1 sur Q | | FILTVOL | `fcTarget` | Valeur cible de la fréquence | | SRC | `samplingIncrementTarget` | Valeur finale de l'incrément d'échantillonnage | ### Sécurité des threads Les [méthodes de l'interface IACPHAL](/fr-CA/reference/audio/acphal/interfaces/IAcpHal/iacphal) et les [méthodes ACPHAL](/fr-CA/reference/audio/acphal/acphal_members) sont thread-safe. Si l'appel [ApuCreateHeap](/fr-CA/reference/audio/apu/functions/apucreateheap) est effectué, le tas est utilisé par tous les threads. Les fonctions utilitaires suivantes ne sont *pas* thread-safe. Toutefois, leur code source est fourni. Au besoin, vous pouvez les rendre thread-safe. La façon habituelle de le faire est d'utiliser des [objets de section critique](https://msdn.microsoft.com/library/windows/desktop/ms682530\(v=vs.85\).aspx). * [ShapeFlowGraph (graphe de flux)](/fr-CA/reference/audio/shapeflowgraph/shapeflowgraph_members) * [ShapeDmaContext (DMA)](/fr-CA/reference/audio/shapedmacontext/shapedmacontext_members) * [ShapeEqCompContext (EQCOMP)](/fr-CA/reference/audio/shapeeqcompcontext/shapeeqcompcontext_members) * [ShapeFiltVolContext (FLTVOL)](/fr-CA/reference/audio/shapefiltvolcontext/shapefiltvolcontext_members) * [ShapePcmContext (PCM)](/fr-CA/reference/audio/shapepcmcontext/shapepcmcontext_members) * [ShapeSrcContext (SRC)](/fr-CA/reference/audio/shapesrccontext/shapesrccontext_members) * [ShapeXmaContext (XMA)](/fr-CA/reference/audio/shapexmacontext/shapexmacontext_members) ### Lignes directrices pour l'utilisation du SRC avec les données PCM et XMA Le tableau suivant présente les lignes directrices pour l'utilisation du bloc SRC avec les données PCM et XMA. | Cible | Implémentation | | - | - | | PCM linéaire sans boucle | Démarrez la voix à l'aide de `SHAPE_SRC_COMMAND_TYPE_START` pour le SRC. Laissez la voix jouer jusqu'à la fin. Vous pouvez aussi l'arrêter avant la fin à l'aide de `SHAPE_SRC_COMMAND_TYPE_STOP_IMMEDIATE`. | | PCM linéaire en boucle infinie | Définissez le nombre de boucles du contexte PCM (`loopCount`) à `SHAPE_PCM_INFINITE_LOOP_COUNT`. Démarrez la voix à l'aide de `SHAPE_SRC_COMMAND_TYPE_START` pour le SRC. Zéro. Laissez la voix jouer jusqu'à ce que vous vouliez l'arrêter à la fin d'une boucle en émettant `SHAPE_SRC_COMMAND_TYPE_STOP_END`, puis laissez la voix jouer jusqu'au bout. Vous pouvez aussi l'arrêter immédiatement en émettant `SHAPE_SRC_COMMAND_TYPE_STOP_IMMEDIATE`. | | PCM linéaire en boucle finie | Définissez le nombre de boucles du contexte PCM (`loopCount`) à \[0, 254]. Démarrez la voix à l'aide de `SHAPE_SRC_COMMAND_TYPE_START` pour le SRC. Laissez la voix jouer jusqu'à la fin. Vous pouvez aussi l'arrêter à la fin d'une boucle à l'aide de `SHAPE_SRC_COMMAND_TYPE_STOP_END` et laisser la voix jouer jusqu'au bout. Vous pouvez aussi l'arrêter immédiatement en émettant `SHAPE_SRC_COMMAND_TYPE_STOP_IMMEDIATE`. | | PCM circulaire | Démarrez la voix à l'aide de `SHAPE_SRC_COMMAND_TYPE_START` pour le SRC. Continuez à diffuser des données en continu et à mettre à jour le pointeur d'écriture du contexte PCM jusqu'à ce que vous vouliez arrêter. Émettez `SHAPE_SRC_COMMAND_TYPE_STOP_END` pour laisser le SRC jouer jusqu'au pointeur d'écriture PCM actuel (`loopStartWritePointer`). Vous pouvez aussi émettre `SHAPE_SRC_COMMAND_TYPE_STOP_IMMEDIATE` pour arrêter immédiatement. | | XMA en diffusion continue (sans boucle matérielle) | Démarrez la voix à l'aide de `SHAPE_SRC_COMMAND_TYPE_START` pour le SRC. Lorsque le dernier tampon d'entrée XMA est consommé, émettez `SHAPE_SRC_COMMAND_TYPE_STOP_END` pour jouer jusqu'à la fin du tampon décodé (consultez la REMARQUE qui suit). Vous pouvez aussi émettre `SHAPE_SRC_COMMAND_TYPE_STOP_IMMEDIATE` pour arrêter immédiatement. | | XMA en boucle matérielle infinie | Définissez le nombre de boucles du contexte XMA (`numLoops`) à `SHAPE_XMA_INFINITE_LOOP_COUNT`. Démarrez la voix à l'aide de `SHAPE_SRC_COMMAND_TYPE_START` pour le SRC. Laissez la voix jouer jusqu'à ce que vous vouliez l'arrêter à la fin d'une boucle en définissant le nombre de boucles XMA à zéro et en émettant `SHAPE_SRC_COMMAND_TYPE_STOP_END`, puis laissez la voix jouer jusqu'au bout. Vous pouvez aussi arrêter immédiatement en émettant `SHAPE_SRC_COMMAND_TYPE_STOP_IMMEDIATE`. | | XMA en boucle matérielle finie | Définissez le nombre de boucles du contexte XMA (`numLoops`) à \[0, 254]. Démarrez la voix à l'aide de `SHAPE_SRC_COMMAND_TYPE_START` pour le SRC. Laissez la voix jouer jusqu'à ce que vous vouliez l'arrêter à la fin des boucles en surveillant le nombre de boucles. Lorsqu'il atteint zéro, émettez `SHAPE_SRC_COMMAND_TYPE_STOP_END` et laissez la voix jouer jusqu'au bout. Pour arrêter à la fin de la boucle suivante, vous pouvez aussi définir le nombre de boucles à zéro. Lorsque le dernier tampon d'entrée XMA est consommé, définissez la commande SRC à `SHAPE_SRC_COMMAND_TYPE_STOP_END` et laissez la voix jouer jusqu'au bout (consultez la REMARQUE qui suit). Pour arrêter immédiatement, émettez `SHAPE_SRC_COMMAND_TYPE_STOP_IMMEDIATE`. | Lorsque l'un de ces scénarios est terminé, la commande SRC est `SHAPE_SRC_COMMAND_TYPE_STOP_IMMEDIATE`. Vérifiez les bits de validité du tampon d'entrée XMA à la même fréquence que celle utilisée pour traiter les graphes de flux SHAPE. Si vous effectuez cette vérification dans le cadre de votre logique de diffusion en continu, qui s'exécute à des intervalles beaucoup plus longs, il est possible que le tampon de sortie XMA se vide avant que vous indiquiez au SRC de s'arrêter à la fin. Cela peut bloquer le graphe de flux. ### Suspension et reprise d'un titre Un titre doit pouvoir être suspendu et repris, par exemple lorsque l'utilisateur le met en mode limité (Constrained). Pour suspendre et reprendre lorsque vous programmez directement le matériel SHAPE à l'aide de `IAcpHal`, il suffit que le titre cesse de soumettre des commandes. Les commandes déjà soumises se terminent normalement et peuvent remplir la file d'attente des messages. Si un titre utilise des graphes de flux persistants, il doit charger un graphe de flux nul pour arrêter le traitement. Cela diffère du processus de suspension et de reprise lorsque vous programmez à l'aide de `XAudio2`. Pour plus de renseignements, consultez la [vue d'ensemble de XAudio2](/fr-CA/build/console-features/audio/overviews/xaudio2-overview). ## Documentation de référence de l'API * [Acphal (contenu de l'API)](/fr-CA/reference/audio/acphal/acphal_members) * Structures * [ACP\_COMMAND\_UPDATE\_DMA\_CONTEXT](/fr-CA/reference/audio/acphal/structs/acp_command_update_dma_context) * [ACP\_COMMAND\_UPDATE\_EQCOMP\_CONTEXT](/fr-CA/reference/audio/acphal/structs/acp_command_update_eqcomp_context) * [ACP\_COMMAND\_UPDATE\_FILTVOL\_CONTEXT](/fr-CA/reference/audio/acphal/structs/acp_command_update_filtvol_context) * [ACP\_COMMAND\_UPDATE\_PCM\_CONTEXT](/fr-CA/reference/audio/acphal/structs/acp_command_update_pcm_context) * [ACP\_COMMAND\_UPDATE\_SRC\_CONTEXT](/fr-CA/reference/audio/acphal/structs/acp_command_update_src_context) * [ACP\_COMMAND\_UPDATE\_XMA\_CONTEXT](/fr-CA/reference/audio/acphal/structs/acp_command_update_xma_context) * [ACP\_COMMAND\_LOAD\_SHAPE\_FLOWGRAPH](/fr-CA/reference/audio/acphal/structs/acp_command_load_shape_flowgraph) * [Shapedmacontext (contenu de l'API)](/fr-CA/reference/audio/shapedmacontext/shapedmacontext_members) * Structures * [SHAPE\_DMA\_CONTEXT](/fr-CA/reference/audio/shapedmacontext/structs/shape_dma_context) * [Shapeeqcompcontext (contenu de l'API)](/fr-CA/reference/audio/shapeeqcompcontext/shapeeqcompcontext_members) * Structures * [SHAPE\_EQCOMP\_CONTEXT](/fr-CA/reference/audio/shapeeqcompcontext/structs/shape_eqcomp_context) * [Shapefiltvolcontext (contenu de l'API)](/fr-CA/reference/audio/shapefiltvolcontext/shapefiltvolcontext_members) * Structures * [SHAPE\_FILTVOL\_CONTEXT](/fr-CA/reference/audio/shapefiltvolcontext/structs/shape_filtvol_context) * [Shapeflowgraph (contenu de l'API)](/fr-CA/reference/audio/shapeflowgraph/shapeflowgraph_members) * [Shapepcmcontext (contenu de l'API)](/fr-CA/reference/audio/shapepcmcontext/shapepcmcontext_members) * Structures * [SHAPE\_PCM\_CONTEXT](/fr-CA/reference/audio/shapepcmcontext/structs/shape_pcm_context) * [Shapesrccontext (contenu de l'API)](/fr-CA/reference/audio/shapesrccontext/shapesrccontext_members) * Structures * [SHAPE\_SRC\_CONTEXT](/fr-CA/reference/audio/shapesrccontext/structs/shape_src_context) * [Shapexmacontext (contenu de l'API)](/fr-CA/reference/audio/shapexmacontext/shapexmacontext_members) * Structures * [SHAPE\_XMA\_CONTEXT](/fr-CA/reference/audio/shapexmacontext/structs/shape_xma_context) * [apu (contenu de l'API)](/fr-CA/reference/audio/apu/apu_members) * Fonctions * [ApuCreateHeap](/fr-CA/reference/audio/apu/functions/apucreateheap) ## Related topics - [Vue d'ensemble de XBOX Series X|S](/fr/paths/series-xs/overview.md) - [Vue d'ensemble de l'accessibilité GDK](/fr/build/game-principles/accessibility/accessibility-overview.md) - [Vue d'ensemble de Windows & ROG XBOX Ally](/fr/paths/windows/overview.md) - [Vue d'ensemble de Godot et des moteurs communautaires](/fr/paths/community-engines/overview.md) - [Vue d'ensemble de Play Anywhere (console + PC)](/fr/paths/play-anywhere/overview.md)