Git Product home page Git Product logo

directstorage's Introduction

DirectStorage on Windows Samples

DirectStorage is a feature intended to allow games to make full use of high-speed storage (such as NVMe SSDs) that can can deliver multiple gigabytes a second of small (eg 64kb) data reads with minimal CPU overhead. Although it is possible to saturate a drive using traditional ReadFile-based IO the CPU overhead of increases non-linearly as the size of individual reads decreases. Additionally, most games choose to store their assets compressed on disk in order to reduce the install footprint, with these assets being decompressed on the fly as load time. The CPU overhead of this becomes increasingly expensive as bandwidth increases.

Video game consoles such as the XBox Series X|S address these issues by offloading aspects of this to hardware - making use of the NVMe hardware queue to manage IO and hardware accelerated decompression. As we expect to see more titles designed to take advantage of the possibilities offered by this architecture it becomes important that Windows has similar capabilities.

The DirectStorage API already exists on Xbox and in order to ease porting of titles between Xbox and Windows, the two APIs are as similar as possible.

DirectStorage only supports read operations.

You can find some good starting information in Developer Guidance

We invite you to join us at our discord server. See the related links section for our full list of Direct3D 12 and DirectStorage-related links.

API Samples

The Samples directory contains sample code that demonstrates how to use the DirectStorage APIs.

  1. HelloDirectStorage: This rudimentary sample serves to provide a quick and easy way to get acquainted with the DirectStorage runtime by reading the contents of a file and writing them out to a buffer on the GPU using DirectStorage.

    HelloDirectStorage screenshot
  2. BulkLoadDemo: This demonstrates using DirectStorage, GPU decompression and custom CPU decompression.

    BulkLoadDemo screenshot
  3. GpuDecompressionBenchmark: This sample provides a quick way to see the DirectStorage runtime decompression performance by reading the contents of a file, compressing it and then decompressing multiple ways while measuring the bandwidth and CPU usage. Decompression is performed using the GPU as well as the CPU for comparison.

    GpuDecompressionBenchmark screenshot

GDeflate Reference Implementation

This directory contains codec source and sample code that demonstrates how to use GDeflate.

The repo uses submodules, so be sure to pass --recurse-submodules to the git clone command.

If you forget to do this then you can run git submodule update --init

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

Build

Install Visual Studio 2019 or higher.

Open the following Visual Studio solutions and build

Samples\HelloDirectStorage\HelloDirectStorage.sln
Samples\BulkLoadDemo\BulkLoadDemo.sln
Samples\GpuDecompressionBenchmark\GpuDecompressionBenchmark.sln

Related links

directstorage's People

Contributors

colta95 avatar coopp avatar damyanp avatar dependabot[bot] avatar haydntrigg avatar markleone avatar mattiabosco avatar microsoft-github-operations[bot] avatar microsoftopensource avatar programmax avatar rechardchen avatar squall-leonhart avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

directstorage's Issues

Size of the DSTORAGE_REQUEST_OPTIONS

While porting the DirectStorage API to Rust, we found the following curriosity and would like to as if it's working as designed:

The DSTORAGE_REQUEST_OPTIONS is defines as a bitfield and it seems that the design goal was that all fields are packed into a single unsigned 64 bit integer field.

But the current implementation is not of byte size 8, but of size 16, since MSVC is only packing fields with the same type into the same backing field. Since DSTORAGE_COMPRESSION_FORMAT is an UINT8 and not an UINT64 like the other fields, it will be stored by MSVC into it's own backing field. Allignment and padding then will grow the size of DSTORAGE_REQUEST_SOURCE_TYPE to 16 bytes.

IDStorageQueue::EnqueueRequest() and multithreading

Can IDStorageQueue::EnqueueRequest() be called on the same queue from multiple threads at the same time, or should requests be enqueued from one thread at a time? Developer guidance does not make this clear.

Staging buffer sizes should be per-queue

A per-process one-size-fits-all might work for games on Xbox, but working on a high-end PC content creation tool this is just not working for me. 4K uncompressed textures (development build, content creation, background async compression while live reloading etc) need a large staging buffer size, while during sculpting geometry I can live with much smaller sizes and I want the VA / BAR address space.

ZLib The DirectStorage request failed

When I compiled in release mode and ran with a 2Gbyte input file, got below error.
What can cause this, something I need to configure in win11?

Compressing N:\Data\data.cow to N:\Data\data.cow.gdeflate in 162x16 MiB chunks
Total: 2716752886 --> 2716882936 bytes (100.005%)
Compressing N:\Data\data.cow to N:\Data\data.cow.zlib in 162x16 MiB chunks
Total: 2716752886 --> 2711941577 bytes (99.8229%)
Uncompressed:
16 MiB staging buffer: .......... 4.10728 GB/s mean cycle time: 370784527
32 MiB staging buffer: .......... 6.78455 GB/s mean cycle time: 308674715
64 MiB staging buffer: .......... 5.65416 GB/s mean cycle time: 339077114
128 MiB staging buffer: .......... 5.47467 GB/s mean cycle time: 363720296
256 MiB staging buffer: .......... 4.65176 GB/s mean cycle time: 405283062
512 MiB staging buffer: .......... 4.09985 GB/s mean cycle time: 448052001
1024 MiB staging buffer: .......... 4.08624 GB/s mean cycle time: 188527878
ZLib:
16 MiB staging buffer: The DirectStorage request failed! HRESULT=0x89240008
13052685 16782342

Q:\git_external\DirectStorage\Samples\GpuDecompressionBenchmark\x64\Release\GpuDecompressionBenchmark.exe (process 9040) exited with code -1073740791.
Press any key to close this window . . .

Provide dstorage.h header in C compatible way

Please consider providing dstorage.h header in C compatible way.
Whole Direct3D12 API can be accessed from C just fine as COM declarations are properly generated in Windows SDK.
Please consider doing the same. Windows SDK headers provide macros that makes writing COM interfaces compatible with C and C++ code very easily.
This will help not only C developers but will also make interfacing from other languages more obvious as C has guarantees about ABI. But in C++ it is a mess.

Don't make same mistakes as Direct2D and DirectWrite teams did: https://devblogs.microsoft.com/oldnewthing/20220113-00/?p=106152

The Direct2D header files are generated by a custom tool, not by the MIDL compiler. The Direct2D team regret this decision,

Publish Bulk Load Demo as compiled release for x64 and ARM (AvocadoMark)

Please can the Bulk Load Demo sample be released as a binary in Github for many of us who are not experienced with C++ and only want to run the application locally? (without the source code)

  • We simply would like to download it as a binary and run the Avocado demo with default pre-sets as a basic benchmark.
  • It would be useful if the results are automatically traced to a log file after each iteration.
  • The BulkLoadDemo is often shared as screenshots by enthusiasts after Benchmarking a graphics card but it currently does not include the Device Name and Model in the header. This would be helpful while comparing two screenshots side by side.

image

As a .NET Developer with limited experience with C++ I was unable to compile the Sample solution in Visual Studio 2022 17.5 and 17.6 Preview 2.0.

Previously I was able to drop in the missing Avocado.marc file into the Release directory (from 3rd party) and then compile and the test application would work. Currently we have to browse the internet for an unofficial compiled version.

image

GDeflate documentation lacks instructions or references for nuget.exe prerequisite

After cloning the repository and following the instructions to open the GDeflate directory as a local folder in Visual Studio 2022, the initial CMake configuration fails with this message:

1> [CMake] -- Check for working CXX compiler: C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Tools/MSVC/14.32.31326/bin/Hostx64/x64/cl.exe - skipped
1> [CMake] -- Detecting CXX compile features
1> [CMake] -- Detecting CXX compile features - done
1> [CMake] 
1> [CMake] Process failed because: The system cannot find the file specified
1> [CMake] 
1> [CMake] for command: NUGET_EXE-NOTFOUND install -Source https://api.nuget.org/v3/index.json Microsoft.Direct3D.DirectStorage -Version 1.2.2 -ExcludeVersion -OutputDirectory D:/src2/DirectStorage/GDeflate/build/Windows/Debug/packages 
1> [CMake] -- Configuring done
1> [CMake] -- Generating done
1> [CMake] -- Build files have been written to: D:/src2/DirectStorage/GDeflate/build/Windows/Debug

Per this page: https://www.nuget.org/downloads , while NuGet is bundled with Visual Studio, the nuget.exe CLI program is not, so this doesn't appear to be a problem of VS being misconfigured. (In my installation, both NuGet components are installed and working otherwise.)

If NuGet CLI isn't installed somewhere that CMake can find it, then the build will fail because it won't fetch the DirectStorage package and dstorage.h will be missing.

Minor Linux build issues

There are case-sensitive filename mismatches in the CMake file:
3rdParty should be "3rdparty" and "Config.h" should be "config.h".

gcc 9.4 rejects using the same name for an enum class and a corresponding struct member:
GDeflateDemo/main.cpp:62:15: error: declaration of ‘Operation Options::Operation’ changes meaning of ‘Operation’

I will submit a pull request that fixes these.

Querying runtime support level

When deploying apps and getting telemetry, it's critical to be able to "query the caps" of the DirectStorage queue and file once created. Are the telemetry numbers from a fast path of NVMe PCIe 4.0 to vidmem, or is this NVMe to sysmem to vidmem? Or is this even an hdd with DirectStorage as a compat layer? There's no way to tell in the current API.

Memory stomp due to libdeflate_gdeflate_compress_bound returning too small of a value and libdeflate_gdeflate_compress ignoring the output limit

While running some tests, GDeflateDemo crashed due to stack corruption. Upon testing, it turns out that this was due to libdeflate_gdeflate_compress writing more data than libdeflate_gdeflate_compress_bound indicated was the upper limit.

Reproduction steps:

  • Extract "gdeflatecrash.bin" from the attached file
  • Compile GDeflateDemo in debug mode so stack corruption checks are enabled
  • Run GDeflateDemo /compress gdeflatecrash.bin .

gdeflatecrash.zip

Explicit upload heap management

I'd like to create queues with an explicit upload heap provided that I allocate and control. I understand I'll be giving up the heap and its entire VA space to the queue, but right now to do accounting for this heap and its VA range (for, say, Aftermath / DRED post mortem debugging) I need to wrap the entire D3D12 device uses a-la Reshade then capture all upload heaps going out.

This is far from ideal and it makes the road to stable, high performance apps much higher friction than needed.

Improve metadata annotations

It's great to have winmd metadata available 🎉 but a few type annotations are missing.

IDStorageFactory::SetDebugFlags::flags should be DSTORAGE_DEBUG. And IDStorageQueue has non-optional output pointers, that don't seem to be properly represented in the metadata and cause windows-rs to generate a by-mutable-reference getter rather than allocating and returning the object.

All of that is solved with the following mapping.

--memberRemap
IDStorageFactory::SetDebugFlags::flags=[AssociatedEnum("DSTORAGE_DEBUG")]
IDStorageQueue::RetrieveErrorRecord::record=[RetVal]
IDStorageQueue::Query::info=[RetVal]

Tsukisoft/direct-storage-rs@6a7f8c5

Wait for file-to-memory IO

It seems that there's no way to WaitFor*() the completion of IO DSTORAGE_REQUEST_DESTINATION_MEMORY requests made on a queue with no D3D12 device. With DirectStorage being a simple, efficient way of saturating NVMe to system memory bandwidth, is there a plan to support this use case not involving a D3D12 device?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.