DirectX-Headers: the D3D12 headers under an MIT licence

The same headers, a different licence

The DirectX-Headers repository hosts the official Direct3D 12 headers, and the point of the repository is stated in the first paragraph: these headers are made available under the MIT licence rather than the traditional Windows SDK licence.

That is a bigger deal than it first appears. The D3D12 API itself is not changing here, the declarations are the official ones, and the repository is the same source Microsoft uses internally. What changes is the permission set. MIT is a short permissive licence with an attribution requirement, whereas the Windows SDK licence carries its own conditions. For a team that wants to vendor the headers into a build, ship them in a container, or mix them with other permissively licensed code, that difference decides whether the headers can be included at all.

The repository also hosts several helpers for using these headers, and the project points to the DirectX landing page as the place for more resources for DirectX developers.

The primary language is C, the licence is MIT, the default branch is main, and the last push was on 2026-10-14. The topic list includes d3d12, directx, directx12 and wsl, which is a fair summary of what the repository covers.

The release history shows the version scheme in use. The listed tags are v1.619.5 from 2026-07-31, v1.721.2-preview from 2026-07-08 and v1.619.4 from 2026-07-08, so the numbers track the graphics driver and DirectX release rather than a simple semantic version.

The directory layout tells you what each part is for

The README's directory structure section is compact and each entry has a specific job.

The root holds the build files, and it is explicit that CMake is provided, referenced either via `subdirectory()` or after installation to a system location, and that Meson is also available for inclusion as a subproject or wrap. Alongside the build files are `CMakeLists.txt`, `CMakePresets.json`, `meson.build` and `meson_options.txt`, and an `Android.bp` file for the Android build system, which is how the headers can be consumed in an Android tree.

The `/include/directx` directory holds the core headers for using D3D12, plus `d3dx12.h`, which is a helper and does not cross the boundaries of the D3D12 API. That distinction is worth holding on to. `d3dx12.h` is convenience code that sits on top of the API rather than being part of it, so a project that wants a strict API surface can take the core headers without the helper.

`/include/wsl` is provided as a shim to be able to include the D3D12 headers from a Linux build environment without requiring the rest of the Windows SDK. `/include/dxguids` allows an application to use `uuidof<T>()` consistently between Windows and WSL instead of `__uuidof()`, and `/src/dxguids.cpp` is a C++ file that can be used as a replacement for linking against `dxguid.lib` on Windows, and as a convenient translation unit to define GUIDs without multiple definitions for WSL.

The `/test` directory holds simple CMake and Meson projects for validating that the headers can be included in a given environment, which is a practical way to check your own toolchain before wiring it into a larger build.

The repository also carries `googletest/` and a `SECURITY.md`.

Include order decides which definitions win on Windows

The section on use on Windows is the one warning every user needs, and it is easy to get wrong because the failure is silent.

These headers may conflict with the headers from the Windows SDK, depending on include ordering. The headers from this repository should be added to the include directory list before the SDK, and should be included before other graphics headers such as `d3d11.h` from the Windows SDK.

The reason is include guards. The SDK headers and these headers define the same guard names, so whichever one is reached first defines the guard and the other becomes a no-op. If the SDK version is included first, it wins, and your code compiles against the SDK declarations without any error to tell you so. The bug is not a compile failure, it is a compile that succeeds against the wrong source, which is the harder kind to notice.

So the rule is concrete and it has two parts. Put this repository's include directory ahead of the Windows SDK include directories in your include path, and include these headers before any other graphics header you pull from the SDK.

The alternative, which is what the Windows SDK route effectively is, is to accept the SDK's licence terms and use the SDK's copies. That is the right answer for a project that already depends on the SDK for D3D11 or for other components, since mixing the two sets is what creates the conflict in the first place. This repository earns its place when you want D3D12 specifically, or when you want the SDK out of the picture for licensing or build reasons, or when you are building on WSL where there is no SDK at all.

WSL is a supported route with two deliberate ABI deviations

The WSL story is where this repository is genuinely different from a plain header dump, and it comes with a warning attached.

First, the scope. WSL support is not intended for general purpose application development. At this time, the only recommended usage is for frameworks wishing to provide hardware acceleration for a Linux graphics or compute API in a WSL2 virtualization environment. So the intended user is a framework author, not an application developer. WSL support is also only available for 64-bit binaries.

Second, the ABI. The headers in the `/include/wsl` directory provide alternative definitions to macros and typedefs normally found in the Windows SDK, and for the most part they are straightforward, but two are called out:

| Type | Reason | |---|---| | `LONG`/`ULONG` | On 64-bit Windows, a `long` is 4 bytes, but on Linux it is typically 8 bytes. The D3D12 ABI for WSL uses `long` and therefore these should be 8 bytes. | | `WCHAR`/`WCSTR` | On Windows, a `wchar_t` is 2 bytes, but on Linux it is typically 4 bytes. The D3D12 ABI for WSL uses the native 4-byte `wchar_t`, to enable applications and the runtime to use the system C library to perform string manipulation. |

The `wchar_t` case has a visible consequence. Because the ABI uses the native 4-byte `wchar_t` on Linux, applications and the runtime can use the system C library to perform string manipulation, which is convenient on Linux and would be wrong on Windows.

There is a third deviation, in how handles are passed. APIs taking `HANDLE`, which is `void*`, for Win32 types should instead use `reinterpret_cast<HANDLE>(fd)` for an appropriate type of file descriptor. For `ID3D12Fence::SetEventOnCompletion` the descriptor should be an `eventfd`, and for shared resources it will be an opaque fd. So a WSL port has to translate the Win32 handle conventions, and the documentation is specific about the translation.

Seven ways to consume the same headers

The README lists various ways to consume the headers, and the list is a good map of how the project fits into different build systems.

The manual route is to copy the headers somewhere and point your project at them. The CMake subproject route is to add this entire project as a subdirectory of your larger project, for example as a git submodule, and `add_subdirectory` into it, using the resulting `DirectX-Headers` and `DirectX-Guids` targets as a link dependency. The installed CMake route is to build and install the project so that CMake's `find_package` functionality finds it, which exposes the same two targets.

For newer CMake there is FetchContent, available from CMake 3.11 onwards, which fetches the library using Git and adds it to your project. Meson users can add the project as a subproject and use `subproject` or `dependency` to consume it, and Pkg-config is supported by building with Meson, after which the installed package can be found via pkg-config.

Beyond the build systems there are two package channels. A vcpkg port has been added, at the microsoft/vcpkg repository under ports/directx-headers, which is the path most Windows C++ projects will take. And there is NuGet, where the DirectX 12 Agility SDK can be downloaded from NuGet.org as `Microsoft.Direct3D.D3D12`, with a getting started guide for the Agility SDK on the DirectX developer blog.

The two exported targets, `DirectX-Headers` and `DirectX-Guids`, reflect the split in the repository between the header set and the GUID translation unit, and they are what every one of the automated routes exposes.

The README notes that contributions for new mechanisms are welcome, which is an invitation to add build or packaging support rather than to change the API declarations.

Against the Windows SDK and against hand-writing your own interfaces

The comparison worth making is not with another header repository but with the two ways to get D3D12 declarations without this one.

The first is the Windows SDK, which is the traditional route and remains the right one for most Windows projects. It gives you the headers along with the rest of the SDK, which includes the tooling, the libraries and the samples that go with Direct3D, and its licence terms are what they are. Choosing this repository over the SDK is a decision to decouple D3D12 from the rest of the SDK, and the reasons are licensing, build weight, or the fact that you are on WSL and there is no SDK.

The second option is to declare the interfaces yourself. Some projects do this to avoid a dependency on any vendor headers at all, hand-writing the small subset of D3D12 interfaces they call. That is a large amount of error-prone work for a large API, and it locks you out of every part of D3D12 you did not hand-declare, including features added in later graphics driver releases. The version numbering of these headers, tracking the DirectX and driver release, is the argument against pinning a hand-written subset.

The third consideration is that these headers are the official ones, so behaviour matches the runtime. Any difference between what a header declares and what the Direct3D 12 runtime expects is a bug in the runtime, not something you would want to reproduce by using a different declaration.

The one thing this repository cannot do is reduce the amount of D3D12 you have to learn. The headers remove a licensing and packaging problem, not an API complexity problem, and the interface surface in the core headers is exactly as large as the SDK's.

Editorial conclusion

Adopt DirectX-Headers when you need the D3D12 API and either do not want the Windows SDK licence terms or are building for WSL2, where the /include/wsl shim is the only supported route. Do not adopt it as a drop-in replacement for the SDK headers in a project that also uses other D3D headers, because the SDK versions define the include guards first and win, and check first that your include path lists these headers before the Windows SDK, since that ordering is what decides which definitions your code actually compiles against.

Frequently asked questions

Official sources

1. License: MIT
2. microsoft/DirectX-Headers on GitHub
3. Project website
4. README
5. Releases