Skip to main content
Dans cette rubrique, nous allons examiner le flux de code attendu pour utiliser la réverbération par convolution matérielle sur les appareils XBOX Series X, à l’aide de l’un des exemples inclus dans 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 via XDspConnect ou 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 passées au matériel. Cette mémoire doit être allouée via 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 illustré dans 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 totale 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 destiné à contenir le handle retourné par cet appel.
Si l’appel réussit, l’appelant peut utiliser baseBuffer pour passer les données d’entrée et récupérer les données de sortie des flux via les paramètres de XDspCommand. Toute mémoire tampon passée dans XDspCommand doit être alignée sur 16 octets. L’exemple suivant de gestionnaire de mémoire tampon simple peut être utilisé pour 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 passé à 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 de 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 sur 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 dans XDspActivationParameters 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 réponse impulsionnelle dans le domaine fréquentiel. 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 manière 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 être utilisée pour 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/FFT/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 de données.
  2. Renseigner XDspCommand avec les valeurs appropriées et 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 être utilisé pour 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 l’enveloppe suivante 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 uniquement la première moitié du filtre de réponse impulsionnelle : les valeurs de gain de la première moitié des blocs de réponse impulsionnelle commencent à 1.0f et diminuent de façon linéaire, et la seconde moitié est remplie avec une valeur de gain de 0.0f. Pour un filtre de réponse impulsionnelle stéréo, l’intégralité du filtre du canal gauche est suivie de celle du canal droit ; la mémoire tampon d’enveloppe du filtre de réponse impulsionnelle stéréo suit le même modèle, avec les valeurs de gain de l’ensemble du canal gauche suivies des valeurs de gain de l’ensemble du canal droit. Consultez Vue d’ensemble de l’enveloppe à l’aide de l’API XDSP pour plus d’informations sur le calcul de 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, à l’exception du paramètre supplémentaire envelopeBuffer qui est passé. 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