Convert all files to CRLF line endings. authored by Alexandre Julliard's avatar Alexandre Julliard
--- ---
title: Vkd3d title: Vkd3d
--- ---
Vkd3d is a 3D graphics library built on top of Vulkan. It has an API Vkd3d is a 3D graphics library built on top of Vulkan. It has an API
very similar, but not identical, to Direct3D 12. Wine uses vkd3d very similar, but not identical, to Direct3D 12. Wine uses vkd3d
libraries for its implementation of Direct3D 12. libraries for its implementation of Direct3D 12.
# Building # Building
## Getting the vkd3d source ## Getting the vkd3d source
You can download the Vkd3d source code as a You can download the Vkd3d source code as a
[tarball](https://dl.winehq.org/vkd3d/source/), but if you plan to do [tarball](https://dl.winehq.org/vkd3d/source/), but if you plan to do
any actual testing or developing, you'll want to use any actual testing or developing, you'll want to use
[git](https://gitlab.winehq.org/wine/vkd3d). [git](https://gitlab.winehq.org/wine/vkd3d).
To grab the source code, just enter the following command: To grab the source code, just enter the following command:
```sh ```sh
$ git clone https://gitlab.winehq.org/wine/vkd3d.git $ git clone https://gitlab.winehq.org/wine/vkd3d.git
``` ```
## Compiling ## Compiling
Enter the following commands: Enter the following commands:
```sh ```sh
$ ./autogen.sh $ ./autogen.sh
$ ./configure $ ./configure
$ make $ make
``` ```
See also the [README See also the [README
file](https://gitlab.winehq.org/wine/vkd3d/-/raw/master/README). file](https://gitlab.winehq.org/wine/vkd3d/-/raw/master/README).
In order to build 32-bit libraries: In order to build 32-bit libraries:
```sh ```sh
$ ../vkd3d/configure --build=i686-pc-linux-gnu "CPPFLAGS=-m32" "LDFLAGS=-m32" $ ../vkd3d/configure --build=i686-pc-linux-gnu "CPPFLAGS=-m32" "LDFLAGS=-m32"
``` ```
## Building a MinGW WoW64 Wine with a custom vkd3d build ## Building a MinGW WoW64 Wine with a custom vkd3d build
If you want your Wine build to use a custom vkd3d build and make it If you want your Wine build to use a custom vkd3d build and make it
compatible with a wider range of applications, check [Building a MinGW compatible with a wider range of applications, check [Building a MinGW
WoW64 Wine with a custom vkd3d WoW64 Wine with a custom vkd3d
build](Building-a-MinGW-WoW64-Wine-with-a-custom-vkd3d-build). build](Building-a-MinGW-WoW64-Wine-with-a-custom-vkd3d-build).
## Building Wine with Direct3D 12 support ## Building Wine with Direct3D 12 support
Wine uses **pkg-config** to find vkd3d libraries. If vkd3d libraries are Wine uses **pkg-config** to find vkd3d libraries. If vkd3d libraries are
installed system-wide, the Wine configure script should find the vkd3d installed system-wide, the Wine configure script should find the vkd3d
libraries automatically. You can also use **PKG_CONFIG_PATH**, libraries automatically. You can also use **PKG_CONFIG_PATH**,
**VKD3D_CFLAGS** or **VKD3D_LIBS** to override **pkg-config** search **VKD3D_CFLAGS** or **VKD3D_LIBS** to override **pkg-config** search
path, C compiler flags for **libvkd3d**, or linker flags for path, C compiler flags for **libvkd3d**, or linker flags for
**libvkd3d**, e.g. **libvkd3d**, e.g.
```sh ```sh
$ ../wine-git/configure PKG_CONFIG_PATH=$HOME/src/vulkan/install/lib/pkgconfig $ ../wine-git/configure PKG_CONFIG_PATH=$HOME/src/vulkan/install/lib/pkgconfig
``` ```
# Debugging # Debugging
## Debug output ## Debug output
Vkd3d provides **VKD3D_DEBUG** and **VKD3D_SHADER_DEBUG** environment Vkd3d provides **VKD3D_DEBUG** and **VKD3D_SHADER_DEBUG** environment
variables to control debug log messages. The debug variables can be set variables to control debug log messages. The debug variables can be set
to one of the following debug log levels: **none**, **err**, **fixme**, to one of the following debug log levels: **none**, **err**, **fixme**,
**warn**, **trace**. **warn**, **trace**.
See the [README See the [README
file](https://gitlab.winehq.org/wine/vkd3d/-/raw/master/README) for file](https://gitlab.winehq.org/wine/vkd3d/-/raw/master/README) for
description of all debug environment variables. description of all debug environment variables.
## Vulkan validation layers ## Vulkan validation layers
Enable validation layers in a standard way: Enable validation layers in a standard way:
```sh ```sh
export VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation export VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation
``` ```
You may also want to enable Vulkan debug extensions in vkd3d: You may also want to enable Vulkan debug extensions in vkd3d:
```sh ```sh
VKD3D_CONFIG=vk_debug VKD3D_CONFIG=vk_debug
``` ```
## Other tools ## Other tools
- [RenderDoc](https://renderdoc.org/) is a frame-capture based debugger. - [RenderDoc](https://renderdoc.org/) is a frame-capture based debugger.
It supports Vulkan and Direct3D 12. It supports Vulkan and Direct3D 12.
- VK_LAYER_LUNARG_api_dump is useful to dump Vulkan commands produced by - VK_LAYER_LUNARG_api_dump is useful to dump Vulkan commands produced by
libvkd3d. libvkd3d.
- [Fossilize](https://github.com/ValveSoftware/Fossilize) might be - [Fossilize](https://github.com/ValveSoftware/Fossilize) might be
useful for debugging crashes in driver shader compiler. Just capture useful for debugging crashes in driver shader compiler. Just capture
pipelines using VK_LAYER_fossilize and use fossilize-replay to pipelines using VK_LAYER_fossilize and use fossilize-replay to
reproduce the crash. reproduce the crash.
# Tests # Tests
Use the following command to run tests: Use the following command to run tests:
```sh ```sh
$ make check $ make check
``` ```
Tests can also be run individually, for example: Tests can also be run individually, for example:
```sh ```sh
$ make tests/d3d12 && ./tests/d3d12 $ make tests/d3d12 && ./tests/d3d12
$ VKD3D_TEST_FILTER=clear_render_target ./tests/d3d12 $ VKD3D_TEST_FILTER=clear_render_target ./tests/d3d12
``` ```
To cross-compile tests for Windows run the following command: To cross-compile tests for Windows run the following command:
```sh ```sh
$ make crosstest $ make crosstest
``` ```
## Shader bytecode in tests ## Shader bytecode in tests
Some tests include compiled shader bytecode. Shader bytecode should be Some tests include compiled shader bytecode. Shader bytecode should be
generated with `/Qstrip_debug /Qstrip_reflect` options. For example: generated with `/Qstrip_debug /Qstrip_reflect` options. For example:
```sh ```sh
$ fxc /Qstrip_debug /Qstrip_reflect /T ps_5_0 source.hlsl /Fo output.dxbc $ fxc /Qstrip_debug /Qstrip_reflect /T ps_5_0 source.hlsl /Fo output.dxbc
``` ```
# See also # See also
- [Todo](Todo) - [Todo](Todo)
- [Known Issues](Known-Issues) - [Known Issues](Known-Issues)