At least making the functional spec public was a massive step forward, this is much more useful than the actual API documentation, and also better than the documentation/specifications for most other 3D APIs:
Only reason I need to use DX12 is because the swapchain uses DXGI textures. I hope Microsoft gives NVIDIA great priority and leverage to use CUDA native textures at the swapchain directly in Windows.
DX12 functions ported directly into CUDA will be a big plus, programming stack is literally next to the NVIDIA hardware, do everything under one language and don't need to mess with two language interoperability.
While you're at it, do you also not know why they break the URLs from time to time so that you can't follow old guides because they point to empty pages?
Usually I find if you're using an open source library you need the whole source checked out for reference, better than proprietary libraries where you need to pay and sign an NDA to get that access or equivalent support.
Lol... while the Vulkan documentation situation is a lot better than OpenGL it's not any better than the documentation of other 3D APIs, especially when trying to make sense of extensions (which depend on other extensions, which in turn depend on other extensions - once you're at the end of the breadcrumb trail you already have forgotten what the original question was).
D3D has a 'functional spec' here which provides a lot more under-the-hood information than what's available on https://docs.vulkan.org/spec/latest/index.html:
A TXT dump of the proposal, with luck a sample from the GPU vendor, and that is all.
Vulkan was famously badly documented, one only has to go to LunarG yearly reports regarding community feedback on Vulkan, and related action points.
OpenGL 4.6 never has had a red book editon, Vulkan only had a red book for 1.0, OpenCL and SYSCL just have the PDF reference, not all Khronos APIs have a cheatsheeet PDF on Khronos site.
directx also has conformance tests.
The directx specs are arguably better in many ways than the vulkan specs. They go into bit level details how various math is required to work, especially in samplers
Not just at Microsoft, but it's an entire industry issue. It's not a job most Software companies value, so ambitious people constantly leave for better positions and the jobs constantly get moved around to the cheapest cost center where ownership and knowledge gets lost and quality declines.
;-)
Tue
25
Nov 2025
Every API needs documentation. Even more so in the case of a graphics API, where there is no single implementation (like in the case of a specific library), but countless users of the API (video games and other graphics apps) and several implementers on the other side of the API (graphics drivers for GPUs from various vendors like AMD, Intel, and Nvidia).
Vulkan documentation, for example, is very extensive, detailed, and precise. Sure, it is not perfect, but it's getting better over time. It's also very formal and difficult to read, but that's how a reference specification should be. For learning the basics, third-party tutorials are better. Documentation is needed for more advanced, day-to-day work with the API. I like to think of the documentation as law. A software bug is like a crime. When the application crashes, you as a programmer are a detective investigating "who killed it". You check the specification to see if the app "broke the law" by using the API incorrectly - meaning your app is guilty of the bug - or whether the usage is correct and the culprit is on the other side: a bug in the graphics driver. There are, of course, some gray areas and unclear situations as well.
Direct3D 12, unfortunately, doesn't have just one main documentation. In this post, I would like to gather and describe links to all official documents that describe the API... and also complain a bit about the state of all this.
1. Direct3D 12 programming guide @ learn.microsoft.com
This looks like the main page of the D3D12 documentation. Indeed, we can find many general chapters there describing various concepts of the API, as well as the API reference for individual interfaces and methods. For example:
ID3D12Device, ID3D12Device1, ..., 10.D3D12_FEATURE_D3D12_OPTIONS20, but it links only to documentation up to the D3D12_FEATURE_DATA_D3D12_OPTIONS11 structure. By manually changing the URL, I found the documentation of 12 and 13 as well, although they look quite empty or “TBD”. At the same time, the latest Agility SDK already defines option structures up to version 21.But there are also hidden gems - sections that, in my opinion, deserve separate pages, yet are buried inside the documentation of specific API elements. For example:
2. Direct3D 11.3 Functional Specification
The documentation linked in point 1 is not fully complete. Direct3D 12, although revolutionary and not backward-compatible, still builds on top of Direct3D 11 in some ways. For that older API, there is this one long and comprehensive document. Sometimes you may need to resort to that specification to find answers to more advanced questions. For example, I remember searching it to find out the alignment requirements for elements of a vertex or index buffer. Be aware through that the parts of this document that apply to D3D12 are only those that D3D12 documentation doesn't define, and that are applicable to D3D12 at all.
3. github.com/microsoft/DirectX-Specs
On the other hand, recent updates to DirectX 12 are also not included in the documentation mentioned in point 1, as Microsoft now puts their new documents in a GitHub repository. You can find .md files there describing new features added in newer versions of the DirectX 12 Agility SDK - from small ones like ID3D12InfoQueue1, to very large ones like DirectX Raytracing (DXR) or Work Graphs. This repository also provides pages describing what's new in each shader model, starting from 6.0, 6.1, 6.2, etc... up to 6.8 (at the moment I’m writing this post). A convenient way to read these docs is through link: microsoft.github.io/DirectX-Specs/.
4. github.com/microsoft/DirectXShaderCompiler/wiki
Then there is the HLSL shader language and its compiler: DXC. Microsoft also maintains documentation for the compiler and the shader language in a separate GitHub repo, this time using the GitHub Wiki feature. There, we can find descriptions of language features like 16 Bit Scalar Types, what's new in each major HLSL language version (2015, 2016, ..., 2021 - see Language Versions), and... again a list of what has been added in recent shader models (see Shader Model).
5. github.com/microsoft/hlsl-specs
When it comes to the HLSL language itself, it’s sometimes hard to tell what code is correct and supported, because there is no fully formal specification like there is for C++, for example. There is only the High-level shader language (HLSL) section of the documentation mentioned in point 1, which briefly describes elements of the syntax. However, Microsoft recently started writing new documentation for HLSL, which can be found in yet another GitHub repository that is most convenient to read online at microsoft.github.io/hlsl-specs/.
I should also mention the DirectX Developer Blog, which is worth following for the latest news about new releases of the Agility SDK and recent additions to the API, as well as updates on related projects like PIX, DirectStorage, and DirectSR (which is pretty much dead now - it was removed from the preview Agility SDK before reaching the retail version). The blog also features nice standalone articles, such as Getting Started with the Agility SDK or the HLSL 2021 Migration Guide, which could easily be part of the main documentation.
As one example I stumbled upon just last week: the description of ByteAddressBuffer at learn.microsoft.com mentions that it has methods Load, Load2, Load3, Load4 that read uint values from a buffer. But to learn that modern HLSL versions also support templated Load<MyType>, I had to go to a separate document ByteAddressBuffer Load Store Additions on the DirectXShaderCompiler Wiki - which describes only that specific addition.
What a mess! Why is the DirectX 12 documentation so scattered across so many websites in different shapes and forms? Of course, I don't know - I don't work at Microsoft. But having worked at big companies for more than 10 years, it isn’t shocking to me. I can imagine how things like this happen. First, engineering managers, project/program managers, and other decision-makers tend to focus on adding new features (everyone wants to “build their pyramid”) while also moving quickly and cutting costs. Creating good documentation is not a top priority. Then, there is Conway’s Law, which states that “Organizations which design systems are constrained to produce designs which are copies of the communication structures of these organizations.” So if there are separate teams developing DXC, the Agility SDK, etc., they will likely want their own outlets for publishing documentation, while no one takes responsibility for the overall user experience. Still, seeing new initiatives like the HLSL specification, I’m hopeful that things will get better over time.
Finally, DirectX Landing Page is also worth mentioning, as it gathers links to many SDKs, tools, helpers, samples, and other projects related to DirectX.
Copyright © 2004-2026