From 52846c72fcd00ff59ed2ba1a8d342cd3efaacbc3 Mon Sep 17 00:00:00 2001 From: Alexandre Julliard Date: Mon, 2 Sep 2024 18:17:49 +0200 Subject: [PATCH] Import vkd3d pages from MediaWiki. --- ...GW-WoW64-Wine-with-a-custom-vkd3d-build.md | 362 ++++++++++++++++++ Known-Issues.md | 248 ++++++++++++ Todo.md | 134 +++++++ home.md | 134 +++++++ 4 files changed, 878 insertions(+) create mode 100644 Building-a-MinGW-WoW64-Wine-with-a-custom-vkd3d-build.md create mode 100644 Known-Issues.md create mode 100644 Todo.md create mode 100644 home.md diff --git a/Building-a-MinGW-WoW64-Wine-with-a-custom-vkd3d-build.md b/Building-a-MinGW-WoW64-Wine-with-a-custom-vkd3d-build.md new file mode 100644 index 0000000..71144eb --- /dev/null +++ b/Building-a-MinGW-WoW64-Wine-with-a-custom-vkd3d-build.md @@ -0,0 +1,362 @@ +As of version 7.4, Wine comes with a bundled version of vkd3d. + +However, if you want to use a more modern version of vkd3d, apply +certain patches to it, or test fixes of your own, you will need Wine to +work with a custom version of vkd3d. + +For this purpose, it is necessary to build both projects and link them +correctly. + +Compiling a Windows on Windows (WoW) version of Wine, so that it +supports both 32-bits and 64-bits Windows applications – which is often +desired – adds a layer of complexity to the build process. + +Furthermore, you may want to use MinGW to cross-compile the Wine +executables and DLLs in the Windows PE format. This is because various +programs expect the on-disk DLLs to look like real PE DLLs. + +This guide aims to help you through that process. + +# Preliminaries + +## Install Wine dependencies + +First, install the dependencies listed in the [Building +Wine](https://gitlab.winehq.org/wine/wine/-/wikis/Building-Wine#satisfying-build-dependencies) article. + +Remember to install the `:i386` version of the required packages too (if +your system has multi-lib support). + +The **mingw** and **vulkan** packages are of particular importance. + +It is also recommended that you install `ccache`, as it may save us a +considerable amount of time during the builds. + +If you have a system-wide installation of vkd3d, it may be good to +uninstall it using `make uninstall`. To ensure that the correct version +of vkd3d is linked in this tutorial. + +## Directory organization + +For this tutorial we will need to create several build directories and +have several git repositories. For this reason, we will start by +creating a common directory for them: + +``` sh +$ mkdir -p $HOME/wine-dirs +``` + +## Cloning `wine` and `vkd3d` repositories + +First, we clone the `wine` repository if we haven't already: + +``` sh +$ git clone https://gitlab.winehq.org/wine/wine.git $HOME/wine-dirs/wine-git +``` + +We also need to clone `vkd3d` repository if we haven't already: + +``` sh +$ git clone https://gitlab.winehq.org/wine/vkd3d.git $HOME/wine-dirs/vkd3d-git +``` + +In case you already have these repositories somewhere else, you can +create symbolic links inside `wine-dirs` instead: + +``` sh +$ cd $HOME/wine-dirs +$ ln -s wine-git +$ ln -s vkd3d-git +``` + +Now it is a good time to pick a particular branch or apply the desired +patches to these repositories. + +# Building + +## Build WIDL + +If the distribution provides a recent enough version (3.21 or later as +of this writing) of WIDL, we can skip this step. On Debian that's +provided by the `mingw-w64-tools` package. We can also skip this step if +we already have 64-bit Wine available and built. + +Vkd3d uses WIDL to compile its IDL files, and if the distribution +doesn't provide a package, we'll have to build it from the Wine +repository to get it. We start by creating the build directory: + +``` sh +$ cd $HOME/wine-dirs +$ mkdir wine64p +``` + +We run the Wine `configure` script from the installation folder + +``` sh +$ cd wine64p +$ ../wine-git/configure --enable-win64 CC='ccache gcc' x86_64_CC='ccache x86_64-w64-mingw32-gcc' +``` + +Note that we use `x86_64_CC` to indicate the compiler used for +cross-compilation, in this case we need the 64-bit mingw32 compiler. We +prepend `ccache` which works as a wrapper for the compiler. The same is +done for the regular C compiler, `gcc`, passed with the `CC` variable. + +Note that to know about other parameters for the `configure` script we +can use: + +``` sh +$ ../wine-git/configure --help +``` + +Also, if something from the configure command fails, it is useful to +search in `config.log` for the line that contains the pertinent error, +and the lines before and after it. + +Once the configure script has finished, we use `make tools/widl/widl` to +only compile WIDL. We can pass `-j` to use threads. + +``` sh +$ make -j8 tools/widl/widl +``` + +## Build a 64-bit vkd3d installation + +Now we need to build 64-bit vkd3d. For that purpose we will also need +the Vulkan and SPIR-V headers. One way of getting them is downloading +the [Vulkan SDK](https://vulkan.lunarg.com). + +Alternativelly, you can get them from the official +[Vulkan-Headers](https://github.com/KhronosGroup/Vulkan-Headers) and +[SPIRV-Headers](https://github.com/KhronosGroup/SPIRV-Headers) +repositories. + +Another alternative is to copy them from your distribution. Usually the +host headers will be installed in `/usr/include/vulkan/` and +`/usr/include/spirv/`. + +Assuming you downloaded and extracted the SDK, move it to the common +directory: + +``` sh +$ mv $HOME/wine-dirs/vulkan-sdk +``` + +You must change the first argument of the `mv` command depending on +where you downloaded and extracted the SDK. e.g. +`~/Downloads/vulkansdk-linux-x86_64-1.3.204.1/1.3.204.1`. + +We have to run `autogen.sh` in `vkd3d-git` to generate vkd3d's +`configure` script + +``` sh +$ cd $HOME/wine-dirs/vkd3d-git +$ ./autogen.sh +``` + +Now we create a folder for the 64-bit vkd3d build + +``` sh +$ cd $HOME/wine-dirs +$ mkdir vkd3d64 +``` + +We run the configure script in the installation folder: + +``` sh +$ cd vkd3d64 +$ ../vkd3d-git/configure \ + --host=x86_64-w64-mingw32 \ + --prefix="$HOME/wine-dirs/vkd3d64-prefix" \ + WIDL="$HOME/wine-dirs/wine64p/tools/widl/widl" \ + SONAME_LIBVULKAN="vulkan-1.dll" \ + CPPFLAGS="-I$HOME/wine-dirs/vulkan-sdk/x86_64/include" \ + LDFLAGS="-static-libgcc" +``` + +- `--host=x86_64-w64-mingw32` indicates that we want to cross-compile + the programs and libraries using the 64-bit MinGW compiler. +- `--prefix="$HOME/wine-dirs/vkd3d64-prefix"` is used to set this + build's installation directory. In this case, we will create a new + folder inside `wine-dirs`. We have to keep in mind that the other + programs will expect the vkd3d libraries to be in this directory at + run-time. +- We set the `WIDL` variable to point to our provisional 64-bit Wine's + WIDL. When using the distribution's WIDL, `configure` should generally + be able to find WIDL on its own and this variable can be omitted; if + not, point it to the location of the distribution's WIDL. +- `SONAME_LIBVULKAN` indicates the name of the Vulkan library to load at + run-time. +- We use `CPPFLAGS` so that the compiler knows to search in the + `vulkan-sdk` folder for the vulkan headers (`-I` flag). Note that you + cannot pass `-I/usr/include/` here to use the host headers; this will + result in incorrect detection of headers like `dlfcn.h`. You will need + to copy or link host headers to a separate directory. +- We use `LDFLAGS="-static-libgcc"` because MinGW gcc depends on + `libgcc_s_sjlj-1.dll`; this links a static version. Alternatively, you + can add the correct path to `--with-system-dllpath` as described + below. + +Then we run + +``` sh +$ make +``` + +Append `-j$(nproc)` to parallelize. + +And if the build succeeds, then we run + +``` sh +$ make install +``` + +to install 64-bit vkd3d in `$HOME/wine-dirs/vkd3d64-prefix`. + +## Build 64-bit wine + +Now with the 64-bit `vkd3d` installation, we can compile a 64-bit Wine +linked to it. + +If you do not have a 64-bit wine tree already, create a new one: + +``` sh +$ cd $HOME/wine-dirs +$ mkdir wine64 +``` + +Alternatively, you can reuse the same "provisional" Wine tree. + +We run the Wine `configure` script again, but now specifying the +parameters to link Wine to the 64-bit vkd3d prefix we just created. We +will also need to include the vulkan headers: + +``` sh +$ cd wine64 +$ ../wine-git/configure --enable-win64 \ + CC='ccache gcc' x86_64_CC='ccache x86_64-w64-mingw32-gcc' \ + --with-system-dllpath="$HOME/wine-dirs/vkd3d64-prefix/bin:" \ + VKD3D_PE_CFLAGS="-I$HOME/wine-dirs/vulkan-sdk/x86_64/include -I$HOME/wine-dirs/vkd3d64-prefix/include/vkd3d" \ + VKD3D_PE_LIBS="-L$HOME/wine-dirs/vkd3d64-prefix/lib -lvkd3d -lvkd3d-shader" +``` + +- We use `--with-system-dllpath` so that wine knows to search our vkd3d + prefix for the vkd3d DLLs. If you did not use `-static-libgcc` to + compile vkd3d, you should also add the libgcc path here. Depending on + distribution it may be `/usr/x86_64-w64-mingw32/bin/` (Arch), + `/usr/x86_64-w64-mingw32/sys-root/mingw/bin/` (Fedora), or + `/usr/lib/gcc/x86_64-w64-mingw32/##-win32/`, where `##` depends on the + gcc version (Debian). + - Notice that multiple paths should be separated with a colon. +- We set `VKD3D_PE_CFLAGS` and `VKD3D_PE_LIBS` to indicate that we will + use a custom version of vkd3d. We use `VKD3D_PE_CFLAGS` to include the + vulkan headers and the vkd3d headers and `VKD3D_PE_LIBS` to load + vkd3d's dynamic libraries. + - Alternatively, you can install MinGW pkg-config, and pass + `PKG_CONFIG_PATH="$HOME/wine-dirs/vkd3d64-prefix/lib/pkgconfig"`. + +If you get the following message around the last lines: + +``` +configure: libvkd3d 64-bit MinGW development files not found; using bundled version. +``` + +Wine was **not** correctly linked to your custom version of vkd3d. Check +the `config.log`. + +Clean ntdll to make sure that the new system DLL path is picked up, and +then rebuild wine: + +``` sh +$ make dlls/ntdll/clean +$ make +``` + +Append "-j\$(nproc)" to make commands to parallelize. + +## Build a 32-bit vkd3d installation + +``` sh +$ cd $HOME/wine-dirs +$ mkdir vkd3d32 +``` + +``` sh +$ cd vkd3d32 +$ ../vkd3d-git/configure \ + --host=i686-w64-mingw32 \ + --prefix="$HOME/wine-dirs/vkd3d32-prefix" \ + WIDL="$HOME/wine-dirs/wine64p/tools/widl/widl" \ + SONAME_LIBVULKAN="vulkan-1.dll" \ + CPPFLAGS="-I$HOME/wine-dirs/vulkan-sdk/x86_64/include" \ + LDFLAGS="-static-libgcc" +``` + +- We now use `--host=i686-w64-mingw32` to indicate that we will use the + 32-bit MinGW compiler. +- We are changing the prefix so that this 32-bit vkd3d is installed in + the `vkd3d32-prefix` folder instead of `vkd3d64-prefix`. +- We're using 64-bit WIDL like before; this is fine. +- We can also still use the Vulkan headers from our 64-bit vulkan-sdk. + +We then run: + +``` sh +$ make +$ make install +``` + +## Build 32-bit Wine + +We can now build our 32-bit Wine, linking it to our 32-bit vkd3d. + +``` sh +$ cd $HOME/wine-dirs +$ mkdir wine32 +``` + +``` sh +$ cd wine32 +$ ../wine-git/configure --with-wine64=../wine64/ \ + CC='ccache gcc' i386_CC='ccache i686-w64-mingw32-gcc' \ + --with-system-dllpath="$HOME/wine-dirs/vkd3d32-prefix/bin:" \ + VKD3D_PE_CFLAGS="-I$HOME/wine-dirs/vulkan-sdk/x86_64/include -I$HOME/wine-dirs/vkd3d32-prefix/include/vkd3d" \ + VKD3D_PE_LIBS="-L$HOME/wine-dirs/vkd3d32-prefix/lib -lvkd3d -lvkd3d-shader" +``` + +- We now point `--with-system-dllpath` and `VKD3D_PE_LIBS` to the + directories inside `vkd3d32-prefix`. + +As above, clean ntdll to make sure that the new system DLL path is +picked up, and then rebuild wine: + +``` sh +$ make dlls/ntdll/clean +$ make +``` + +# Updating your build + +If you want to update either wine or vkd3d's source code, we can execute +the following commands in order. `ccache` should help reducing the +compilations times. + +``` sh +# Recompile 64-bit vkd3d +cd $HOME/wine-dirs/vkd3d64 +make +make install + +# Recompile 64-bit wine +cd $HOME/wine-dirs/wine64 +make + +# Recompile 32-bit vkd3d +cd $HOME/wine-dirs/vkd3d32 +make +make install + +# Recompile 32-bit wine +cd $HOME/wine-dirs/wine32 +make +``` diff --git a/Known-Issues.md b/Known-Issues.md new file mode 100644 index 0000000..7fe3a40 --- /dev/null +++ b/Known-Issues.md @@ -0,0 +1,248 @@ +Vkd3d is considered as work-in-progress, there are known issues that +have to be resolved. Moreover, there are some incompatibilities between +Vulkan and Direct3D 12. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Issue

Description

Current implementation

Possible solutions

NULL descriptors

Vulkan doesn't support NULL descriptors.

NULL descriptors are currently emulated using dummy resources. +Sparse resources are used when +`residencyNonResidentStrict` is supported. The current +solution doesn't handle `resinfo` and +`bufinfo` instructions correctly.

Indirect draws

In Direct3D 12 indirect draws can update vertex buffer views, +index buffer views, root constants and root descriptors.

Not supported in Vulkan.

    +
  • A Vulkan extension.
    • +
  • It could be emulated in an inefficient way.
    • +

Memory object residency

Memory object residency management doesn't exist in Vulkan. In +Direct3D 12 resources and heaps can be evicted. Resource descriptors are +still valid after a resource is made resident again.

We can try to evict memory manually (e.g. using sparse +bindings).

Queries initial state

Queries are initially in the available state in Direct3D 12. +Results are all equal to zero.

We track the query state, and fill buffer with zeroes when a +query wasn't issued. The current implementation doesn't handle command +lists executed out-of-order.

Texture array views

Texture array views and textures views are incompatible in +Vulkan.

Descriptor heaps

Direct3D 12 and Vulkan binding models are largely different. It +seems to be implied that Direct3D 12 CBV/SRV/UAV descriptor heaps exist +in GPU memory, but there's no real equivalent for that in Vulkan. Vulkan +descriptor sets are probably the closest match, but among others have +the issue that the descriptor type (CBV, SRV or UAV) would need to be +declared in advance, while in Direct3D 12 these can be mixed freely +within the descriptor heap. Run-time translation from Direct3D 12 +binding model to Vulkan binding model is expected to introduce a +noticeable overhead.

CPU descriptor heaps

Direct3D 12 allows to create and prepare descriptors in CPU +heaps. Descriptors from CPU descriptor heaps can be copied to +shader-visible descriptor heaps. In Vulkan, there are only +shared-visibile descriptor sets, and +`VkCopyDescriptorSet` is implemented very inefficiently +on some drivers.

Descriptor heaps concurrency

Some apps appear to concurrently overwrite descriptors in +descriptor heaps. We need to confirm that this works reliably on +Windows. It might not be a problem on Windows because implementations +might simply write or copy descriptors data in memory. However, in our +translation layer we have to manage VkImageView objects and potentially +reference count them.

Descriptors for destroyed resources

Apps keep descriptors for destroyed resources in descriptor +heaps. This is problematic and may lead to invalid usage in +Vulkan.

ID3D12Fence

ID3D12Fence have an associated UINT64 value (see also timeline +semaphores). In addition, ID3D12Fence can be signaled by GPU or CPU, and +can also be waited for on CPU or ID3D12CommandQueue. Moreover, it's +possible to signal native Win32 events when a fence reaches a certain +value. In Vulkan, there is no way to signal native synchronization +objects (e.g. HANDLEs to Win32 events or file descriptors) when, e.g. +VkFence is signaled.

Timeline semaphores.

Sampler border color

In Direct3D 12 the sampler border color is defined as a float4 +vector. In Vulkan the border color is constrained by the values of the +VkBorderColor enum. (It might not be that important because we haven't +encountered application which needs this yet).

Separate resource state for depth-stencil

In Direct3D, the depth aspect and the stencil aspect of an image +can be in different image layouts.

Vulkan extension.

Out-of-bounds resource access

Vulkan doesn't give the same guarantees as Direct3D 12 when it +comes to out-of-bounds resource access.

D3D12_DEFAULT_RESOURCE_PLACEMENT_ALIGNMENT

On radv with AMD Polaris GPUs, the required alignment for +textures may be higher than 0x10000 +(D3D12_DEFAULT_RESOURCE_PLACEMENT_ALIGNMENT), e.g. 0x20000 or 0x40000. +World of Warcraft aligns only to +D3D12_DEFAULT_RESOURCE_PLACEMENT_ALIGNMENT and ignores the alignment +returned from `GetResourceAllocationInfo()`.

We currently allocate additional device memory when the heap +offset is misaligned.

Swapchain

    +
  • sRGB views.
    • +
  • Scaling.
    • +
  • Present mode without recreating.
    • +

We currently use additional set of images and blit from them to +the real swapchain.

Conditional rendering

In D3D12, 64-bit values are used. +`VK_EXT_conditional_rendering` uses 32-bit values. In +D3D12, conditional rendering affects copy commands.

We do what the `VK_EXT_conditional_rendering` +extension does.

Binary occlusion queries

D3D12 guarantees binary occlusion queries result in only 0 and +1.

Strip cut value

In Vulkan the strip cut value is derived from the index format. +In Direct3D 12 0xffff or 0xffffffff can be used as the strip cut value +with 16-bit and 32-bit index buffer formats.

Not supported in Vulkan.

GPU virtual addresses

In Direct3D 12, vertex buffers, index buffers, stream output +buffers and root descriptors are bound using GPU virtual addresses. In +Vulkan, VkBuffer objects with an offset are used instead.

Fake virtual addresses are allocated for buffers. Virtual +addresses have to be resolved to VkBuffer and an offset. The resolving +of GPU virtual address introduces unnecessary overhead.

    +
  • `VK_EXT_device_buffer_address` can be used for root +descriptors. Unfortunately, the extension doesn't help with vertex, +index and stream output buffers. The extension also introduces some +complications, e.g. multiple buffers can be bound to the same virtual +memory address.
    • +
  • Ideally, we could bind vertex, index and stream output buffers using +`VkDeviceAddress` in Vulkan.
    • +

`GetResourceAllocationInfo()`

In Vulkan, a resource needs to be created to get allocation +info.

We create temporary resources to get allocation info.

`SetEventOnCompletion()` / +`SetEventOnMultipleFenceCompletion()`

We have a separate thread that signals Win32 events.

Timeline semaphores.

Copy between depth-stencil and color formats

In Direct3D 12 it is possible to copy data between compatible +color and depth-stencil resources.

We currently use a temporary buffer to perform the copy +operation.

We should implement the copy operation in shaders for graphics +and compute queues.

Dynamic states

In Direct3D 12 the following states are dynamic: vertex buffer +strides, the primitive topology and viewport/scissor counts. In Vulkan, +those states require compiling a new pipeline. The primitive topology +type is still specified when Direct3D 12 pipeline states are created +(one of points, lines, triangles, or patches).

Vulkan pipelines are created on draw call time when we know all +parameters to compile the pipeline.

    +
  • Add pipeline cache.
    • +
  • Compile pipelines speculatively.
    • +
diff --git a/Todo.md b/Todo.md new file mode 100644 index 0000000..c933dca --- /dev/null +++ b/Todo.md @@ -0,0 +1,134 @@ +## libvkd3d + +- Try to use VK_EXT_buffer_device_address for GPU addresses (partially + done - jkucia). +- Add tests for out-of-bounds access with vertex buffers. +- Improve multi-queue support. +- Queue family ownership transfer. +- Fix all Vulkan validation errors. +- Fix clears for A8_UNORM. +- Implement UAVs in vertex processing shader stages. +- Implement support for multiple viewports. +- Test and fix copying between BC and other compatible formats. +- State decay for resources and queue ownership transfer for resources. +- Reduce the number of queue submits. Queue submits are generally + expensive, especially on recent kernels with amdgpu (mostly done - + jkucia). +- Merge vkCmdPipelineBarrier() calls. +- Try to avoid fence worker thread when possible. +- Implement stencil aspect resource state transitions. +- Implement cache for SPIR-V shaders? +- Implement disk pipeline/shader cache? +- Implement sparse resources? +- Optimize barriers (render passes, ClearUnorderedAccessView, transform + feedback). +- Memory residency. +- Raytracing? +- DirectML? +- Add support for sRGB swapchain views (VK_KHR_image_format_list). +- Add tests for validation of view format compatibility (RTV, SRV, UAV, + DSV). + +## libvkd3d-shader + +- Add support for capturing components with stream output. +- Finish the DXIL work (Conor). +- Add tests for OpenGL atomic counters. +- Import SM4 to GLSL shader translation from wined3d (Henri). +- Allow ignoring checking the checksum when parsing DXBC, both from the + API and from the command line. +- Always check that memory allocation didn't fail; for example, calls to + vkd3d_string_buffer_printf() usually are not checked. +- Finish API for scanning/gathering info from shaders (registers used, + bindings used, parameters used, required limits, extensions). +- Implement ID3D11ShaderReflection et al. + - Should we put everything into the same (chained) + vkd3d_shader_scan_dxbc_info struct, or split them up? (Split up the + DXBC-specific ones from the rest?) + - I guess HLSL compile flags should be preserved verbatim...? I don't + like the disparity we currently have. + - How to do things like constant table types? +- Add support for SSBO. +- Support HLSL -\> sm6 compilation. +- Support direct HLSL -\> spirv compilation. This will be easier as + things are refactored to account for vsir. +- Consider adding a CUDA frontend. + +#### TPF validation + +Vkd3d-shader generally assumes that Direct3D shader bytecode is valid +and doesn't do much validation. We should introduce some kind of +validation pass. The validation potentially could be optional, e.g. used +only in debug builds. + +- Interpolation mode is the same for all variables in the input + register. +- Number of indices for resources (SM5 vs SM5.1). + +## Tests + +- Make it possible to run all reasonable test combinations mixing these + factors: + - the library used to compile the shaders: vkd3d-shader, + d3dcompiler_xx.dll or dxcompiler.dll; + - the Shader Model to target; + - the API to use to run the shader (d3d8, d3d9, d3d10, d3d11, d3d12, + Vulkan, GL); + - when running on Windows, the actual library to use to run the + shader: vkd3d or a native implementation; + - possibly, one day, the library to use to recompile the shaders (it + currently only makes sense on macOS once we support the Apple shader + compiler for Metal; in all the other cases the choice is forced). +- Run a decent subsets of those combinations in the CI. +- Need more shader runners: OpenGL + GLSL (Henri has WIP), d3d10core, + d3d8 + +- Some HLSL functionality was accepted despite a lack of tests. We need + tests for: + - all tex\*() variants + - D3DCOLORtoUBYTE4() different results on sm1 + - min() + - texture arrays + - centroid interpolation + - "linear centroid" keywords + - noperspective interpolation + - precise? + - texture types other than 2D + - nontrivial tests for 2D multisample textures + - GetDimensions() + - SampleCmp(), SampleCmpLevelZero() + - depth output + - GS SV_PrimitiveID + - For the sake of sm1 and its weird disjoint instruction sets, a lot + of tests probably deserve VS variants as well. + - Uniform reflection, which depends on uniform reflection API design + - SM1 semantic matching (Zeb has this) + - Test that all of the SM1 input semantics work + - tbuffer + - We should properly gate features based on profile version, and test + that we are correctly doing this. + + +None of this necessarily needs to be extensions to the shader runner; we +can find a way to write C tests for these. + +- We would also like a way to invoke shader runner logic from C. It's a + bit unfortunate that the tests in hlsl_d3d12.c are d3d12-specific. +- Untested sm4 -\> spirv paths: + - "lod" shader instruction + - bufinfo and resinfo with NULL SRV and UAV descriptors + - D3D discard semantics + +## DXGI + +- Fix adapter LUIDs in Wine. +- Reimplement IDXGIAdapter3::QueryVideoMemoryInfo() on top of + VK_EXT_memory_budget. Ideally, Vulkan implementations should return + the memory budget based on total system load (memory used by all + graphics APIs). + +## Vulkan + +- Try to fix detached WSI surfaces after D3D9/D3D11 swapchain (OpenGL) + is created for a window with D3D12 swapchain (Vulkan). +- Fix child window rendering for D3D12 RenderDoc. diff --git a/home.md b/home.md new file mode 100644 index 0000000..de081f0 --- /dev/null +++ b/home.md @@ -0,0 +1,134 @@ +--- +title: Vkd3d +--- + +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 +libraries for its implementation of Direct3D 12. + +# Building + +## Getting the vkd3d source + +You can download the Vkd3d source code as a +[tarball](https://dl.winehq.org/vkd3d/source/), but if you plan to do +any actual testing or developing, you'll want to use +[git](https://gitlab.winehq.org/wine/vkd3d). + +To grab the source code, just enter the following command: + +```sh +$ git clone https://gitlab.winehq.org/wine/vkd3d.git +``` + +## Compiling + +Enter the following commands: + +```sh +$ ./autogen.sh +$ ./configure +$ make +``` + +See also the [README +file](https://gitlab.winehq.org/wine/vkd3d/-/raw/master/README). + +In order to build 32-bit libraries: + +```sh +$ ../vkd3d/configure --build=i686-pc-linux-gnu "CPPFLAGS=-m32" "LDFLAGS=-m32" +``` + +## 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 +compatible with a wider range of applications, check [Building a MinGW +WoW64 Wine with a custom vkd3d +build](Building-a-MinGW-WoW64-Wine-with-a-custom-vkd3d-build). + +## Building Wine with Direct3D 12 support + +Wine uses **pkg-config** to find vkd3d libraries. If vkd3d libraries are +installed system-wide, the Wine configure script should find the vkd3d +libraries automatically. You can also use **PKG_CONFIG_PATH**, +**VKD3D_CFLAGS** or **VKD3D_LIBS** to override **pkg-config** search +path, C compiler flags for **libvkd3d**, or linker flags for +**libvkd3d**, e.g. + +```sh +$ ../wine-git/configure PKG_CONFIG_PATH=$HOME/src/vulkan/install/lib/pkgconfig +``` + +# Debugging + +## Debug output + +Vkd3d provides **VKD3D_DEBUG** and **VKD3D_SHADER_DEBUG** environment +variables to control debug log messages. The debug variables can be set +to one of the following debug log levels: **none**, **err**, **fixme**, +**warn**, **trace**. + +See the [README +file](https://gitlab.winehq.org/wine/vkd3d/-/raw/master/README) for +description of all debug environment variables. + +## Vulkan validation layers + +Enable validation layers in a standard way: + +```sh +export VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation +``` + +You may also want to enable Vulkan debug extensions in vkd3d: + +```sh +VKD3D_CONFIG=vk_debug +``` + +## Other tools + +- [RenderDoc](https://renderdoc.org/) is a frame-capture based debugger. + It supports Vulkan and Direct3D 12. +- VK_LAYER_LUNARG_api_dump is useful to dump Vulkan commands produced by + libvkd3d. +- [Fossilize](https://github.com/ValveSoftware/Fossilize) might be + useful for debugging crashes in driver shader compiler. Just capture + pipelines using VK_LAYER_fossilize and use fossilize-replay to + reproduce the crash. + +# Tests + +Use the following command to run tests: + +```sh +$ make check +``` + +Tests can also be run individually, for example: + +```sh +$ make tests/d3d12 && ./tests/d3d12 +$ VKD3D_TEST_FILTER=clear_render_target ./tests/d3d12 +``` + +To cross-compile tests for Windows run the following command: + +```sh +$ make crosstest +``` + +## Shader bytecode in tests + +Some tests include compiled shader bytecode. Shader bytecode should be +generated with `/Qstrip_debug /Qstrip_reflect` options. For example: + +```sh +$ fxc /Qstrip_debug /Qstrip_reflect /T ps_5_0 source.hlsl /Fo output.dxbc +``` + +# See also + +- [Todo](Todo) +- [Known Issues](Known-Issues)