Vue d'ensemble de l'ACP

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. 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, veillez à inclure le fichier ShapeContext.h, et non les fichiers d’en-tête de contexte individuels. Dans cette rubrique :

Flowgraphs
Utilitaires DMA
Utilitaires du compresseur EQ
Utilitaires de filtre de volume
Utilitaires PCM
Utilitaires SRC
Utilitaires XMA
Valeurs cibles
Sécurité des threads
Recommandations pour l’utilisation du SRC avec des données PCM et XMA
Mise en pause et reprise d’un titre

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

Sons 3D

Figure 1. Deux voix, chacune panoramiquée entre deux sorties, avec un envoi vers une sortie commune.

Dans le code, ce flowgraph 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 flowgraph 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 flowgraph 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 flowgraph va traiter.
Utilisez la méthode 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.
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.
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 à 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. 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 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.

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

Utilitaires du compresseur EQ

Incluez les utilitaires EQCOMP du fichier ShapeEqCompContext.h. Ces utilitaires opèrent sur une structure SHAPE_EQCOMP_CONTEXT. Pour plus d’informations, consultez ShapeEqCompContext (méthodes utilitaires EQCOMP).

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

Utilitaires PCM

Incluez les utilitaires Pulse Code Modulation (PCM) du fichier ShapePCMContext.h. Ces utilitaires opèrent sur une structure SHAPE_PCM_CONTEXT. Pour plus d’informations, consultez ShapePcmContext (méthodes utilitaires PCM).

Utilitaires SRC

Incluez les utilitaires Sample Rate Convertor (SRC) du fichier ShapeSRCContext.h. Ces utilitaires opèrent sur une structure SHAPE_SRC_CONTEXT. Pour plus d’informations, consultez ShapeSrcContext (méthodes utilitaires SRC).

Utilitaires XMA

Incluez les utilitaires XMA du fichier ShapeXMAContext.h. Ces utilitaires opèrent sur une structure SHAPE_XMA_CONTEXT. Pour plus d’informations, 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 flowgraphs, mais les données doivent toujours 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 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.

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 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 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.

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 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. Si nécessaire, vous pouvez les rendre thread-safe. La méthode habituelle consiste à utiliser des objets de section critique.

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.

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