README

   1 =============================
   2 The vkd3d 3D Graphics Library
   3 =============================
   4
   5 Vkd3d is a 3D graphics library built on top of Vulkan. It has an API very
   6 similar, but not identical, to Direct3D 12.
   7
   8 ==============
   9 Building vkd3d
  10 ==============
  11
  12 Vkd3d depends on SPIRV-Headers and Vulkan-Headers (>= 1.3.228).
  13
  14 Vkd3d generates some of its headers from IDL files. If you are using the
  15 release tarballs, then these headers are pre-generated and are included. If
  16 you are building from git, then they will be generated at build-time using
  17 widl. By default, vkd3d will use the widl found in `PATH'. If widl is not
  18 available or is not recent (>= 3.21), then you can build Wine with `make
  19 tools/widl/widl' to avoid building all of Wine. You can then point vkd3d's
  20 configure at that widl binary with `WIDL="/path/to/widl"'.
  21
  22 For release builds, you may want to disable debug log messages defining
  23 preprocessor macros VKD3D_NO_TRACE_MESSAGES and VKD3D_NO_DEBUG_MESSAGES.
  24 See the `Preprocessor definitions' section below for more details.
  25
  26 ================
  27 Developing vkd3d
  28 ================
  29
  30 Development of vkd3d happens on the Wine GitLab instance
  31 (https://gitlab.winehq.org/wine/vkd3d/). Contributors are encouraged
  32 to submit their patches using the merge request tool.
  33
  34 Each merge request is automatically tested with the GitLab CI
  35 system. See gitlab/README in the Git tree for more details.
  36
  37 ===========
  38 Using vkd3d
  39 ===========
  40
  41 Vkd3d can be used by projects that target Direct3D 12 as a drop-in replacement
  42 at build-time with some modest source modifications.
  43
  44 If vkd3d is available when building Wine, then Wine will use it to support
  45 Direct3D 12 applications.
  46
  47 =====================
  48 Environment variables
  49 =====================
  50
  51 Most of the environment variables used by vkd3d are for debugging purposes. The
  52 environment variables are not considered a stable interface and might be changed
  53 or removed in future versions of vkd3d.
  54
  55 Some of debug variables are lists of elements. Elements must be separated by
  56 commas or semicolons.
  57
  58  * NO_COLOR - this is an alias of NO_COLOUR.
  59
  60  * NO_COLOUR - when set, vkd3d-compiler and vkd3d-dxbc will default to
  61    monochrome output, even when the output supports colour.
  62
  63  * VKD3D_CONFIG - a list of options that change the behavior of libvkd3d.
  64     * virtual_heaps - Create descriptors for each D3D12 root signature
  65       descriptor range instead of entire descriptor heaps. Useful when push
  66       constant or bound descriptor limits are exceeded.
  67     * vk_debug - enables Vulkan debug extensions.
  68
  69  * VKD3D_DEBUG - controls the debug level for log messages produced by
  70    libvkd3d. Accepts the following values: none, err, fixme, warn, trace.
  71
  72  * VKD3D_VULKAN_DEVICE - a zero-based device index. Use to force the selected
  73    Vulkan device.
  74
  75  * VKD3D_DISABLE_EXTENSIONS - a list of Vulkan extensions that libvkd3d should
  76    not use even if available.
  77
  78  * VKD3D_CAPS_OVERRIDE - a list of Direct3D 12 capabilities for which the
  79    default value detected by vkd3d should be overridden, in the form
  80    `capability1=value1,capability2=value2'. This doesn't change the vkd3d
  81    behaviour, only the information reported to the application. The following
  82    capabilities can currently be overridden:
  83     * feature_level (allowed values: 11.0, 11.1, 12.0, 12.1, 12.2)
  84     * resource_binding_tier (allowed values: 1, 2, 3)
  85
  86  * VKD3D_SHADER_CONFIG - a list of options that change the behavior of
  87    libvkd3d-shader.
  88     * force_validation - Enable (additional) validation of libvkd3d-shader's
  89       internal representation of shaders.
  90
  91  * VKD3D_SHADER_DEBUG - controls the debug level for log messages produced by
  92    libvkd3d-shader. See VKD3D_DEBUG for accepted values.
  93
  94  * VKD3D_SHADER_DUMP_PATH - path where shader bytecode is dumped.
  95
  96  * VKD3D_TEST_DEBUG - enables additional debug messages in tests. Set to 0, 1
  97    or 2.
  98
  99  * VKD3D_TEST_DETAILED - enables printing detailed output when running the test
 100    suite, reporting specific shader_test lines that trigger XFAIL and SKIP even
 101    on tests that overall PASS. Set to 0, or 1.
 102
 103  * VKD3D_TEST_FILTER - a filter string. Only the tests whose names matches the
 104    filter string will be run, e.g. VKD3D_TEST_FILTER=clear_render_target.
 105    Useful for debugging or developing new tests.
 106
 107  * VKD3D_TEST_PLATFORM - can be set to "wine", "windows" or "other". The test
 108    platform controls the behavior of todo(), todo_if(), bug_if() and broken()
 109    conditions in tests.
 110
 111  * VKD3D_TEST_SKIP_DXC - when set, tests requiring the dxcompiler library will
 112    be skipped.
 113
 114  * VKD3D_TEST_BUG - set to 0 to disable bug_if() conditions in tests.
 115
 116 If the configuration defines 'DXCOMPILER_LIBS=-L/path/to/dxcompiler', Shader
 117 Runner attempts to load libdxcompiler.so or dxcompiler.dll to compile test
 118 shaders in Shader Model 6. LD_LIBRARY_PATH (linux), WINEPATH (wine) or PATH
 119 (native windows) should include the location of dxcompiler if SM 6 shader
 120 tests are desired. If dxcompiler is not found, Shader Runner will compile the
 121 test shaders only in earlier shader models. The DXC source does not contain
 122 code for adding DXBC checksums, so the official release should be installed
 123 from:
 124 https://github.com/microsoft/DirectXShaderCompiler/releases
 125
 126 ========================
 127 Preprocessor definitions
 128 ========================
 129
 130 A number of preprocessor definitions can be used at compilation time to control
 131 the behaviour of the generated binary. You can pass something like
 132 `CPPFLAGS="-DVKD3D_VAR1 -DVKD3D_VAR2"' to the configure script. The preprocessor
 133 variables are not considered a stable interface and might be changed or removed
 134 in future versions of vkd3d.
 135
 136  * VKD3D_NO_TRACE_MESSAGES - do not emit trace messages in the debug log; this
 137    can be useful in release builds to reduce the size of the binary and make it
 138    slightly faster.
 139
 140  * VKD3D_NO_DEBUG_MESSAGES - do not emit warn and fixme messages in the debug
 141    log; this will further optimise the binary, but may omit messages that could
 142    help debug problems with vkd3d.
 143
 144  * VKD3D_NO_ERROR_MESSAGES - do not emit error messages; this will optimise the
 145    binary even more, but may omit very important messages, so it is not
 146    recommended in most circumstances.
 147
 148  * VKD3D_ABORT_ON_ERR - abort the process as soon as an error message is
 149    emitted; this can be useful for developers to make error conditions as
 150    conspicuous as possible.
 151
 152  * VKD3D_SHADER_UNSUPPORTED_DXIL - enable DXIL (DirectX Intermediate Language)
 153    support in vkd3d-shader, which is disabled by default because it is not
 154    considered ready for release yet. Please note that this feature is not
 155    currently supported, and it might change in a non-compatible way before it is
 156    released.
 157
 158  * VKD3D_SHADER_UNSUPPORTED_GLSL - enable GLSL (GL Shading Language) support in
 159    vkd3d-shader, which is disabled by default because it is not considered ready
 160    for release yet. Please note that this feature is not currently supported,
 161    and it might change in a non-compatible way before it is released.
 162
 163  * VKD3D_SHADER_UNSUPPORTED_MSL - enable MSL (Metal Shading Language) support in
 164    vkd3d-shader, which is disabled by default because it is not considered ready
 165    for release yet. Please note that this feature is not currently supported,
 166    and it might change in a non-compatible way before it is released.
 167
 168  * VKD3D_SHADER_UNSUPPORTED_SPIRV_PARSER - enable SPIR-V parser support in
 169    vkd3d-shader, which is disabled by default because it is not considered ready
 170    for release yet. Please note that this feature is not currently supported,
 171    and it might change in a non-compatible way before it is released.
 172
 173 ============================
 174 Testing with the Agility SDK
 175 ============================
 176
 177 Traditionally Microsoft have released the Direct3D 12 development files,
 178 including the debug layer runtime, as part of the larger Windows SDK.
 179 In 2021 the DirectX 12 Agility SDK was introduced, which may be updated
 180 independently of the Windows SDK. If you plan to run the vkd3d
 181 crosstests with Microsoft's debug layer you might want to get it from
 182 the Agility SDK, both because it's probably going to be more up-to-date
 183 and because the Agility SDK is a couple dozens of megabytes versus the
 184 gigabytes of the Windows SDK.
 185
 186 In order to build the vkd3d crosstests with Agility SDK support, follow
 187 these steps:
 188
 189  * The Agility SDK is distributed at [1]: select your preferred
 190    version (likely the most recent one) and note the number in column
 191    D3D12SDKVersion, which you're going to need later.
 192
 193  [1] https://devblogs.microsoft.com/directx/directx12agility/
 194
 195  * You also need to enable the "Graphics Tools" optional feature in Windows.
 196    Open the "Settings" applications, then look for "Apps", "Optional features",
 197    "View features" and install "Graphics Tools".
 198
 199  * Configure vkd3d with something like:
 200    'CROSSCC64="x86_64-w64-mingw32-gcc -DVKD3D_AGILITY_SDK_VERSION=<version>"',
 201    as well as the equivalent CROSSCC32 variable for the 32-bit
 202    crosstests. You'll have to replace '<version>' with the
 203    D3D12SDKVersion number you noted above. Then build the crosstests
 204    with 'make crosstest' as usual.
 205
 206  * Download the Agility SDK NuGet package, which is essentially a ZIP
 207    file with a .nupkg extension. Extract d3d12core.dll and
 208    d3d12sdklayers.dll for your architecture, and put them in the
 209    directory containing the crosstest executables.
 210
 211  * Now you can run the crosstests, possibly with arguments
 212    '--validate' and '--gbv' to enable the debug layers. They will use
 213    the runtime from the Agility SDK.
 214
 215  * It's also possible to use '-DVKD3D_AGILITY_SDK_PATH=/path/to/sdk/' to
 216    specify the directory to load the Agility SDK DLLs from at runtime.
 217    If relative, the path is intended to be relative to the executable
 218    path. If unspecified the path defaults to './'.