Décodage audio Opus à flux unique avec l'API XAPU

Dans cette rubrique, nous passerons en revue le déroulement attendu du code pour utiliser le décodage Opus accéléré par le matériel sur les appareils XBOX Series X à l’aide de l’un des exemples inclus avec le Microsoft Game Development Kit (GDK). Cet exemple s’appelle DecodeOne.cpp et couvre un scénario de décodage à flux unique avec un client.

Connexion au matériel audio et démarrage

Le décodage commence par l’établissement d’une connexion avec l’unité d’accélération matérielle au moyen de XApuConnect. L’appelant définit les exigences de la connexion à l’aide de XApuConnectInputParameters pour configurer les éléments suivants :

Le type de traitement (dans ce cas, XApuProcessType::DecodeOpus).
Le nombre de flux (dans ce cas, 1).
La mémoire totale requise pour transmettre et récupérer les données d’entrée et de sortie, dans ce cas 1024 pour MaxInputBufferLength (doit être égal ou supérieur au plus gros paquet Opus du flux). Le nombre doit également être un multiple de 16, et 7680. Cela correspond à 20 ms de données à 48 K, soit 960 × 2 × sizeof(float) = 7680 pour MaxOutputBufferLength. La sortie doit également être un multiple de 16.

Si cet appel réussit, le paramètre XApuConnectOutputParameters::baseData pointe vers un emplacement mémoire alloué par le système d’exploitation de manière à ce que l’unité d’accélération matérielle puisse y accéder directement sans marshaling ni copie supplémentaire. L’appelant doit utiliser cette mémoire pour transmettre les données d’entrée et récupérer les données de sortie. L’exemple suivant d’un gestionnaire de mémoire simple peut servir à définir XApuConnectInputParameters et à partitionner XApuConnectOutputParameters::baseData en deux pointeurs : l’un pour les données d’entrée et l’autre pour les données de sortie.

class DecodeOneSimpleMemoryManager
{
public:
    static const uint32_t MaxStreamCount = 1;
    const uint32_t MaxInputBufferLength = 1024; // Must be equal to or greater than the largest Opus packet in the stream. The number must also be a multiple of 16.
    const uint32_t MaxOutputBufferLength = 7680; // This is 20 ms of data at 48 K, which is 960 x 2 x sizeof(float) = 7680 for MaxOutputBufferLength. The output also needs to be multiple of 16.

private:
    XApuConnectInputParameters _inParam = {
        XApuProcessType::DecodeOpus,
        MaxStreamCount,
        1,
        MaxStreamCount * (MaxInputBufferLength + MaxOutputBufferLength),
        0,
        XApuConnectOptions::None };

    XApuConnectOutputParameters _outParam = {};

public:
    XApuConnectInputParameters * const GetConnectParametersRef() {
        return &_inputParam;
    }

    XApuConnectOutputParameters * const GetConnectionDataRef() {
        return &_outParam;
    }

    uint8_t* GetRawInputBuffer(uint32_t& maxByteCount) {
        maxByteCount = MaxInputBufferLength;
        return reinterpret_cast<uint8_t*>(_outParam.baseData);
    }

    uint8_t* GetRawOutputBuffer(uint32_t& maxByteCount) {
        maxByteCount = MaxOutputBufferLength;
        return reinterpret_cast<uint8_t*>(_outParam.baseData) + MaxInputBufferLength;
    }
};

Voici l’exemple de code de la première étape pour établir une connexion.

XApuConnectInputParameters * const connectParameters = memoryManager.GetConnectParametersRef();
XApuConnectOutputParameters * const connectionData = memoryManager.GetConnectionDataRef();
hr = XApuConnect(connectParameters, connectionData, &xapuHandle);

Activation et désactivation des flux

Une fois la connexion établie avec le périphérique, l’appelant doit envoyer une commande d’activation de flux pour engager un seul moteur de décodage. L’appelant doit indiquer l’index du flux et le nombre de canaux. Seuls les flux mono ou stéréo sont autorisés. L’appelant doit appeler XApuDequeueResult pour obtenir le résultat de l’activation. Comme XApuConnectInputParameters::maxQueuedCommandsPerStream est défini à 1 dans cet exemple, l’appelant doit attendre chaque résultat avant de soumettre la commande suivante. Cela inclut les commandes Activate, Process et Deactivate (pour plus de détails, consultez XApuCommandType). Voici le code pour activer un flux.

XApuDecodeConvertActivateCommand command = {};
command.id.type = XApuCommandType::Activate;
command.id.streamIndex = 0;
command.id.sequence = 0;
command.channelCount = channelCount;

hr = XApuEnqueueCommand(xapuHandle, &command.id, nullptr);
XApuResult result = {};

do {
    hr = XApuDequeueResult(handle, &result);
} while (hr == XAPU_E_PENDING_RESULTS);

Une fois le résultat de l’activation reçu, l’appelant peut commencer à soumettre des paquets Opus pour décodage. Cela doit se faire à l’aide de la commande XApuCommandType::Process. Pour chaque commande Process, l’appelant doit effectuer les opérations suivantes :

Remplir la mémoire tampon d’entrée avec exactement un paquet Opus.
Indiquer la longueur du paquet.
Fournir l’emplacement de la mémoire tampon de sortie qui sera remplie de données décodées par l’unité d’accélération matérielle audio.
Indiquer la longueur maximale de la mémoire tampon de sortie.

L’appelant doit également indiquer les valeurs streamIndex et frameCount. Si toutes les données décodées doivent être copiées dans la mémoire tampon de sortie, la valeur frameCount peut être définie à n’importe quelle valeur égale ou supérieure au nombre de trames encodées dans le paquet (par exemple, pour un paquet de 20 ms, frameCount peut être défini entre 960 et 0xFFFFFFFF).

XApuDecodeConvertCommand command = {};
command.id.streamIndex = 0;
command.id.type = XApuCommandType::Process;
command.id.sequence = packetIndex;
command.frameCount = 0xFFFFFFFF;
command.inputData = memoryManager.GetRawInputBuffer(inputMaxByteCount);
command.inputDataLength = packetLength;
command.outputData = memoryManager.GetRawOutputBuffer(outputMaxByteCount);
command.maxOutputDataLength = outputMaxByteCount;

hr = XApuEnqueueCommand(xapuHandle, &command.id, nullptr);

Ensuite, XApuDequeueResult doit être appelé pour obtenir la sortie décodée du paquet. Une fois XApuResult récupéré avec succès, les données de sortie seront stockées dans result.outputData. Après leur traitement, le paquet suivant doit être soumis pour décodage au moyen d’un nouvel appel à XApuEnqueueCommand avec la commande XApuCommandType::Process.

XApuResult result = {};

do {
    hr = XApuDequeueResult(handle, &result);
    if (SUCCEEDED(hr))
    {
         if (result.id.type == XApuCommandType::Process)
         {
              fwrite(result.outputData, 1, result.outputDataLength, fileOutput);
         }
    }
    
} while (hr == XAPU_E_PENDING_RESULTS);

Une fois tous les paquets du flux décodés, une commande XApuCommandType::Deactivate doit être soumise.

XApuCommandId id;
id.type = XApuCommandType::Deactivate;
id.streamIndex = 0;
id.sequence = 0;

hr = XApuEnqueueCommand(xapuHandle, &id, nullptr);

do {
    hr = XApuDequeueResult(handle, &result);
} while (hr == XAPU_E_PENDING_RESULTS);

Terminaison

Une fois le résultat de la désactivation reçu, l’appelant doit appeler XApuDisconnect pour se déconnecter de l’unité d’accélération matérielle audio afin de libérer toutes les ressources allouées.

hr = XApuDisconnect(xapuHandle);

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

Connexion au matériel audio et démarrage

Activation et désactivation des flux

Terminaison

​Connexion au matériel audio et démarrage

​Activation et désactivation des flux

​Terminaison

Connexion au matériel audio et démarrage

Activation et désactivation des flux

Terminaison