Vue d'ensemble de l'ACP

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. Pour plus de détails sur l’architecture SHAPE, consultez la vue d’ensemble de SHAPE. 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
Utilitaires DMA
Utilitaires de compresseur EQ
Utilitaires de filtre de volume
Utilitaires PCM
Utilitaires SRC
Utilitaires XMA
Valeurs cibles
Sécurité des threads
Lignes directrices pour l’utilisation du SRC avec les données PCM et XMA
Suspension et reprise d’un titre

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. 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). 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
Frontal d’un moteur audio logiciel
Rendu audio
Analyse des graphes de flux
Mise à jour des graphes de flux
Graphes de flux multiples

Sons 3D

Figure 1. Deux voix, chacune répartie (panoramique) entre deux sorties, avec un envoi vers une sortie commune.

Dans le code, ce graphe de flux peut être représenté comme suit.

        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.

        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

Créez un graphe de flux semblable à ceux présentés dans les exemples précédents, qui définit le graphe audio à traiter.
Créez des structures de contexte qui définissent comment et quoi le graphe de flux traitera.
Utilisez la méthode 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.
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.
Lorsque vous mettez à jour des contextes, notez qu’un paramètre d’indicateur de 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. 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 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.

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.
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. 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.
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. Pour plus de renseignements, consultez ShapeDmaContext (méthodes utilitaires DMA).

Utilitaires de compresseur EQ

Incluez les utilitaires EQCOMP du fichier ShapeEqCompContext.h. Ces utilitaires agissent sur une structure SHAPE_EQCOMP_CONTEXT. Pour plus de renseignements, consultez ShapeEqCompContext (méthodes utilitaires EQCOMP).

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. Pour plus de renseignements, consultez ShapeFiltVolContext (méthodes utilitaires FLTVOL).

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. Pour plus de renseignements, consultez ShapePcmContext (méthodes utilitaires PCM).

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. Pour plus de renseignements, consultez ShapeSrcContext (méthodes utilitaires SRC).

Utilitaires XMA

Incluez les utilitaires XMA du fichier ShapeXMAContext.h. Ces utilitaires agissent sur une structure SHAPE_XMA_CONTEXT. Pour plus de renseignements, consultez ShapeXmaContext (méthodes utilitaires XMA). 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. 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 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.

Remplissez le ou les contextes avec les données pertinentes : tampons, décalages, etc.
Activez les contextes.
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 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.

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 et les méthodes ACPHAL sont thread-safe. Si l’appel 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.

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.

Documentation de référence de l’API

Acphal (contenu de l’API)
- Structures
Shapedmacontext (contenu de l’API)
- Structures
  - SHAPE_DMA_CONTEXT
Shapeeqcompcontext (contenu de l’API)
- Structures
  - SHAPE_EQCOMP_CONTEXT
Shapefiltvolcontext (contenu de l’API)
- Structures
  - SHAPE_FILTVOL_CONTEXT
Shapeflowgraph (contenu de l’API)
Shapepcmcontext (contenu de l’API)
- Structures
  - SHAPE_PCM_CONTEXT
Shapesrccontext (contenu de l’API)
- Structures
  - SHAPE_SRC_CONTEXT
Shapexmacontext (contenu de l’API)
- Structures
  - SHAPE_XMA_CONTEXT
apu (contenu de l’API)
- Fonctions
  - ApuCreateHeap

Introduction

Onboarding & Access

Setup & Install

Build Your First Title