mirror of
https://gitlab.winehq.org/wine/vkd3d.git
synced 2024-11-21 16:46:41 -08:00
2129a7f09d
The idea is to keep at the beginning of the files the sections that contain general introduction to vkd3d and how it works, which are likely the first things a reader needs. Then the sections going into more specific and verbose topics, which are probably to be read only when looking some specific piece of information.
165 lines
6.8 KiB
Plaintext
165 lines
6.8 KiB
Plaintext
=============================
|
|
The vkd3d 3D Graphics Library
|
|
=============================
|
|
|
|
Vkd3d is a 3D graphics library built on top of Vulkan. It has an API very
|
|
similar, but not identical, to Direct3D 12.
|
|
|
|
==============
|
|
Building vkd3d
|
|
==============
|
|
|
|
Vkd3d depends on SPIRV-Headers and Vulkan-Headers (>= 1.3.228).
|
|
|
|
Vkd3d generates some of its headers from IDL files. If you are using the
|
|
release tarballs, then these headers are pre-generated and are included. If
|
|
you are building from git, then they will be generated at build-time using
|
|
widl. By default, vkd3d will use the widl found in `PATH'. If widl is not
|
|
available or is not recent (>= 3.21), then you can build Wine with `make
|
|
tools/widl/widl' to avoid building all of Wine. You can then point vkd3d's
|
|
configure at that widl binary with `WIDL="/path/to/widl"'.
|
|
|
|
For release builds, you may want to define NDEBUG. If you do not need debug log
|
|
messages, you may also consider VKD3D_NO_TRACE_MESSAGES and
|
|
VKD3D_NO_DEBUG_MESSAGES. For example, you can pass `CPPFLAGS="-DNDEBUG
|
|
-DVKD3D_NO_TRACE_MESSAGES"' to configure.
|
|
|
|
================
|
|
Developing vkd3d
|
|
================
|
|
|
|
Development of vkd3d happens on the Wine GitLab instance
|
|
(https://gitlab.winehq.org/wine/vkd3d/). Contributors are encouraged
|
|
to submit their patches using the merge request tool.
|
|
|
|
Each merge request is automatically tested with the GitLab CI
|
|
system. See gitlab/README in the Git tree for more details.
|
|
|
|
===========
|
|
Using vkd3d
|
|
===========
|
|
|
|
Vkd3d can be used by projects that target Direct3D 12 as a drop-in replacement
|
|
at build-time with some modest source modifications.
|
|
|
|
If vkd3d is available when building Wine, then Wine will use it to support
|
|
Direct3D 12 applications.
|
|
|
|
=====================
|
|
Environment variables
|
|
=====================
|
|
|
|
Most of the environment variables used by vkd3d 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.
|
|
|
|
Some of debug variables are lists of elements. Elements must be separated by
|
|
commas or semicolons.
|
|
|
|
* NO_COLOR - this is an alias of NO_COLOUR.
|
|
|
|
* NO_COLOUR - when set, vkd3d-compiler and vkd3d-dxbc will default to
|
|
monochrome output, even when the output supports colour.
|
|
|
|
* VKD3D_CONFIG - a list of options that change the behavior of libvkd3d.
|
|
* virtual_heaps - Create descriptors for each D3D12 root signature
|
|
descriptor range instead of entire descriptor heaps. Useful when push
|
|
constant or bound descriptor limits are exceeded.
|
|
* vk_debug - enables Vulkan debug extensions.
|
|
|
|
* VKD3D_DEBUG - controls the debug level for log messages produced by
|
|
libvkd3d. Accepts the following values: none, err, fixme, warn, trace.
|
|
|
|
* VKD3D_VULKAN_DEVICE - a zero-based device index. Use to force the selected
|
|
Vulkan device.
|
|
|
|
* VKD3D_DISABLE_EXTENSIONS - a list of Vulkan extensions that libvkd3d should
|
|
not use even if available.
|
|
|
|
* VKD3D_SHADER_CONFIG - a list of options that change the behavior of
|
|
libvkd3d-shader.
|
|
* force_validation - Enable (additional) validation of libvkd3d-shader's
|
|
internal representation of shaders.
|
|
|
|
* VKD3D_SHADER_DEBUG - controls the debug level for log messages produced by
|
|
libvkd3d-shader. See VKD3D_DEBUG for accepted values.
|
|
|
|
* VKD3D_SHADER_DUMP_PATH - path where shader bytecode is dumped.
|
|
|
|
* VKD3D_TEST_DEBUG - enables additional debug messages in tests. Set to 0, 1
|
|
or 2.
|
|
|
|
* VKD3D_TEST_DETAILED - enables printing detailed output when running the test
|
|
suite, reporting specific shader_test lines that trigger XFAIL and SKIP even
|
|
on tests that overall PASS. Set to 0, or 1.
|
|
|
|
* 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_target.
|
|
Useful for debugging or developing new tests.
|
|
|
|
* 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_SKIP_DXC - when set, tests requiring the dxcompiler library will
|
|
be skipped.
|
|
|
|
* VKD3D_TEST_BUG - set to 0 to disable bug_if() conditions in tests.
|
|
|
|
If the configuration defines 'DXCOMPILER_LIBS=-L/path/to/dxcompiler', Shader
|
|
Runner attempts to load libdxcompiler.so or dxcompiler.dll to compile test
|
|
shaders in Shader Model 6. LD_LIBRARY_PATH (linux), WINEPATH (wine) or PATH
|
|
(native windows) should include the location of dxcompiler if SM 6 shader
|
|
tests are desired. If dxcompiler is not found, Shader Runner will compile the
|
|
test shaders only in earlier shader models. The DXC source does not contain
|
|
code for adding DXBC checksums, so the official release should be installed
|
|
from:
|
|
https://github.com/microsoft/DirectXShaderCompiler/releases
|
|
|
|
============================
|
|
Testing with the Agility SDK
|
|
============================
|
|
|
|
Traditionally Microsoft have released the Direct3D 12 development files,
|
|
including the debug layer runtime, as part of the larger Windows SDK.
|
|
In 2021 the DirectX 12 Agility SDK was introduced, which may be updated
|
|
independently of the Windows SDK. If you plan to run the vkd3d
|
|
crosstests with Microsoft's debug layer you might want to get it from
|
|
the Agility SDK, both because it's probably going to be more up-to-date
|
|
and because the Agility SDK is a couple dozens of megabytes versus the
|
|
gigabytes of the Windows SDK.
|
|
|
|
In order to build the vkd3d crosstests with Agility SDK support, follow
|
|
these steps:
|
|
|
|
* The Agility SDK is distributed at [1]: select your preferred
|
|
version (likely the most recent one) and note the number in column
|
|
D3D12SDKVersion, which you're going to need later.
|
|
|
|
[1] https://devblogs.microsoft.com/directx/directx12agility/
|
|
|
|
* You also need to enable the "Graphics Tools" optional feature in Windows.
|
|
Open the "Settings" applications, then look for "Apps", "Optional features",
|
|
"View features" and install "Graphics Tools".
|
|
|
|
* Configure vkd3d with something like:
|
|
'CROSSCC64="x86_64-w64-mingw32-gcc -DVKD3D_AGILITY_SDK_VERSION=<version>"',
|
|
as well as the equivalent CROSSCC32 variable for the 32-bit
|
|
crosstests. You'll have to replace '<version>' with the
|
|
D3D12SDKVersion number you noted above. Then build the crosstests
|
|
with 'make crosstest' as usual.
|
|
|
|
* Download the Agility SDK NuGet package, which is essentially a ZIP
|
|
file with a .nupkg extension. Extract d3d12core.dll and
|
|
d3d12sdklayers.dll for your architecture, and put them in the
|
|
directory containing the crosstest executables.
|
|
|
|
* Now you can run the crosstests, possibly with arguments
|
|
'--validate' and '--gbv' to enable the debug layers. They will use
|
|
the runtime from the Agility SDK.
|
|
|
|
* It's also possible to use '-DVKD3D_AGILITY_SDK_PATH=/path/to/sdk/' to
|
|
specify the directory to load the Agility SDK DLLs from at runtime.
|
|
If relative, the path is intended to be relative to the executable
|
|
path. If unspecified the path defaults to './'.
|