> 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
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?
This and also due to the fact that positions that involve writing and managing documentation typically do not have great paths for promotions.
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.
Many of those sites, incredible for a $4 trillion valued company, are managed by teams themselves on their own infra, thus when there is one of those restructuring rounds that big corps love doing almost every year, some of that gets lost.
I really wish DX would go back to have a proper installable SDK with headers, libs, tools, integrated documentation and example code instead of those things being scattered across the Windows SDK and half the internet (and then half of the links becoming stale).
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:
Basically all native libraries inevitably have bad or difficult to follow documentation like this, proprietary or open source. Vulkan is the exception as it's a standard so needs to be very clear so all stakeholders can implement it correctly.
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.
Vulkan spec is missing tons of stuff. Implementers check they pass the conformance tests (tho those also miss stuff)
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
I'm sure it misses stuff, but generally a 'spec' is better than a 'doc' for the reason that you need enough info to at least guess how a spec is implemented, whereas a doc can leave everything out and as long as the programmer has headers and some examples they can probably do 90% of what is needed.
Extensions to Khronos standards are hardly that greatly documented.
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.
> Vulkan is the exception as it's a standard so needs to be very clear so all stakeholders can implement it correctly.
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).
I want to point out that the DirectX 12 Discord is a great place to get help , it also covers PIX. Yeah, I know - it's not indexed but the regular web search but nevertheless it has a lot of good information and experts from industry and Microsoft that can be quite helpful.
> 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
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?
Microsoft does this all the time, and it reeks of a lack of continuity or ownership internally.
This and also due to the fact that positions that involve writing and managing documentation typically do not have great paths for promotions.
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.
Many of those sites, incredible for a $4 trillion valued company, are managed by teams themselves on their own infra, thus when there is one of those restructuring rounds that big corps love doing almost every year, some of that gets lost.
Every few years they break all links to The Old New Thing. There is no job Microsoft can't botch.
Yup I also enjoyed that time when they replaced everyone's usernames with their hidden emails on that blog.
"continuous development & adaption at a high paced environment"
;-)
I really wish DX would go back to have a proper installable SDK with headers, libs, tools, integrated documentation and example code instead of those things being scattered across the Windows SDK and half the internet (and then half of the links becoming stale).
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:
https://microsoft.github.io/DirectX-Specs/
Basically all native libraries inevitably have bad or difficult to follow documentation like this, proprietary or open source. Vulkan is the exception as it's a standard so needs to be very clear so all stakeholders can implement it correctly.
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.
Vulkan spec is missing tons of stuff. Implementers check they pass the conformance tests (tho those also miss stuff)
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
I'm sure it misses stuff, but generally a 'spec' is better than a 'doc' for the reason that you need enough info to at least guess how a spec is implemented, whereas a doc can leave everything out and as long as the programmer has headers and some examples they can probably do 90% of what is needed.
Extensions to Khronos standards are hardly that greatly documented.
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.
And the red book isn't that good either.
> Vulkan is the exception as it's a standard so needs to be very clear so all stakeholders can implement it correctly.
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:
https://microsoft.github.io/DirectX-Specs/
A great deal of effort which will be help to someone... Assuming search engines provide it as a result to that industrius soul
I want to point out that the DirectX 12 Discord is a great place to get help , it also covers PIX. Yeah, I know - it's not indexed but the regular web search but nevertheless it has a lot of good information and experts from industry and Microsoft that can be quite helpful.
Eh I'm sticking with GLES 2 until this little GPU craze dies down