vkd3d-proton

vkd3d-proton

vkd3d-proton is a fork of VKD3D, which aims to implement the full Direct3D 12 API on top of Vulkan. The project serves as the development effort for Direct3D 12 support in Proton.

Upstream

The original project is available at WineHQ.

Priorities

Performance and game compatibility are important targets, at the expense of compatibility with older drivers and systems. Modern Vulkan extensions and features are aggressively made use of to improve game performance and compatibility. It is recommended to use the very latest drivers you can get your hands on for the best experience. Backwards compatibility with the vkd3d standalone API is not a goal of this project.

Drivers

There are some hard requirements on drivers to be able to implement D3D12 in a reasonably performant way.

• Vulkan 1.3
• Descriptor indexing with at least 1000000 UpdateAfterBind descriptors for all types except UniformBuffer. Essentially all features in VkPhysicalDeviceDescriptorIndexingFeatures must be supported.
• Further, the following device features are required:
  • samplerMirrorClampToEdge
  • shaderDrawParameters
• VK_EXT_robustness2
• VK_KHR_push_descriptor

Some notable extensions that should be supported for optimal or correct behavior. These extensions will likely become mandatory later.

• VK_EXT_image_view_min_lod

VK_EXT_mutable_descriptor_type (or the vendor VALVE alias) and VK_EXT_descriptor_buffer are also highly recommended, but not mandatory.

AMD (RADV)

For AMD, RADV is the recommended driver and the one that sees most testing on AMD GPUs. The minimum requirement at the moment is Mesa 22.0.

NOTE: For older Mesa versions, use the v2.6 release.

NVIDIA

The Vulkan beta drivers generally contain the latest driver fixes that we identify while getting games to work. The latest drivers (stable, beta or Vulkan beta tracks) are always preferred. If you're having problems, always try the latest drivers. At minimum, 535 series drivers are needed, which fixes a bunch of bugs.

Intel

We have not done any testing against Intel GPUs yet.

---

Cloning the repo

To clone the repo you should run:

git clone --recursive https://github.com/HansKristian-Work/vkd3d-proton

in order to pull in all the submodules which are needed for building.

Building vkd3d-proton

Requirements:

• wine (for widl) [for native builds]
  • On Windows this may be substituted for Strawberry Perl as it ships widl and is easy to find and install -- although this dependency may be eliminated in the future.
• Meson build system (at least version 0.49)
• glslang compiler
• Mingw-w64 compiler, headers and tools (at least version 7.0) [for cross-builds for d3d12.dll which are default]

Building:

The simple way

Inside the vkd3d-proton directory, run:

./package-release.sh master /your/target/directory --no-package

This will create a folder vkd3d-master in /your/target/directory, which contains both 32-bit and 64-bit versions of vkd3d-proton, which can be set up in the same way as the release versions as noted above.

If you want to build natively (ie. for libvkd3d-proton.so), pass --native to the build script. This option will make it build using your system's compilers.

In order to preserve the build directories for development, pass --dev-build to the script. This option implies --no-package. After making changes to the source code, you can then do the following to rebuild vkd3d-proton:

# change to build.86 for 32-bit
ninja -C /your/target/directory/build.64 install

Compiling manually (cross for d3d12.dll, default)

# 64-bit build.
meson --cross-file build-win64.txt --buildtype release --prefix /your/vkd3d-proton/directory build.64
ninja -C build.64 install

# 32-bit build
meson --cross-file build-win32.txt --buildtype release --prefix /your/vkd3d-proton/directory build.86
ninja -C build.86 install

Compiling manually (native)

# 64-bit build.
meson --buildtype release --prefix /your/vkd3d-proton/directory build.64
ninja -C build.64 install

# 32-bit build
CC="gcc -m32" CXX="g++ -m32" \
PKG_CONFIG_PATH="/usr/lib32/pkgconfig:/usr/lib/i386-linux-gnu/pkgconfig:/usr/lib/pkgconfig" \
meson --buildtype release --prefix /your/vkd3d-proton/directory build.86
ninja -C build.86 install

Cross-compilation build for aarch64

First, setup a distrobox using Steam's runtime for it.

distrobox create --image registry.gitlab.steamos.cloud/steamrt/steamrt4/sdk/arm64-on-amd64 --name aarch64
distrobox enter aarch64
# Inside container
sudo apt install mingw-w64-tools
meson setup build-aarch64 \
  --buildtype release \
  --cross-file /usr/share/meson/cross/aarch64-linux-gnu-gcc.txt \
  --cross-file ./build-widl.txt \
  -Denable_extras=true \
  -Denable_tests=true \
  --prefix /tmp/vkd3d-proton-aarch64
ninja -C build-aarch64 install
cp build-aarch64/tests/d3d12 /tmp/vkd3d-proton-aarch64/bin

Building on Windows

NOTE: Building directly on Windows (instead of cross compiling) is only expected to be used for testing and development. The primary use case is to develop tests and run them against native drivers, not to run real applications. This requires decent debugger support, so MSVC is supported as a compiler, although we do not stress test these builds at all.

Building with MSVC

This mostly involves installing the dependencies first (except for mingw-w64). Then, enter a MSVC development shell (usually called "x64 Native Tools Command Prompt for VS 2022" or something similar. Navigate to vkd3d-proton checkout, and run:

mkdir build
cd build
meson .. --backend vs2022 --buildtype release -Denable_tests=true # change as needed
msbuild.exe vkd3d-proton.sln # or open in Visual Studio

Building with mingw (UCRT)

In the ucrt64 shell of msys2, make sure to install ucrt packages of gcc toolchain, meson, glslang, python, ninja, etc.

# The explicit path seems to be important in some cases. It may complain about mismatching python.
# Unlike cross compilation, do not use a cross file here.
mkdir build
cd build
/ucrt64/bin/meson --buildtype release -Denable_tests=true
ninja

Using vkd3d-proton

The intended way to use vkd3d-proton is as native Win32 DLLs (d3d12.dll and d3d12core.dll). These serve as a drop-in replacement for D3D12, and can be used in Wine (Proton or vanilla flavors), or on Windows.

vkd3d-proton does not supply the necessary DXGI components on its own. Instead, DXVK (2.1+) and vkd3d-proton share a DXGI implementation.

A note on using vkd3d-proton on Windows

Native Windows use is mostly relevant for developer testing purposes. Do not expect games running on Windows 7 or 8.1 to magically make use of vkd3d-proton, as many games will only even attempt to load d3d12.dll if they are running on Windows 10.

Native Linux build

A native Linux binary can be built, but it is not intended to be compatible with upstream Wine. A native option is mostly relevant for development purposes for the time being.

Environment variables

Most of the environment variables used by vkd3d-proton are for debugging purposes. The environment variables are not considered a part of API and might be changed or removed in the future versions of vkd3d-proton.

Some of debug variables are lists of elements. Elements must be separated by commas or semicolons.

• VKD3D_CONFIG - a list of options that change the behavior of vkd3d-proton.
  • vk_debug - enables Vulkan debug extensions and loads validation layer.
  • skip_application_workarounds - Skips all application workarounds. For debugging purposes.
  • nodxr - Disables DXR support.
  • dxr - DXR is normally enabled automatically. This config forces it to be enabled even when considered unsafe.
  • dxr12 - Enables experimental support for DXR 1.2 if VK_EXT_opacity_micromap is available.
  • force_static_cbv - Unsafe speed hack on NVIDIA. May or may not give a significant performance uplift.
  • single_queue - Do not use asynchronous compute or transfer queues.
  • no_upload_hvv - Blocks any attempt to use host-visible VRAM (large/resizable BAR) for the UPLOAD heap. May free up vital VRAM in certain critical situations, at cost of lower GPU performance. A fraction of VRAM is reserved for resizable BAR allocations either way, so it should not be a real issue even on lower VRAM cards.
  • force_host_cached - Forces all host visible allocations to be CACHED, which greatly accelerates captures.
  • no_invariant_position - Avoids workarounds for invariant position. The workaround is enabled by default.
• VKD3D_DEBUG - controls the debug level for log messages produced by vkd3d-proton. Accepts the following values: none, err, info, fixme, warn, trace.
• VKD3D_SHADER_DEBUG - controls the debug level for log messages produced by the shader compilers. See VKD3D_DEBUG for accepted values.
• VKD3D_LOG_FILE - If set, redirects VKD3D_DEBUG logging output to a file instead.
• VKD3D_VULKAN_DEVICE - a zero-based device index. Use to force the selected Vulkan device.
• VKD3D_FILTER_DEVICE_NAME - skips devices that don't include this substring.
• VKD3D_DISABLE_EXTENSIONS - a list of Vulkan extensions that vkd3d-proton should not use even if available.
• VKD3D_TEST_DEBUG - enables additional debug messages in tests. Set to 0, 1 or 2.
• VKD3D_TEST_MATCH - a match string. Only the tests whose names exactly match the string will be run, e.g. VKD3D_TEST_FILTER=clear_render_target will only match tests named 'clear_render_target'. Useful for debugging or developing new tests.
• VKD3D_TEST_FILTER - a filter string. Only the tests whose names matches the filter string will be run, e.g. VKD3D_TEST_FILTER=clear_render will match tests named 'clear_render_target' or 'target_clear_render'. Useful for debugging or developing new tests.
• VKD3D_TEST_EXCLUDE - excludes tests of which the name is included in the string, e.g. VKD3D_TEST_EXCLUDE=test_root_signature_priority,test_conservative_rasterization_dxil.
• VKD3D_TEST_PLATFORM - can be set to "wine", "windows" or "other". The test platform controls the behavior of todo(), todo_if(), bug_if() and broken() conditions in tests.
• VKD3D_TEST_BUG - set to 0 to disable bug_if() conditions in tests.
• VKD3D_PROFILE_PATH - If profiling is enabled in the build, a profiling block is emitted to ${VKD3D_PROFILE_PATH}.${pid}.
• VKD3D_SWAPCHAIN_PRESENT_MODE - accepts a Vulkan present mode name. Forces the use of the specified present mode if supported. Currently accepts IMMEDIATE, MAILBOX, FIFO, FIFO_RELAXED, FIFO_LATEST_READY.

Frame rate limit

The VKD3D_FRAME_RATE environment variable can be used to limit the frame rate. A value of 0 uncaps the frame rate, while any positive value will limit rendering to the given number of frames per second.

Shader cache

By default, vkd3d-proton manages its own driver cache. This cache is intended to cache DXBC/DXIL -> SPIR-V conversion. This reduces stutter (when pipelines are created last minute and app relies on hot driver cache) and load times (when applications do the right thing of loading PSOs up front).

Behavior is designed to be close to DXVK state cache.

Default behavior

vkd3d-proton.cache (and vkd3d-proton.cache.write) are placed in the current working directory. Generally, this is the game install folder when running in Steam.

Custom directory

VKD3D_SHADER_CACHE_PATH=/path/to/directory overrides the directory where vkd3d-proton.cache is placed.

Disable cache

`VKD3D_SH