Overview of a single stream Convolution using the XDSP API

In this topic, we will walk through the expected code flow about how to use hardware Convolution reverb on XBOX Series X devices by using one of the samples included with the Microsoft Game Development Kit (GDK).

Hardware connection and startup

A connection has to be established with the hardware acceleration unit via XDspConnect or XDspConnectWithMaximumStreamLimit. The caller sets the requirements for the connection by using the following parameters:

baseBuffer - A pointer to the user allocated memory enough to hold input, output, envelope buffer and/or block multiplier buffers that will be passed to the hardware. This memory should be allocated via XMemAlloc with these attributes: XALLOC_MEMTYPE_PHYSICAL_CACHEABLE, XALLOC_PAGESIZE_64KB, XALLOC_ALIGNMENT_64K. These attributes should be set using MAKE_XALLOC_ATTRIBUTES(), as shown in the example below. This memory should not be freed until XDspDisconnect call succeeds. This buffer should be at least 64KB in size.
baseBufferLength - The length of the baseBuffer in bytes. This buffer should be at least 64KB and no more than 500 MB.
aggregateImpulseResponseInSeconds - It represents the overall duration of all the individual impulse responses that will be activated simultaneously using XDspActivate with XDspProcessType::Convolution. If this value is 0, no streams with XDspProcessType::Convolution can be activated.
handle - a pointer to the XDspClientHandle to hold the handle returned by this call.

If the call succeeds, the baseBuffer can be used by the caller to pass input data and retrieve the output data of the streams via XDspCommand parameters. Any buffer that is passed in the XDspCommand should be 16 byte aligned. The following example of a simple buffer manager can be used for managing the input and output buffers.

class ConvolveOneBufferManager
{
private:
    float const* _outputBuffer = nullptr;
    uint32_t _maxBufferFrameCount = 0;
    uint32_t _bufferStride = 0;
    uint32_t _maxBufferCount = 0;
    uint32_t _acquiredBufferCount = 0;
    uint32_t _channelCount = 1;

public:
    void Reset(float const* outputBuffer, uint32_t maxBufferCount, uint32_t maxBufferFrameCount, uint32_t channelCount) {
        _outputBuffer = outputBuffer;
        _maxBufferCount = maxBufferCount;
        _maxBufferFrameCount = maxBufferFrameCount;
        _channelCount = channelCount;
    }

    uint32_t GetMaxBufferFrameCount() const {
        return _maxBufferFrameCount;
    }

    bool IsFull() const {
        return _acquiredBufferCount >= _maxBufferCount;
    }

    void Acquire() {
        if (_acquiredBufferCount < _maxBufferCount) {
            _acquiredBufferCount++;
        }
    }

    void Release() {
        if (_acquiredBufferCount > 0) {
            _acquiredBufferCount--;
        }
    }

    float* GetOutputBuffer(uint32_t index) {
        return const_cast<float*>(_outputBuffer) + (((index % _maxBufferCount) * _maxBufferFrameCount * _channelCount));
    }

};

Following is the code example for the first step to allocate memory and establish a connection.

static const ULONGLONG XMemAllocAttributes = MAKE_XALLOC_ATTRIBUTES(allocatorId,
                      0,
                      XALLOC_MEMTYPE_PHYSICAL_CACHEABLE,
                      XALLOC_PAGESIZE_64KB,
                      XALLOC_ALIGNMENT_64K,
                      FALSE);

float* baseBuffer = (float *)XMemAlloc(baseBufferLength, XMemAllocAttributes);

Where XMemAllocAttributes represents the attributes mentioned above. The following code sets the aggregateImpulseResponse to 32 seconds.

hr = XDspConnect(baseBuffer, baseBufferLength, 32 /*aggregateImpulseResponseInSeconds*/, &clientHandle);

Activation and deactivation of streams

After the connection is established with the device, the caller should send a stream activation command to engage a convolution, FFT or IFFT. The caller must specify the XDspProcessType, block frame count, channel count, impulse response length in floats and a pointer to the impulse response data in frequency domain in the XDspActivationParameters. Only mono or stereo streams are allowed. For XDspProcessType::ForwardFourierTransform and XDspProcessType::inverseFourierTransform, XDspActivationParameters::impulseResponse should be nullptr and XDspActivationParameters::impulseResponseLengthInFloats = 0. XDspActivationOptions should be set appropriately. Following is the code to activate one stream for convolution.

XDspActivationParameters params;
XDspStatus* status;
XDspStreamHandle* streamHandle;
params.type = XDspProcessType::Convolution;
params.blockFrameCount = maxBufferFrameCount;
params.channelCount = channelCount; // mono or stereo
params.impulseResponseLengthInFloats = filterFrameCount;
params.impulseResponse = filterBuffer;

if (channelCount == 2 && deinterleaved)
{
    params.options |= XDspActivationOptions::Deinterleaved;
}
if (stereoImpulseResponse)
{
    params.options |= XDspActivationOptions::StereoImpulseResponse;
}
hr = XDspActivate(clientHandle, &params, &status, &streamHandle); 

XDspActivate returns a XDspStatus buffer as one of its parameters. This XDspStatus buffer should be used to find the status of the commands processed by the hardware for this stream. After the activation result is received, the caller can start submitting data for Convolution/FFT/IFFT. This should be done by using the XDspSubmitCommand API. For each XDspSubmitCommand, the caller must do the following:

Fill the input buffer with exactly blockFrameCount of data.
Fill in the XDspCommand with appropriate values and input and output buffers that are 16 byte aligned.
Call XDspSubmitCommand to submit the command to the hardware. This function returns a command sequence number that can be used to track the number of commands sent to the hardware.

XDspCommand command;

command.beginScale = 1.0f;
command.endScale = 1.0f;
command.inputBlockBuffer = inputDataBuffer;
command.outputBlockBuffer =  bufferManager.GetOutputBuffer(_totalCommandsSubmitted + 1);
command.blockBufferMultiplier = nullptr;

uint32_t sequence = 0;
hr = XDspSubmitCommand(streamHandle, &command, &sequence);

if (SUCCEEDED(hr))
{
    totalCommandsSubmitted++;
}

Next, XDspStatus can be checked to find the status of the commands submitted to the hardware as follows:

while (status->lastProcessedCommandSequence > totalResponsesReceived)
{
    totalResponsesReceived++;
 
    // Hardware status is only updated when there is a hardware fault and the
    // error is going to persist for the duration of the stream. But, all the
    // commands that have already been submitted will still be processed by
    // the hardware and we have to wait for these commands to be processed 
    // before calling XDspDeactivate.
    hr = status->result; 
     
    float* outBuffer = bufferManager.GetOutputBuffer(totalResponsesReceived);
    // The output will be in the outBuffer
    // Do something with the outBuffer
    bufferManager.Release();
}

The packets in the stream are processed or the hardware returns an error in XDspStatus result, XDspDeactivate should be called.

while (totalResponsesReceived < totalCommandsSubmitted)
{
    // run the above code in the while loop to obtain all the responses
}
hr = XDspDeactivate(streamHandle);

XDspDeactivate returns XDSP_E_PENDING_RESULTS if the hardware is not done processing all commands submitted for this stream.

Termination

After XDspDeactivate succeeds, the caller must call XDspDisconnect to disconnect from the audio hardware acceleration unit to free all the allocated resources. If all streams are not deactivated, XDspDisconnect will return XDSP_E_NOT_ALL_HANDLES_DEACTIVATED error.

hr = XDspDisconnect(clientHandle);
XMemFree(baseBuffer, XMemAllocAttributes);

Reference API documentation

XDspAudio (API contents)
- Functions
- Structures

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

Overview of a single stream Convolution using the XDSP API

Hardware connection and startup

Activation and deactivation of streams

Termination

Reference API documentation

See also

​Hardware connection and startup

​Activation and deactivation of streams

​Termination

​Reference API documentation

​See also

Hardware connection and startup

Activation and deactivation of streams

Termination

Reference API documentation

See also