# Superseded by #70315.
---
## Direct3D 12 Rendering Driver (via SPIRV-Cro…ss + DXC)
 
This is a feature-complete Direct3D 12 RenderingDevice implementation for Godot Engine. It works as a drop-in replacement for the Vulkan one. It is selectable in the project settings as an alternative to use on Windows.
By supporting Direct3D 12, Godot gains support for multiple new platforms, such as:
* Windows Store (UWP).
* Windows on ARM.
* GDK.
* XBox —which can't be supported officially by Godot, but for which Direct3D 12 support is essential—.
This PR includes some preparatory changes, to uncouple the `RenderingDevice` from Vulkan, that is, abstracting the modern Godot rendering architecture from whatever rendering API is used. Moreover, instead of a monolithic commit, the code of the driver itself is split into three, much more manageable commits.
## Highlights
### Performance
Depending on the complexity of the scene, effects used, etc., this first version of the renderer performs generally worse than the Vulkan one. In some tests, D3D12 has not been able to deliver more than 75% of the Vulkan frames per second. In some other, D3D12 has been able to outperform Vulkan by a small margin. Performance improvements will be ironed out over time.
### Homogeneity
The D3D12 rendering driver has been written taking the Vulkan one as a basis and keeping as much as possible from the original. This effort gives two-fold benefits: on the one hand, the overall structure of the code files, including auxiliary structures and other elements, is very similar, which makes maintenance easier; on the other hand, both renderers are more similar at the functional level. An example of this is that the D3D12 renderer will be as picky as the Vulkan one when it comes to validation and error checking, even in areas where the Microsft API wouldn't impose such strict constraints.
### Specialization Constants
In Vulkan it is possible to create multiple variations of a pipeline with different values for certain parameters that end up as compile-time constants in the shader generated under the hood. Those parameters are called specialization constants.
In Direct3D there's no counterpart of that mechanism. However, Godot rendering relies on it for some of its shaders. A way to have specialization constants in the Direct3D/DXIL world had to be researched. It was finally found and is used in this code. The technique is explained in this Twitter thread: https://twitter.com/RandomPedroJ/status/1532725156623286272.
### Code Comments
To avoid making this PR description unnecessarily long, the reader is advised to find additional insight in the comments.
### Assertions
Given that some data crosses many stages from its inception to where it's finally used, the code is full of dev-only checks ensure the sanity of many different data structures at different points in time. The expectation is that this will make easier to catch bugs —even subtle ones— in areas of high complexity.
## Known Issues
- **Multiview rendering does not work.** Only the left eye is rendered.
- **SDFGI glitches on AMD GPUs.** At least, it does on integrated AMD Radeon. Deep investigation led to the finding that it's a bug in some third-party element — e.g. the Radeon driver, Direct3D or the DirectX Shader compiler. The clue is that graphics debugging tools show the pipeline status as if some of the needed bindings hadn't been set. Moreover, the affected shaders work fine if compiled with optimizations disabled.
- **No MinGW supported.** So far only building with MSVC works, due to some vendor-specific stuff in third-party code.
## Compilation & Distribution
- Grab the (main, not PDB) .zip file corresponding to the 1.7.2207 version of the DirectX Shader Compiler from https://github.com/Microsoft/DirectXShaderCompiler/releases.
- Unzip the file to some path.
- Optional (only for developers wanting to debug graphics with the PIX tool, only for debug builds):
- Locate the WinPixEventRuntime package (version 1.0.220810001 is the latest tested), at https://devblogs.microsoft.com/pix/download/. You’ll be finally taken to a NuGet package page where you can click Download package to get it.
- Change the file extension to .zip.
- Unzip the file to some path.
- Build Godot with the following additional parameters to SCons: `d3d12=yes DXC_PATH=<...>` plus `PIX_PATH=<...>` if you want PIX.
**NOTE:** The build process will copy `dxcompiler.dll` and `dxil.dll` from the `bin/x64/` directory in the DXC zipfile to the Godot binary directory. **D3D12-enabled Godot packages for distribution to end users must include those files, both for the editor and games.**
## Future Work
Besides fixing the known issues described in another section, there are many options for potential improvement, the most important of which are described below. The code also has a number of TODO items that refer to these and other, generally smaller, potential enhancements or nice-to-haves.
### Render Pass API
The D3D12 renderer uses what in the Vulkan world is called dynamic rendering. In other words, it doesn't use render pass —and subpass— APIs. This was done to make things simpler, but came with a couple of downsides.
- First, a lot of code to do the proper setup of rendering passes is avoided, but some of the things the API would do by itself still require an amount of code —operations like clearing or discarding a framebuffer—.
- Second, this mentioned sort of emulation of builtin render subpasses won't perform as well on TBDR hardware because of the performance gains that input attachments provide can't be obtained from manual management of subpasses. This performance limitation only affects the mobile backend, though.
**Actionable item:** Re-work render pass management with the proper APIs, which may be needed to squeeze performance from certain kind of devices.
### Enhanced Barriers
Direct3D 12 was released with a way to synchronize the GPU work consisting in resource barriers. In short, they are not nearly as fine-grained as Vulkan's memory and pipeline barriers are, the biggest consequence of this being comparatively worse performance. Microsoft has later powered Direct3D with the so-called enhanced barriers, which are the same that Vulkan has. Recent GPU drivers and Windows versions already support them.
**Actionable item:** Re-work synchronization based on enhanced barriers, which will give more performance and make the code more similar to the one in the Vulkan renderer.
### More Reasonable Dependencies
Currently, this is using SPIRV-Cross for shader translation to HLSL and an important chunk of DXC for the specialization constants hack. When the Microsoft provided support for DXIL in Mesa is mature —when checked for the purpose of this work it wasn't yet—, we may be able to use it —via NIR— instead of that two other dependencies for those purposes. Microsoft is donating engineer time to Mesa for this effort, so we hope it will be in an usable state soon for us.
**Actionable item:** Watch the status of DXIL in Mesa and replace SPIRV-Cross and the DXC source code as soon as feasible.
### Deprecate Texture Aliasing
In Vulkan it is possible to tell upfront which formats a texture will be interpreted as, and it'll just work. In Direct3D 12 there was traditionally no way to do the same. Therefore, there are limitations on which reinterpretations one can do.
Godot needs to do two of them that are illegal in D3D12: write as `R32` and read as `R9G9B9E5`, and write as `R16` and read as `R4B4G4A4`. The Direct3D 12 renderer code works around that limitation by abusing texture aliases, which, according to some tests across different GPUs, seems to work fine in practice.
The legal approach would be to make copies of the textures when the time to read comes. However, that won't still work for the `R4B4G4A4` case. Therefore, the aliasing workaround is used for every case by now.
Luckily, Direct3D has recently added a new API `CreateCommittedResource3()` that provides the same nicety as Vulkan, but it's still not widely available and, at the time of this writing, the D3D12 Memory Allocator library still doesn't support it (there's a PR, though: https://github.com/GPUOpen-LibrariesAndSDKs/D3D12MemoryAllocator/pull/44).
Thanks go to [Matías N. Goldberg](https://twitter.com/matiasgoldberg), which was of great help in this investigation.
**Actionable item:** Add check support and prefer `CreateCommittedResource3()` to the aliasing hack where possible.
### Further Homogeneity
**Actionable item:** Fuse as much as possible the elements that Vulkan and D3D12 have in common —staging buffer, static arrays of data format names, etc.—. This should reduce the codebase size and make it easier to maintain (and eventually add more platforms).
### More
Just to make it complete, there are a few more potential improvements that may or may not be already in a _TODO_ in the comments:
- Try to assign HLSL bindings manually and inform SPIRV-Cross in a deterministic way. That would make reflection, management of root signature and population of handle heaps simpler and more efficient. (Credit: @reduz.)
- ~More sensible use of the shared heap (i.e., track which resources/samplers are already bound and reuse somehow).~ **Update:** Done.
- Leverage promotion and decay of the state of buffers.
- While still using resource barriers, do split barriering where possible. (Maybe by taking the now neglected `p_post_barrier` parameters as a hint somehow?)
- A way to use the HLSL implementation of `fsr_upscale.h` directly, given the appropriate defines.
- Consider promoting some samplers (`material_samplers`) to static samplers and/or descriptors to root descriptors when possible.
- In case of `D3D12_FEATURE_DATA_ARCHITECTURE` being UMA, use `WriteToSubresource()` instead of `memcpy()`.
- Consider `D3D12_BUFFER_SRV_FLAG_RAW` for CBV, or another usage.
---
🍀 **This work has been financed and kindly donated to the Godot Engine project by [W4 Games](https://w4games.com).** 🍀
