> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Easy Hardware Decompression

> 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.

```cpp theme={null}
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](https://www.ietf.org/rfc/rfc1950.txt)
zlib standard. See [Optimizing compressed content by using DirectStorage
and XBTC
(microsoft.com)](https://developer.microsoft.com/games/xbox/docs/gdk/directstorage-compression)
for more details.

```cpp theme={null}
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            |


## Related topics

- [DirectStorage Overview](/build/console-features/storage/directstorage/directstorage-overview.md)
- [DirectStorage](/build/console-features/storage/directstorage-toc.md)
- [Overview of XMA2](/build/console-features/audio/overviews/xma2-overview.md)
- [XBOX Texture Compressor (XBTC) tool reference](/build/core-features/graphics/newfeatures/xbtc/index.md)
- [DSTORAGE_STATS](/reference/system/dstorage/structs/dstorage_stats.md)