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 define NDEBUG. If you do not need debug log
  23 messages, you may also consider VKD3D_NO_TRACE_MESSAGES and
  24 VKD3D_NO_DEBUG_MESSAGES. For example, you can pass `CPPFLAGS="-DNDEBUG
  25 -DVKD3D_NO_TRACE_MESSAGES"' to configure.
  26
  27 ===========
  28 Using vkd3d
  29 ===========
  30
  31 Vkd3d can be used by projects that target Direct3D 12 as a drop-in replacement
  32 at build-time with some modest source modifications.
  33
  34 If vkd3d is available when building Wine, then Wine will use it to support
  35 Direct3D 12 applications.
  36
  37 =====================
  38 Environment variables
  39 =====================
  40
  41 Most of the environment variables used by vkd3d are for debugging purposes. The
  42 environment variables are not considered a part of API and might be changed or
  43 removed in the future versions of vkd3d.
  44
  45 Some of debug variables are lists of elements. Elements must be separated by
  46 commas or semicolons.
  47
  48  * NO_COLOR - this is an alias of NO_COLOUR.
  49
  50  * NO_COLOUR - when set, vkd3d-compiler and vkd3d-dxbc will default to
  51    monochrome output, even when the output supports colour.
  52
  53  * VKD3D_CONFIG - a list of options that change the behavior of libvkd3d.
  54     * virtual_heaps - Create descriptors for each D3D12 root signature
  55       descriptor range instead of entire descriptor heaps. Useful when push
  56       constant or bound descriptor limits are exceeded.
  57     * vk_debug - enables Vulkan debug extensions.
  58
  59  * VKD3D_DEBUG - controls the debug level for log messages produced by
  60    libvkd3d. Accepts the following values: none, err, fixme, warn, trace.
  61
  62  * VKD3D_VULKAN_DEVICE - a zero-based device index. Use to force the selected
  63    Vulkan device.
  64
  65  * VKD3D_DISABLE_EXTENSIONS - a list of Vulkan extensions that libvkd3d should
  66    not use even if available.
  67
  68  * VKD3D_SHADER_CONFIG - a list of options that change the behavior of
  69    libvkd3d-shader.
  70     * force_validation - Enable (additional) validation of libvkd3d-shader's
  71       internal representation of shaders.
  72
  73  * VKD3D_SHADER_DEBUG - controls the debug level for log messages produced by
  74    libvkd3d-shader. See VKD3D_DEBUG for accepted values.
  75
  76  * VKD3D_SHADER_DUMP_PATH - path where shader bytecode is dumped.
  77
  78  * VKD3D_TEST_DEBUG - enables additional debug messages in tests. Set to 0, 1
  79    or 2.
  80
  81  * VKD3D_TEST_FILTER - a filter string. Only the tests whose names matches the
  82    filter string will be run, e.g. VKD3D_TEST_FILTER=clear_render_target.
  83    Useful for debugging or developing new tests.
  84
  85  * VKD3D_TEST_PLATFORM - can be set to "wine", "windows" or "other". The test
  86    platform controls the behavior of todo(), todo_if(), bug_if() and broken()
  87    conditions in tests.
  88
  89  * VKD3D_TEST_BUG - set to 0 to disable bug_if() conditions in tests.
  90
  91 If the configuration defines 'DXCOMPILER_LIBS=-L/path/to/dxcompiler', Shader
  92 Runner attempts to load libdxcompiler.so or dxcompiler.dll to compile test
  93 shaders in Shader Model 6. LD_LIBRARY_PATH (linux), WINEPATH (wine) or PATH
  94 (native windows) should include the location of dxcompiler if SM 6 shader
  95 tests are desired. If dxcompiler is not found, Shader Runner will compile the
  96 test shaders only in earlier shader models. The DXC source does not contain
  97 code for adding DXBC checksums, so the official release should be installed
  98 from:
  99 https://github.com/microsoft/DirectXShaderCompiler/releases
 100
 101 ================
 102 Developing vkd3d
 103 ================
 104
 105 Development of vkd3d happens on the Wine GitLab instance
 106 (https://gitlab.winehq.org/wine/vkd3d/). Contributors are encouraged
 107 to submit their patches using the merge request tool.
 108
 109 Each merge request is automatically tested with the GitLab CI
 110 system. See gitlab/README in the Git tree for more details.