Skip to main content
Dans cette rubrique, nous passerons en revue le déroulement prévu du code pour utiliser la réverbération par convolution matérielle sur les appareils XBOX Series X, à l’aide de l’un des exemples inclus avec le Microsoft Game Development Kit (GDK).

Connexion au matériel et démarrage

Une connexion doit être établie avec l’unité d’accélération matérielle au moyen de XDspConnect ou de XDspConnectWithMaximumStreamLimit. L’appelant définit les exigences de la connexion à l’aide des paramètres suivants :
  1. baseBuffer : pointeur vers la mémoire allouée par l’utilisateur, suffisante pour contenir les mémoires tampons d’entrée, de sortie, d’enveloppe et/ou de multiplicateur de bloc qui seront transmises au matériel. Cette mémoire doit être allouée au moyen de XMemAlloc avec les attributs suivants : XALLOC_MEMTYPE_PHYSICAL_CACHEABLE, XALLOC_PAGESIZE_64KB, XALLOC_ALIGNMENT_64K. Ces attributs doivent être définis à l’aide de MAKE_XALLOC_ATTRIBUTES(), comme le montre l’exemple ci-dessous. Cette mémoire ne doit pas être libérée tant que l’appel à XDspDisconnect n’a pas réussi. Cette mémoire tampon doit avoir une taille d’au moins 64 Ko.
  2. baseBufferLength : longueur de baseBuffer, en octets. Cette mémoire tampon doit avoir une taille d’au moins 64 Ko et d’au plus 500 Mo.
  3. aggregateImpulseResponseInSeconds : représente la durée globale de toutes les réponses impulsionnelles individuelles qui seront activées simultanément à l’aide de XDspActivate avec XDspProcessType::Convolution. Si cette valeur est 0, aucun flux avec XDspProcessType::Convolution ne peut être activé.
  4. handle : pointeur vers le XDspClientHandle qui contiendra le handle retourné par cet appel.
Si l’appel réussit, l’appelant peut utiliser baseBuffer pour transmettre les données d’entrée et récupérer les données de sortie des flux au moyen des paramètres de XDspCommand. Toute mémoire tampon transmise dans XDspCommand doit être alignée sur 16 octets. L’exemple suivant d’un gestionnaire de mémoires tampons simple peut servir à gérer les mémoires tampons d’entrée et de sortie.
Les mémoires tampons d’enveloppe de chaque flux doivent faire partie du baseBuffer transmis à XDspConnect ou à XDspConnectWithMaximumStreamLimit, comme les mémoires tampons d’entrée et de sortie. La longueur de chaque mémoire tampon d’enveloppe peut être calculée comme suit.
Voici l’exemple de code de la première étape, qui consiste à allouer la mémoire et à établir une connexion. Notez que XDspConnectWithMaximumStreamLimit peut être utilisé à la place de XDspConnect pour réduire l’utilisation de la mémoire interne si le nombre de flux pouvant être actifs est inférieur à 256.
où XMemAllocAttributes représente les attributs mentionnés ci-dessus. Le code suivant définit aggregateImpulseResponse à 32 secondes.

Activation et désactivation des flux

Une fois la connexion établie avec l’appareil, l’appelant doit envoyer une commande d’activation de flux pour lancer une convolution, une FFT ou une IFFT. L’appelant doit spécifier le XDspProcessType, le nombre de trames par bloc, le nombre de canaux, la longueur de la réponse impulsionnelle en valeurs float et un pointeur vers les données de la réponse impulsionnelle dans le domaine fréquentiel dans XDspActivationParameters. Seuls les flux mono ou stéréo sont autorisés. Pour XDspProcessType::ForwardFourierTransform et XDspProcessType::inverseFourierTransform, XDspActivationParameters::impulseResponse doit être nullptr et XDspActivationParameters::impulseResponseLengthInFloats = 0. XDspActivationOptions doit être défini de façon appropriée. Voici le code permettant d’activer un flux pour la convolution.
XDspActivate retourne une mémoire tampon XDspStatus dans l’un de ses paramètres. Cette mémoire tampon XDspStatus doit servir à connaître l’état des commandes traitées par le matériel pour ce flux. Une fois le résultat de l’activation reçu, l’appelant peut commencer à soumettre des données pour la convolution, la FFT ou l’IFFT. Cela doit se faire à l’aide de l’API XDspSubmitCommand ou XDspSubmitCommandWithEnvelope. À chaque appel, l’appelant doit effectuer les opérations suivantes :
  1. Remplir la mémoire tampon d’entrée avec exactement blockFrameCount données.
  2. Remplir XDspCommand avec les valeurs appropriées ainsi que des mémoires tampons d’entrée et de sortie alignées sur 16 octets.
  3. Appeler XDspSubmitCommand pour soumettre la commande au matériel. Cette fonction retourne un numéro de séquence de commande qui peut servir à suivre le nombre de commandes envoyées au matériel.
  4. Pour appliquer une enveloppe, remplir la mémoire tampon d’enveloppe avec les valeurs de gain de chaque bloc du filtre de réponse impulsionnelle, appeler XDspSubmitCommandWithEnvelope, puis continuer à effectuer cet appel avec la même mémoire tampon d’enveloppe jusqu’à ce que l’enveloppe ne soit plus nécessaire ou qu’elle doive être modifiée.
  5. Lorsque l’enveloppe n’est plus nécessaire, appeler XDspSubmitCommand ou XDspSubmitCommandWithEnvelope avec nullptr pour envelopeBuffer. Notez que XDspSubmitCommandWithEnvelope avec nullptr pour envelopeBuffer équivaut à XDspSubmitCommand.
  6. Lors du changement d’enveloppe, le envelopeBuffer actuel ne peut être mis à jour pour la prochaine enveloppe que si le matériel a traité toutes les commandes utilisant cette enveloppe et que les résultats ont été récupérés. Sinon, utilisez une autre mémoire tampon d’enveloppe.
L’extrait de code suivant montre un exemple de remplissage de la mémoire tampon d’enveloppe avec les valeurs de gain de chaque bloc du filtre de réponse impulsionnelle. Il montre comment utiliser seulement la première moitié du filtre de réponse impulsionnelle : les valeurs de gain de la première moitié des blocs de la réponse impulsionnelle commencent à 1.0f et diminuent de façon linéaire, tandis que la seconde moitié est remplie avec une valeur de gain de 0.0f. Pour un filtre de réponse impulsionnelle stéréo, le filtre complet du canal gauche est suivi de celui du canal droit; la mémoire tampon d’enveloppe du filtre de réponse impulsionnelle stéréo suit le même modèle, les valeurs de gain de tout le canal gauche étant suivies des valeurs de gain de tout le canal droit. Consultez Vue d’ensemble de l’enveloppe à l’aide de l’API XDSP pour savoir comment calculer la taille de la mémoire tampon d’enveloppe.
L’extrait de code suivant montre l’application de l’enveloppe en appelant XDspSubmitCommandWithEnvelope avec un envelopeBuffer valide. Il est identique à l’extrait qui montre comment soumettre une commande à l’aide de XDspSubmitCommand, sauf qu’il transmet le paramètre supplémentaire envelopeBuffer. Cette opération doit être répétée jusqu’à ce que l’enveloppe ne soit plus nécessaire; il faut alors appeler XDspSubmitCommand ou XDspSubmitCommandWithEnvelope avec nullptr pour envelopeBuffer.
Ensuite, vous pouvez vérifier XDspStatus pour connaître l’état des commandes soumises au matériel, comme suit :
Lorsque les paquets du flux ont été traités ou que le matériel retourne une erreur dans le résultat de XDspStatus, XDspDeactivate doit être appelé.
XDspDeactivate retourne XDSP_E_PENDING_RESULTS si le matériel n’a pas fini de traiter toutes les commandes soumises pour ce flux.

Arrêt

Une fois que XDspDeactivate a réussi, l’appelant doit appeler XDspDisconnect pour se déconnecter de l’unité d’accélération matérielle audio et libérer toutes les ressources allouées. Si tous les flux ne sont pas désactivés, XDspDisconnect retourne l’erreur XDSP_E_NOT_ALL_HANDLES_DEACTIVATED.

Documentation de référence de l’API

Voir aussi

Vue d’ensemble de XDSP Vue d’ensemble de l’enveloppe à l’aide de l’API XDSP
Last modified on October 6, 2026