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

Dans cette rubrique, nous allons parcourir 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 dans le Microsoft Game Development Kit (GDK). Cet exemple s’appelle DecodeOne.cpp et couvre un scénario de décodage à flux unique avec un seul 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 via 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 nécessaire pour transmettre et récupérer les données d’entrée et de sortie, dans ce cas, 1024 pour MaxInputBufferLength (doit être supérieur ou égal au plus grand 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 telle sorte que l’unité d’accélération matérielle puisse y accéder directement, sans marshaling ni copie supplémentaires. 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 de gestionnaire de mémoire simple peut être utilisé pour 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, qui consiste à é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 moteur de décodage unique. L’appelant doit spécifier 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 sur 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 permettant d’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.
Spécifier la longueur du paquet.
Fournir l’emplacement de la mémoire tampon de sortie qui sera remplie avec les données décodées par l’unité d’accélération matérielle audio.
Spécifier la longueur maximale de la mémoire tampon de sortie.

L’appelant doit également spécifier 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 sur n’importe quelle valeur supérieure ou égale au nombre de trames encodées dans le paquet (par exemple, pour un paquet de 20 ms, frameCount peut être compris 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 sont stockées dans result.outputData. Après leur traitement, le paquet suivant doit être soumis pour décodage par 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);

Arrêt

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 et libérer toutes les ressources allouées.

hr = XApuDisconnect(xapuHandle);

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

Connexion au matériel audio et démarrage

Activation et désactivation des flux

Arrêt

​Connexion au matériel audio et démarrage

​Activation et désactivation des flux

​Arrêt

Connexion au matériel audio et démarrage

Activation et désactivation des flux

Arrêt