Well, I decided to make a DirectX 12 quick reference guide... The main issue is dealing with page formatting. It's not just about some MS crazy nomenclature like VPAndRTArrayIndexFromAnyShaderFeedingRasterizerSupportedWithoutGSEmulation (one of the best feature of D3D12 though), simply I never wrote such type of document. Currently I am using notepad++ for raw text data and InDesign for the layout and formatting..
I am using the Vulkan quick reference guide as reference.
Here I attach a sample draft, it doesn't have final colours, annotation and structures are missing; but I would like to receive some feedbacks and tips about it, especially on layout and text organization.
I noted that current font sizes are enough good for printing but terrible on non-high density screens. I also would like to know if you have a better model to use as reference (for both layout and text grouping and organization). Finally, are external url or internal links useful for you?
Thank you
UPDATE: it is now on github, RAW data included: https://github.com/alessiot89/D3D12QuickRef/
Writing a quick reference guide
I've uploaded a new draft, hopefully someone will give me some feedbacks, because this "thing" is requiring more time I imaged.
Some notes: structures and enumeration are still missing as a proper annotation.
Oh well, I did not know where post this, since it is not really about coding... Let's move then!
It looks pretty organized and good readable.
Maybe you can add some 'basic startup guide' as reference, describing how you can create a d3d12 device, swapchain, basic resource, 3 vertices and a triangle and draw it to the backbuffer and then flip to screen.
Thank you.
I am most concerned about placing the functions in the right section.
Actually, I am re-drawing some diagrams (interface hierarchies, pipelines) since those are on MSDN are low-res, and next I will add the structures and enumerations.
The basic startup guide is good idea, I will add a final section containing useful references and links too. But first, I need to add all missing structures and enumerations, which are lot. I am also not sure about the formatting, since reading on a screen look not so much comfortable.
- Inconsistent use of DirectX / Direct3D.
- GetDeviceRemovedReason is in the wrong font
- GetGPUVirtualAddress and GetGPUDescriptorHandleForHeapStart don't really belong under Command List Creation
- "Graphics root signature set-up" and "Compute root signature set-up" should probably be called "Graphics/Compute root constant setting". Those functions don't setup the root signature.
- "Enables some scene-traversal and culling to be moved from the CPU to the GPU." as a description of Indirect Drawing is needlessly use-case specific and doesn't really explain what ExecuteIndirect does.
- I'd re-order the sections so Heap creation came before View creation
- "A descriptor heap is a collection of contiguous allocations of descriptors, one allocation for every descriptor" - I'd reword that to not use the word "allocation" in bold. It makes it sounds like there's a memory allocation for each descriptor which there isn't, it's one allocation large enough to contain many descriptors.
- "ID3D12Resource::GetDesc" doesn't belong under Heap Creation.
- "ID3D12Device::CreatePlacedResource" doesn't belong under Heap Creation
- "mesure" -> "measure"
- GetCurrentBackBufferIndex doesn't belong under "Resizing"
- [Speculation] Does SetMaximumFrameLatency have any relevance on D3D12? How many frames of data buffered up on the CPU would seem to be under application control already. I'm not sure what this function would/could do on D3D12.
Thank you, m'lord.
This is why I was concerned about ordering (that's the price using plain txts I guess).
- GetGPUVirtualAddress and GetGPUDescriptorHandleForHeapStart don't really belong under Command List Creation
Yeah, a subsection called "helpers", maybe under the resources, after descriptor heap creation may be more appropriate.
- "Graphics root signature set-up" and "Compute root signature set-up" should probably be called "Graphics/Compute root constant setting". Those functions don't setup the root signature.
- "Enables some scene-traversal and culling to be moved from the CPU to the GPU." as a description of Indirect Drawing is needlessly use-case specific and doesn't really explain what ExecuteIndirect does.
- I'd re-order the sections so Heap creation came before View creation
- "A descriptor heap is a collection of contiguous allocations of descriptors, one allocation for every descriptor" - I'd reword that to not use the word "allocation" in bold. It makes it sounds like there's a memory allocation for each descriptor which there isn't, it's one allocation large enough to contain many descriptors.
Got it.
- "ID3D12Resource::GetDesc" doesn't belong under Heap Creation.
Yep, another helper function for resources.
- "ID3D12Device::CreatePlacedResource" doesn't belong under Heap Creation
I will move it to resource creation. Better: sub-allocation.
- GetCurrentBackBufferIndex doesn't belong under "Resizing"
Yes, that's more concerned with presentation and frame buffers rotation. -> Synchronization.
- [Speculation] Does SetMaximumFrameLatency have any relevance on D3D12? How many frames of data buffered up on the CPU would seem to be under application control already. I'm not sure what this function would/could do on D3D12.
SetMaximumFrameLatency works with D3D12 (but not with Direct3D 11 on 12 AFIK). Intel made a very nice sample showing how to take advantage of D3D12 flip model: https://software.intel.com/en-us/articles/sample-application-for-direct3d-12-flip-model-swap-chains
Ok I did some correction and added schemas of D3D12 and DXGI interface hierarchies, and one of the graphics pipline (yes, I know they have different scales!... for now)
If the order of the content is acceptable I will add proper types (structs, enums), constants, proper colours, fix a lil layout formatting, add some extra comments etc..
EDIT: also, still need to investigate about d3d12 content protection support
just want to say, Allesio, this is a very helpful reference guide your writing, its nice to have everything in one place, and its organized nicely and easy to read