> ## 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 flowgraphs audio SHAPE sur les consoles XBOX One. Cette rubrique fournit des descriptions et des exemples des flowgraphs utilisés pour piloter 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) inclut é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 flowgraph dans votre application pour acheminer les données audio *à travers* les blocs SHAPE. L'ACP gère les blocs SHAPE et en garantit l'efficacité. Pour plus de détails sur l'ensemble d'API, y compris les structures et énumérations déclarées dans les fichiers d'utilitaires, consultez la référence [AcpHal](/fr/reference/audio/acphal/acphal_members). Pour plus de détails sur l'architecture SHAPE, consultez la [vue d'ensemble de SHAPE](/fr/build/console-features/audio/overviews/shape-overview). Dans les fichiers sources d'un projet de titre, veillez à inclure le fichier *ShapeContext.h*, et non les fichiers d'en-tête de contexte individuels. Dans cette rubrique : * [Flowgraphs](#ID4EVB) * [Utilitaires DMA](#ID4EZH) * [Utilitaires du 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) * [Recommandations pour l'utilisation du SRC avec des données PCM et XMA](#ID4EUPAC) * [Mise en pause et reprise d'un titre](#ID4E5BAE) ### Flowgraphs Pour utiliser SHAPE, un titre crée généralement un flowgraph SHAPE. Pour une description d'une autre solution, consultez la section [Utilitaires XMA](#ID4EACAC). Un flowgraph SHAPE est un tableau de commandes (une par bloc SHAPE) accompagné de données de contexte qui décrivent l'ordre des opérations des différents blocs et les données sur lesquelles ils opèrent. L'ACP utilise les données du flowgraph pour planifier correctement les opérations au sein des blocs SHAPE. Le titre est chargé de construire le flowgraph et de le soumettre à l'ACP. Pour construire un flowgraph, utilisez [ShapeFlowGraph (méthodes utilitaires de flowgraph)](/fr/reference/audio/shapeflowgraph/shapeflowgraph_members). Dans les figures suivantes, les blocs verts représentent les composants SHAPE, les blocs cyan correspondent au matériau 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 flowgraphs](#ID4EHF) * [Mise à jour des flowgraphs](#ID4EHG) * [Flowgraphs multiples](#ID4ELH) #### Sons 3D **Figure 1. Deux voix, chacune panoramiquée entre deux sorties, avec un envoi vers une sortie commune.** Flowgraph de deux voix Dans le code, ce flowgraph 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 flowgraph 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 flowgraph 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 flowgraph va traiter. 3. Utilisez la méthode [SubmitCommand](/fr/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_submitcommand) pour soumettre le flowgraph à l'ACP. Selon les paramètres de `SubmitCommand`, le flowgraph est traité une seule fois puis supprimé, ou traité à chaque trame audio. 4. Le titre est chargé de mettre à jour les données de contexte pour chaque trame audio à l'aide des commandes `ACP_COMMAND_UPDATE_*_CONTEXT`, ou en synchronisant correctement les mises à jour avec le traitement du flowgraph et en mettant à jour manuellement les contextes. * [ACP\_COMMAND\_UPDATE\_DMA\_CONTEXT](/fr/reference/audio/acphal/structs/acp_command_update_dma_context) * [ACP\_COMMAND\_UPDATE\_EQCOMP\_CONTEXT](/fr/reference/audio/acphal/structs/acp_command_update_eqcomp_context) * [ACP\_COMMAND\_UPDATE\_FILTVOL\_CONTEXT](/fr/reference/audio/acphal/structs/acp_command_update_filtvol_context) * [ACP\_COMMAND\_UPDATE\_PCM\_CONTEXT](/fr/reference/audio/acphal/structs/acp_command_update_pcm_context) * [ACP\_COMMAND\_UPDATE\_SRC\_CONTEXT](/fr/reference/audio/acphal/structs/acp_command_update_src_context) * [ACP\_COMMAND\_UPDATE\_XMA\_CONTEXT](/fr/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/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_submitcommand) détermine si la mise à jour a lieu dès que possible ou à la trame 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/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 trame audio. L'utilisation de 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 souhaitez mettre à jour un grand nombre de contextes, un titre doit modifier les données de contexte puis soumettre des flowgraphs non persistants à l'ACP, ou tirer parti de la commande `ACP_COMMAND_TYPE_START_FLOWGRAPH` et du paramètre `waitForStart` de la commande [ACP\_COMMAND\_LOAD\_SHAPE\_FLOWGRAPH](/fr/reference/audio/acphal/structs/acp_command_load_shape_flowgraph) pour suspendre le traitement jusqu'à ce que le contexte soit mis à jour. Lorsque le flowgraph a terminé son traitement, les contextes peuvent de nouveau être mis à jour. Une troisième solution 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 flowgraph, puis permuter les contextes au début d'une trame audio. #### Analyse des flowgraphs L'ACP met fin à l'analyse des flowgraphs persistants à la fin de la trame audio, qui est une trame audio ACP limitée à 2,667 ms. Si un titre dispose d'un flowgraph dont le traitement occupe 75 % d'une trame audio, mais que le titre ne laisse le traitement démarrer qu'à 30 % de la trame audio, les parties du flowgraph qui n'ont pas été analysées sont purgées. Le flowgraph lui-même n'est pas modifié. Dans ce cas, l'ACP envoie le message `ACP_MESSAGE_TYPE_FLOWGRAPH_TERMINATED` si le titre s'est inscrit pour recevoir les messages. Pour déterminer quelles commandes n'ont pas été insérées dans les files d'attente SHAPE internes, le titre doit examiner l'indicateur `queued` de la commande de flowgraph. Les flowgraphs non persistants sont généralement traités jusqu'à leur terme, quel que soit le moment de leur soumission. L'une des exceptions est le blocage d'une ou plusieurs commandes en raison de l'indisponibilité des données sources ou d'une mauvaise utilisation de l'indicateur `disabled`. Un titre peut soumettre un flowgraph non persistant à tout moment au cours d'une trame audio ACP et avoir la certitude (à l'exception de quelques cas limites) qu'il sera terminé. 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 flowgraphs dans l'intervalle de trame audio ACP de 2,667 ms. Le risque est qu'un titre provoque des coupures audio s'il ne soumet pas ses flowgraphs de manière régulière ou si les flowgraphs nécessitent plus de 2,667 ms. Voici un résumé de la durée de vie des flowgraphs. * Un flowgraph persistant reste actif sur l'ACP jusqu'à ce qu'il soit remplacé par la soumission d'un nouveau flowgraph ou d'un flowgraph null, ce qui le supprime effectivement. * L'ACP commence à traiter un flowgraph persistant au début d'une trame audio, sauf si le client demande à l'ACP d'attendre une commande de démarrage. * L'ACP arrête de traiter un flowgraph persistant peu avant la fin de la trame audio, même s'il n'a pas été entièrement traité. * Un flowgraph non persistant n'est actif que jusqu'à ce qu'il soit terminé, puis il est supprimé. * Un flowgraph non persistant reste actif d'une trame audio à l'autre. Il n'est supprimé qu'une fois terminé. Le traitement des commandes n'est pas lié à l'analyse des flowgraphs. L'ACP recherche en permanence de nouvelles commandes et les traite aussi vite que possible pendant qu'il analyse un flowgraph ou effectue d'autres tâches. #### Mise à jour des flowgraphs Les options de mise à jour des flowgraphs sont semblables à celles de mise à jour des contextes décrites précédemment. La règle de base est la même : ne mettez pas à jour les flowgraphs pendant leur traitement. Vous pouvez utiliser trois stratégies pour mettre à jour les flowgraphs. 1. Utilisez des flowgraphs non persistants, reconstruisez-les si nécessaire et soumettez-les au début de la trame audio. Un titre peut réutiliser le même flowgraph autant de fois que nécessaire. Si le flowgraph ne change pas, le titre n'a pas besoin de le reconstruire. Vous pouvez également appliquer la double mise en mémoire tampon à cette approche en construisant un nouveau flowgraph pendant le traitement de l'ancien. Lors de leur reconstruction, les flowgraphs peuvent non seulement être construits de zéro, mais leurs sections peuvent aussi être stockées et liées selon les besoins en définissant de manière appropriée les ID des tampons de mixage. 2. Utilisez des flowgraphs persistants et ne les reconstruisez et remplacez que lorsque des modifications sont nécessaires. La double mise en mémoire tampon fonctionne ici aussi. L'ACP peut fonctionner librement si vous n'utilisez pas le paramètre `waitForStart` de [ACP\_COMMAND\_LOAD\_SHAPE\_FLOWGRAPH](/fr/reference/audio/acphal/structs/acp_command_load_shape_flowgraph). L'ACP commence à traiter le flowgraph dès le début de la trame audio, juste après le traitement des commandes associées à cette trame audio. Vous pouvez également définir le paramètre `waitForStart` pour empêcher le traitement du flowgraph jusqu'à l'envoi de la commande `ACP_COMMAND_TYPE_START_FLOWGRAPH`. Cela n'affecte pas directement les mises à jour des flowgraphs, mais permet une légère amélioration de la synchronisation. 3. Utilisez l'indicateur `disabled` des commandes de flowgraph pour désactiver des parties d'un flowgraph. Par exemple, un flowgraph maître peut être construit, mais seules les sections nécessaires sont activées à chaque exécution. Cette option doit être combinée avec l'option 1 ou 2 pour transmettre le nouveau flowgraph à l'ACP. Notez que l'ACP ne parcourt actuellement pas le flowgraph pour rechercher les blocs orphelins. Un titre doit désactiver des chemins complets dans le flowgraph (et pas seulement les premiers nœuds). Sinon, les commandes SHAPE bloquent temporairement le matériel. Ces blocages peuvent être simples, comme un bloc unique qui ne peut pas être traité et qui est supprimé à faible coût. Ils peuvent aussi être suffisamment graves pour bloquer une voix entière. Utilisez la technique de double mise en mémoire tampon pour un titre qui comporte un grand nombre de voix ou qui effectue de nombreuses mises à jour par trame 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 : maintenez l'ACP actif. #### Flowgraphs multiples Un titre peut traiter plusieurs flowgraphs par trame audio si leurs besoins combinés ne dépassent pas les capacités du matériel. L'avantage est qu'un titre peut exécuter plusieurs moteurs audio, middleware comme personnalisés, ou découper leur analyse en blocs 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 flowgraphs sont traités. Un seul flowgraph peut être chargé par client ACP. Si un client soumet un nouveau flowgraph, celui-ci remplace le flowgraph existant. Un titre qui doit prendre en charge plusieurs flowgraphs doit soit disposer de clients distincts pour chaque type de flowgraph (chaque client ayant ses propres files d'attente de commandes et de messages), soit attendre qu'un flowgraph soit terminé avant d'en soumettre un nouveau. La prise en charge de plusieurs flowgraphs est conçue pour être utilisée par plusieurs clients, et non par un seul. Cela permet à un moteur middleware de soumettre son flowgraph et au titre de soumettre un flowgraph 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 ACP et 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 Direct Memory Access (DMA) du fichier *ShapeDMAContext.h*. Les utilitaires suivants opèrent sur une structure [SHAPE\_DMA\_CONTEXT](/fr/reference/audio/shapedmacontext/structs/shape_dma_context). Pour plus d'informations, consultez [ShapeDmaContext (méthodes utilitaires DMA)](/fr/reference/audio/shapedmacontext/shapedmacontext_members). ### Utilitaires du compresseur EQ Incluez les utilitaires EQCOMP du fichier *ShapeEqCompContext.h*. Ces utilitaires opèrent sur une structure [SHAPE\_EQCOMP\_CONTEXT](/fr/reference/audio/shapeeqcompcontext/structs/shape_eqcomp_context). Pour plus d'informations, consultez [ShapeEqCompContext (méthodes utilitaires EQCOMP)](/fr/reference/audio/shapeeqcompcontext/shapeeqcompcontext_members). ### Utilitaires de filtre de volume Incluez les utilitaires de filtre de volume du fichier *ShapeFiltVolContext.h*. Ces utilitaires opèrent sur une structure [SHAPE\_FILTVOL\_CONTEXT](/fr/reference/audio/shapefiltvolcontext/structs/shape_filtvol_context). Pour plus d'informations, consultez [ShapeFiltVolContext (méthodes utilitaires FLTVOL)](/fr/reference/audio/shapefiltvolcontext/shapefiltvolcontext_members). ### Utilitaires PCM Incluez les utilitaires Pulse Code Modulation (PCM) du fichier *ShapePCMContext.h*. Ces utilitaires opèrent sur une structure [SHAPE\_PCM\_CONTEXT](/fr/reference/audio/shapepcmcontext/structs/shape_pcm_context). Pour plus d'informations, consultez [ShapePcmContext (méthodes utilitaires PCM)](/fr/reference/audio/shapepcmcontext/shapepcmcontext_members). ### Utilitaires SRC Incluez les utilitaires Sample Rate Convertor (SRC) du fichier *ShapeSRCContext.h*. Ces utilitaires opèrent sur une structure [SHAPE\_SRC\_CONTEXT](/fr/reference/audio/shapesrccontext/structs/shape_src_context). Pour plus d'informations, consultez [ShapeSrcContext (méthodes utilitaires SRC)](/fr/reference/audio/shapesrccontext/shapesrccontext_members). ### Utilitaires XMA Incluez les utilitaires XMA du fichier *ShapeXMAContext.h*. Ces utilitaires opèrent sur une structure [SHAPE\_XMA\_CONTEXT](/fr/reference/audio/shapexmacontext/structs/shape_xma_context). Pour plus d'informations, consultez [ShapeXmaContext (méthodes utilitaires XMA)](/fr/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/reference/audio/shapexmacontext/structs/shape_xma_context). Un titre peut utiliser des données XMA sans utiliser de flowgraphs, mais les données doivent toujours passer par l'ACP à l'aide des commandes [ACP\_COMMAND\_TYPE](/fr/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 arrête 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 arrête 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 être effectué de manière synchrone, sur l'ACP, ou de manière asynchrone. | À l'aide de ces commandes, un titre peut utiliser l'ACP HAL de la XBOX One de manière 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 doit pas utiliser uniquement le composant XMA de SHAPE. Il est presque trivial de créer un flowgraph « frontal » qui ne nécessite qu'une maintenance mineure et qui offre au titre un SRC gratuit et de haute qualité ainsi que d'autres fonctionnalités. Les flowgraphs sont faciles à créer et à gérer, et ils déchargent le processeur principal du SRC tout en améliorant la qualité. ### Valeurs cibles Les valeurs cibles pouvant être définies dans les fonctions utilitaires représentent les valeurs finales du paramètre à la fin de la trame audio. Par exemple, la structure [SHAPE\_FILTVOL\_CONTEXT](/fr/reference/audio/shapefiltvolcontext/structs/shape_filtvol_context) contient des valeurs pour `gain` et `gainTarget`. Pendant le traitement de la trame, 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 la trame, `gain` est égal à `gainTarget`. Les paramètres cibles peuvent être définis pour l'ACP comme indiqué dans 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/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/reference/audio/acphal/interfaces/IAcpHal/iacphal) et les [méthodes ACPHAL](/fr/reference/audio/acphal/acphal_members) sont thread-safe. Si l'appel [ApuCreateHeap](/fr/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. Si nécessaire, vous pouvez les rendre thread-safe. La méthode habituelle consiste à utiliser des [objets de section critique](https://msdn.microsoft.com/library/windows/desktop/ms682530\(v=vs.85\).aspx). * [ShapeFlowGraph (flowgraph)](/fr/reference/audio/shapeflowgraph/shapeflowgraph_members) * [ShapeDmaContext (DMA)](/fr/reference/audio/shapedmacontext/shapedmacontext_members) * [ShapeEqCompContext (EQCOMP)](/fr/reference/audio/shapeeqcompcontext/shapeeqcompcontext_members) * [ShapeFiltVolContext (FLTVOL)](/fr/reference/audio/shapefiltvolcontext/shapefiltvolcontext_members) * [ShapePcmContext (PCM)](/fr/reference/audio/shapepcmcontext/shapepcmcontext_members) * [ShapeSrcContext (SRC)](/fr/reference/audio/shapesrccontext/shapesrccontext_members) * [ShapeXmaContext (XMA)](/fr/reference/audio/shapexmacontext/shapexmacontext_members) ### Recommandations pour l'utilisation du SRC avec des données PCM et XMA Le tableau suivant présente les recommandations pour l'utilisation du bloc SRC avec des 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 être lue jusqu'à la fin. Vous pouvez éventuellement 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`) sur `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 être lue jusqu'à ce que vous souhaitiez l'arrêter à la fin d'une boucle en émettant `SHAPE_SRC_COMMAND_TYPE_STOP_END`, puis laissez la voix se terminer. Vous pouvez éventuellement 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`) sur \[0, 254]. Démarrez la voix à l'aide de `SHAPE_SRC_COMMAND_TYPE_START` pour le SRC. Laissez la voix être lue jusqu'à la fin. Vous pouvez éventuellement l'arrêter à la fin d'une boucle à l'aide de `SHAPE_SRC_COMMAND_TYPE_STOP_END` et laisser la voix se terminer. Vous pouvez éventuellement 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 streaming et à mettre à jour le pointeur d'écriture du contexte PCM jusqu'à ce que vous souhaitiez arrêter. Émettez `SHAPE_SRC_COMMAND_TYPE_STOP_END` pour laisser le SRC lire jusqu'au pointeur d'écriture PCM actuel (`loopStartWritePointer`). Vous pouvez éventuellement émettre `SHAPE_SRC_COMMAND_TYPE_STOP_IMMEDIATE` pour arrêter immédiatement. | | XMA en streaming (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 lire jusqu'à la fin du tampon décodé (consultez la REMARQUE qui suit). Vous pouvez éventuellement é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`) sur `SHAPE_XMA_INFINITE_LOOP_COUNT`. Démarrez la voix à l'aide de `SHAPE_SRC_COMMAND_TYPE_START` pour le SRC. Laissez la voix être lue jusqu'à ce que vous souhaitiez l'arrêter à la fin d'une boucle en définissant le nombre de boucles XMA sur zéro et en émettant `SHAPE_SRC_COMMAND_TYPE_STOP_END`, puis laissez la voix se terminer. Vous pouvez éventuellement 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`) sur \[0, 254]. Démarrez la voix à l'aide de `SHAPE_SRC_COMMAND_TYPE_START` pour le SRC. Laissez la voix être lue jusqu'à ce que vous souhaitiez 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 se terminer. Pour arrêter à la fin de la boucle suivante, vous pouvez éventuellement définir le nombre de boucles sur zéro. Lorsque le dernier tampon d'entrée XMA est consommé, définissez la commande SRC sur `SHAPE_SRC_COMMAND_TYPE_STOP_END` et laissez la voix se terminer (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 flowgraphs SHAPE. Si vous effectuez cette vérification dans le cadre de votre logique de streaming, qui s'exécute à des intervalles beaucoup plus longs, il est possible que le tampon de sortie XMA se vide avant que vous ne demandiez au SRC de s'arrêter à la fin. Cela peut entraîner le blocage du flowgraph. ### Mise en pause et reprise d'un titre Un titre doit pouvoir être mis en pause et repris, par exemple lorsque l'utilisateur le fait passer en mode contraint. Pour mettre en pause et reprendre lorsque vous codez directement pour le matériel SHAPE à l'aide de `IAcpHal`, faites simplement en sorte 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 flowgraphs persistants, il doit charger un flowgraph null pour arrêter le traitement. Ce processus diffère de la mise en pause et de la reprise lorsque vous codez à l'aide de `XAudio2`. Pour plus d'informations, consultez la [vue d'ensemble de XAudio2](/fr/build/console-features/audio/overviews/xaudio2-overview). ## Documentation de référence de l'API * [Acphal (contenu de l'API)](/fr/reference/audio/acphal/acphal_members) * Structures * [ACP\_COMMAND\_UPDATE\_DMA\_CONTEXT](/fr/reference/audio/acphal/structs/acp_command_update_dma_context) * [ACP\_COMMAND\_UPDATE\_EQCOMP\_CONTEXT](/fr/reference/audio/acphal/structs/acp_command_update_eqcomp_context) * [ACP\_COMMAND\_UPDATE\_FILTVOL\_CONTEXT](/fr/reference/audio/acphal/structs/acp_command_update_filtvol_context) * [ACP\_COMMAND\_UPDATE\_PCM\_CONTEXT](/fr/reference/audio/acphal/structs/acp_command_update_pcm_context) * [ACP\_COMMAND\_UPDATE\_SRC\_CONTEXT](/fr/reference/audio/acphal/structs/acp_command_update_src_context) * [ACP\_COMMAND\_UPDATE\_XMA\_CONTEXT](/fr/reference/audio/acphal/structs/acp_command_update_xma_context) * [ACP\_COMMAND\_LOAD\_SHAPE\_FLOWGRAPH](/fr/reference/audio/acphal/structs/acp_command_load_shape_flowgraph) * [Shapedmacontext (contenu de l'API)](/fr/reference/audio/shapedmacontext/shapedmacontext_members) * Structures * [SHAPE\_DMA\_CONTEXT](/fr/reference/audio/shapedmacontext/structs/shape_dma_context) * [Shapeeqcompcontext (contenu de l'API)](/fr/reference/audio/shapeeqcompcontext/shapeeqcompcontext_members) * Structures * [SHAPE\_EQCOMP\_CONTEXT](/fr/reference/audio/shapeeqcompcontext/structs/shape_eqcomp_context) * [Shapefiltvolcontext (contenu de l'API)](/fr/reference/audio/shapefiltvolcontext/shapefiltvolcontext_members) * Structures * [SHAPE\_FILTVOL\_CONTEXT](/fr/reference/audio/shapefiltvolcontext/structs/shape_filtvol_context) * [Shapeflowgraph (contenu de l'API)](/fr/reference/audio/shapeflowgraph/shapeflowgraph_members) * [Shapepcmcontext (contenu de l'API)](/fr/reference/audio/shapepcmcontext/shapepcmcontext_members) * Structures * [SHAPE\_PCM\_CONTEXT](/fr/reference/audio/shapepcmcontext/structs/shape_pcm_context) * [Shapesrccontext (contenu de l'API)](/fr/reference/audio/shapesrccontext/shapesrccontext_members) * Structures * [SHAPE\_SRC\_CONTEXT](/fr/reference/audio/shapesrccontext/structs/shape_src_context) * [Shapexmacontext (contenu de l'API)](/fr/reference/audio/shapexmacontext/shapexmacontext_members) * Structures * [SHAPE\_XMA\_CONTEXT](/fr/reference/audio/shapexmacontext/structs/shape_xma_context) * [apu (contenu de l'API)](/fr/reference/audio/apu/apu_members) * Fonctions * [ApuCreateHeap](/fr/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)