Easy Hardware Decompression

The XBOX Series consoles support hardware decompression for zlib compressed content using DirectStorage. Provided here is a drop-in replacement for the stock software zlib inflate function. Using this code can allow a developer to add support for accelerated hardware decompression with the minimum number of changes to their code. It will provide an immediate improvement in decompression times while also freeing up CPU resources that can be used for other work. A one-time initialization is needed to create the DirectStorage objects being used for hardware decompression.

Microsoft::WRL::ComPtr<IDStorageFactoryX> inflateDropInFactory;
Microsoft::WRL::ComPtr<IDStorageQueueX> inflateDropInQueue;
Microsoft::WRL::ComPtr<IDStorageStatusArrayX> inflateDropInStatus;

void CreateDSObjects()
{
    DX::ThrowIfFailed(DStorageGetFactory(__uuidof(IDStorageFactoryX), (void**)(inflateDropInFactory.ReleaseAndGetAddressOf())));
    DSTORAGE_QUEUE_DESC queueDesc = {};
    queueDesc.SourceType = DSTORAGE_REQUEST_SOURCE_MEMORY;
    queueDesc.Priority = DSTORAGE_PRIORITY_REALTIME;
    queueDesc.Capacity = DSTORAGE_MIN_QUEUE_CAPACITY;
    inflateDropInFactory->CreateQueue(&queueDesc, __uuidof(IDStorageQueueX), (void**)(inflateDropInQueue.ReleaseAndGetAddressOf()));
    inflateDropInFactory->CreateStatusArray(1, nullptr, __uuidof(IDStorageStatusArrayX), (void**)(inflateDropInStatus.ReleaseAndGetAddressOf()));
}

Hardware decompression has a minimum setup cost, because of this it can be faster to use software decompression for smaller block sizes. A table of times is provided below using ASCII text as the source buffer. You should profile to find the best cross-over size against your software decompressor and content. There is an assumption in this code that the compressed content conforms to the supported IETF RFC 1950 zlib standard. See Optimizing compressed content by using DirectStorage and XBTC (microsoft.com) for more details.

int inflateDropIn(z_streamp strm, int flush)
{
    bool fallback(false);
    if (strm->avail_out <= strm->total_in)
        fallback = true;
    if (flush != Z_FINISH)
        fallback = true;
    if (strm->avail_out < c_hardwareSizeCrossOverSize)
        fallback = true;
    if (fallback)
        return inflate(strm, flush);

    DSTORAGE_REQUEST request = {};
    request.Options.ZlibDecompress = true;
    request.Options.SourceType = DSTORAGE_REQUEST_SOURCE_MEMORY;
    request.Source = strm->next_in;
    request.SourceSize = strm->total_in;
    request.Destination = strm->next_out;
    request.DestinationSize = strm->avail_out;
    inflateDropInQueue->EnqueueRequest(&request);
    inflateDropInQueue->EnqueueStatus(inflateDropInStatus.Get(), 0);
    inflateDropInQueue->Submit();
    while (!inflateDropInStatus->IsComplete(0))
    {
        _mm_pause();
    }
    return Z_STREAM_END;
}

This table provides a measurement of times for the stock software zlib decompressor versus the hardware decompressor from an XBOX Series X|S running at 3.8GHz using ASCII text as the source buffer. Different compression ratios will create different cross-over points for which is faster between software and hardware. You should profile to find the best cross-over size against your software decompressor and content. Block size is in bytes and times are in microseconds.

Block Size	CPU Time	Hardware Time
128	2.91	75.39
256	3.67	65.29
512	4.14	65.54
1,024	5.59	66.63
2,048	7.65	66.29
4,096	10.96	83.93
8,192	13.69	69.04
10,240	15.08	67.09
12,288	16.16	67.66
14,336	17.37	70.58
16,384	18.40	72.56
20,480	20.58	70.34
24,576	22.88	71.52
28,672	25.34	71.34
32,768	27.71	73.03
36,864	29.73	72.35
40,960	31.56	77.67
45,056	34.34	73.22
65,536	46.76	76.69
131,072	83.96	89.13
262,144	158.32	111.58
524,288	308.01	177.95

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features