Fortunate
25
november 2025
Every API requires documentation. Even more so in the case of graphics APIs, where there is no single implementation (as in the case of a specific library), but countless users of the API (video games and other graphics apps) and numerous implementers on the other side of the API (graphics drivers for GPUs from different vendors like AMD, Intel, and Nvidia).
For example, the Vulkan documentation is very comprehensive, detailed, and accurate. Sure, it’s not perfect, but it’s getting better with time. It’s very formal and hard to read, but that’s how the reference specification should be. To learn the basics, third-party tutorials are better. More advanced, everyday work with the API requires documentation. I like to think of documentation as law. Software bug is like a crime. When the application crashes, as a programmer you are a detective investigating “who killed it”. You check the specification to see if the app has “broken the law” by misusing the API – meaning your app is guilty of a bug – or whether the usage is correct and the culprit lies on the other side: a bug in the graphics driver. Of course, there are also some gray areas and unclear situations.
direct3d 12Unfortunately, there is not just one main document. In this post, I would like to collect and describe links to all the official documents describing the API… and also complain a little about the state of it all.
1. Direct3D 12 Programming Guide @ learn.Microsoft.com
This is what the main page of the D3D12 document looks like. Indeed, we can find there several general chapters describing various API concepts as well as API context for individual interfaces and methods. For example:
- The page Specifying route signatures in HLSL provides a good, self-contained and complete description of the HLSL syntax for defining route signatures (for more information about route signatures, see my older post: Sizes and Forms of DX12 Route Signatures).
- It also describes new updates to the API, such as the ID3D12Device10 interface, as well as all previous interfaces:
ID3D12Device, ID3D12Device1, ..., 10, - In addition to the API, this website also hosts a documentation of the HLSL language, for example, the page Internal Functions listing the available internal functions.
- The page Shader Model vs Shader Profile and its sub-pages describe what has been added to the shader model up to 6.0 and down to 1.0, which is more than 20 years old in DirectX 8 or 9.
- However, not all API elements are documented. For example, the D3D12_FEATURE calculation mentions “options” structures.
D3D12_FEATURE_D3D12_OPTIONS20But this only links to the document up to the structure D3D12_FEATURE_DATA_D3D12_OPTIONS11. By manually changing the URL, I also found document 12 and 13, although they appear to be fairly blank or “TBD”. Also, the latest Agility SDK already defines option structures up to version 21.
But it also has hidden gems – sections that, in my opinion, deserve separate pages, yet buried inside the documentation for specific API elements. For example:
2. Direct3D 11.3 Functional Specification
The document linked in point 1 is not completely complete. Direct3D 12, although not revolutionary and backward-compatible, still sits on top of Direct3D 11 in some ways. For that old API, it’s a long and extensive document. Sometimes you may need to resort to that specification to find answers to more advanced questions. For example, I remember searching for it to find out the alignment requirements for elements of a vertex or index buffer. Be aware that the parts of this document that apply to D3D12 are only those that the D3D12 documentation does not define, and they apply 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 keeps its new documentation in the GitHub repository. You can find .md files there that describe new features added in new versions of the DirectX 12 Agility SDK – from small files like ID3D12InfoQueue1 to very large files 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 the 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 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’s been added to recent shader models (see shader models).
5. github.com/Microsoft/hlsl-specs
When it comes to the HLSL language, it is sometimes difficult to tell which code is correct and supported, because there is no complete formal specification like C++, for example. There is only the High-Level Shader Language (HLSL) section of the document mentioned in point 1, which briefly describes elements of the syntax. However, Microsoft has recently started writing new documentation for HLSL, which can be found in another GitHub repository that is most convenient to read online at microsoft.github.io/hlsl-specs/.
- Specifically, there is the PDF document: High-Level Shader Language Specification which is already quite long but is still incomplete and has been marked as “working draft” for several months.
- Interestingly, the repo also contains proposals – documents describing language features that are planned and may or may not be accepted into the language in the future. I appreciate such open development of new features!
6. DirectX Developer Blog
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 now largely dead – it was removed from the preview Agility SDK before reaching the retail version). The blog also has good standalone articles, like Getting Started with the Agility SDK or the HLSL 2021 Migration Guide, that could easily be part of the main document.
As an example, I just found out last week: The description of ByteAddressBuffer on learn.Microsoft.com mentions that it has the methods Load, Load2, Load3, Load4 he read uint Value from buffer. But be aware that modern HLSL versions also support templates. LoadI had to go to a separate document ByteAddressBuffer Load Store Additions on the DirectXShaderCompiler Wiki – which only describes that specific addition.
what a mess! Why is DirectX 12 documentation so scattered across so many websites in various shapes and formats? Of course, I don’t know – I don’t work at Microsoft. But after working in large companies for over 10 years, this isn’t shocking to me. I can imagine how things like this happen. At first, engineering managers, project/program managers, and other decision-makers focus on moving faster and cutting costs as well as adding new features (everyone wants to “build their pyramid”). Creating a good document is not a top priority. Then, there is Conway’s Law, which states that “Organizations that design systems are obliged to produce designs that are copies of the communication structures of these organizations.” So if there are separate teams developing DXC, 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, the DirectX landing page is also worth mentioning, as it collects links to many SDKs, tools, helpers, samples and other projects related to DirectX.
Comments | #directx
share
<a href