wine/vkd3d
0
0
Fork 0
mirror of https://gitlab.winehq.org/wine/vkd3d.git synced 2025-04-13 05:43:18 -07:00
Code Issues Packages Projects Releases Wiki Activity

Convert all files to CRLF line endings.

Alexandre Julliard
2024-09-17 14:11:10 +02:00
parent 52846c72fc
commit ad54c07d3b
4 changed files with 872 additions and 878 deletions
Download Patch File Download Diff File Expand all files Collapse all files

724
Building-a-MinGW-WoW64-Wine-with-a-custom-vkd3d-build.md

File diff suppressed because it is too large Load Diff

490
Known-Issues.md

@@ -1,248 +1,242 @@
Vkd3d is considered as work-in-progress, there are known issues that Vkd3d is considered as work-in-progress, there are known issues that
have to be resolved. Moreover, there are some incompatibilities between have to be resolved. Moreover, there are some incompatibilities between
Vulkan and Direct3D 12. Vulkan and Direct3D 12.
<table> <table>
<thead> <thead>
<tr class="header"> <tr class="header">
<th><p>Issue</p></th> <th><p>Issue</p></th>
<th><p>Description</p></th> <th><p>Description</p></th>
<th><p>Current implementation</p></th> <th><p>Current implementation</p></th>
<th><p>Possible solutions</p></th> <th><p>Possible solutions</p></th>
</tr> </tr>
</thead> </thead>
<tbody> <tbody>
<tr class="odd"> <tr class="even">
<td></td> <td><p>NULL descriptors</p></td>
<td></td> <td><p>Vulkan doesn't support NULL descriptors.</p></td>
<td></td> <td><p>NULL descriptors are currently emulated using dummy resources.
<td></td> Sparse resources are used when
</tr> `residencyNonResidentStrict` is supported. The current
<tr class="even"> solution doesn't handle `resinfo` and
<td><p>NULL descriptors</p></td> `bufinfo` instructions correctly.</p></td>
<td><p>Vulkan doesn't support NULL descriptors.</p></td> <td></td>
<td><p>NULL descriptors are currently emulated using dummy resources. </tr>
Sparse resources are used when <tr class="odd">
`residencyNonResidentStrict` is supported. The current <td><p>Indirect draws</p></td>
solution doesn't handle `resinfo` and <td><p>In Direct3D 12 indirect draws can update vertex buffer views,
`bufinfo` instructions correctly.</p></td> index buffer views, root constants and root descriptors.</p></td>
<td></td> <td><p>Not supported in Vulkan.</p></td>
</tr> <td><ul>
<tr class="odd"> <li>A Vulkan extension.</li>
<td><p>Indirect draws</p></td> <li>It could be emulated in an inefficient way.</li>
<td><p>In Direct3D 12 indirect draws can update vertex buffer views, </ul></td>
index buffer views, root constants and root descriptors.</p></td> </tr>
<td><p>Not supported in Vulkan.</p></td> <tr class="even">
<td><ul> <td><p>Memory object residency</p></td>
<li>A Vulkan extension.</li> <td><p>Memory object residency management doesn't exist in Vulkan. In
<li>It could be emulated in an inefficient way.</li> Direct3D 12 resources and heaps can be evicted. Resource descriptors are
</ul></td> still valid after a resource is made resident again.</p></td>
</tr> <td></td>
<tr class="even"> <td><p>We can try to evict memory manually (e.g. using sparse
<td><p>Memory object residency</p></td> bindings).</p></td>
<td><p>Memory object residency management doesn't exist in Vulkan. In </tr>
Direct3D 12 resources and heaps can be evicted. Resource descriptors are <tr class="odd">
still valid after a resource is made resident again.</p></td> <td><p>Queries initial state</p></td>
<td></td> <td><p>Queries are initially in the available state in Direct3D 12.
<td><p>We can try to evict memory manually (e.g. using sparse Results are all equal to zero.</p></td>
bindings).</p></td> <td><p>We track the query state, and fill buffer with zeroes when a
</tr> query wasn't issued. The current implementation doesn't handle command
<tr class="odd"> lists executed out-of-order.</p></td>
<td><p>Queries initial state</p></td> <td></td>
<td><p>Queries are initially in the available state in Direct3D 12. </tr>
Results are all equal to zero.</p></td> <tr class="even">
<td><p>We track the query state, and fill buffer with zeroes when a <td><p>Texture array views</p></td>
query wasn't issued. The current implementation doesn't handle command <td><p>Texture array views and textures views are incompatible in
lists executed out-of-order.</p></td> Vulkan.</p></td>
<td></td> <td></td>
</tr> <td></td>
<tr class="even"> </tr>
<td><p>Texture array views</p></td> <tr class="odd">
<td><p>Texture array views and textures views are incompatible in <td><p>Descriptor heaps</p></td>
Vulkan.</p></td> <td><p>Direct3D 12 and Vulkan binding models are largely different. It
<td></td> seems to be implied that Direct3D 12 CBV/SRV/UAV descriptor heaps exist
<td></td> in GPU memory, but there's no real equivalent for that in Vulkan. Vulkan
</tr> descriptor sets are probably the closest match, but among others have
<tr class="odd"> the issue that the descriptor type (CBV, SRV or UAV) would need to be
<td><p>Descriptor heaps</p></td> declared in advance, while in Direct3D 12 these can be mixed freely
<td><p>Direct3D 12 and Vulkan binding models are largely different. It within the descriptor heap. Run-time translation from Direct3D 12
seems to be implied that Direct3D 12 CBV/SRV/UAV descriptor heaps exist binding model to Vulkan binding model is expected to introduce a
in GPU memory, but there's no real equivalent for that in Vulkan. Vulkan noticeable overhead.</p></td>
descriptor sets are probably the closest match, but among others have <td></td>
the issue that the descriptor type (CBV, SRV or UAV) would need to be <td></td>
declared in advance, while in Direct3D 12 these can be mixed freely </tr>
within the descriptor heap. Run-time translation from Direct3D 12 <tr class="even">
binding model to Vulkan binding model is expected to introduce a <td><p>CPU descriptor heaps</p></td>
noticeable overhead.</p></td> <td><p>Direct3D 12 allows to create and prepare descriptors in CPU
<td></td> heaps. Descriptors from CPU descriptor heaps can be copied to
<td></td> shader-visible descriptor heaps. In Vulkan, there are only
</tr> shared-visibile descriptor sets, and
<tr class="even"> `VkCopyDescriptorSet` is implemented very inefficiently
<td><p>CPU descriptor heaps</p></td> on some drivers.</p></td>
<td><p>Direct3D 12 allows to create and prepare descriptors in CPU <td></td>
heaps. Descriptors from CPU descriptor heaps can be copied to <td></td>
shader-visible descriptor heaps. In Vulkan, there are only </tr>
shared-visibile descriptor sets, and <tr class="odd">
`VkCopyDescriptorSet` is implemented very inefficiently <td><p>Descriptor heaps concurrency</p></td>
on some drivers.</p></td> <td><p>Some apps appear to concurrently overwrite descriptors in
<td></td> descriptor heaps. We need to confirm that this works reliably on
<td></td> Windows. It might not be a problem on Windows because implementations
</tr> might simply write or copy descriptors data in memory. However, in our
<tr class="odd"> translation layer we have to manage VkImageView objects and potentially
<td><p>Descriptor heaps concurrency</p></td> reference count them.</p></td>
<td><p>Some apps appear to concurrently overwrite descriptors in <td></td>
descriptor heaps. We need to confirm that this works reliably on <td></td>
Windows. It might not be a problem on Windows because implementations </tr>
might simply write or copy descriptors data in memory. However, in our <tr class="even">
translation layer we have to manage VkImageView objects and potentially <td><p>Descriptors for destroyed resources</p></td>
reference count them.</p></td> <td><p>Apps keep descriptors for destroyed resources in descriptor
<td></td> heaps. This is problematic and may lead to invalid usage in
<td></td> Vulkan.</p></td>
</tr> <td></td>
<tr class="even"> <td></td>
<td><p>Descriptors for destroyed resources</p></td> </tr>
<td><p>Apps keep descriptors for destroyed resources in descriptor <tr class="odd">
heaps. This is problematic and may lead to invalid usage in <td><p>ID3D12Fence</p></td>
Vulkan.</p></td> <td><p>ID3D12Fence have an associated UINT64 value (see also timeline
<td></td> semaphores). In addition, ID3D12Fence can be signaled by GPU or CPU, and
<td></td> can also be waited for on CPU or ID3D12CommandQueue. Moreover, it's
</tr> possible to signal native Win32 events when a fence reaches a certain
<tr class="odd"> value. In Vulkan, there is no way to signal native synchronization
<td><p>ID3D12Fence</p></td> objects (e.g. HANDLEs to Win32 events or file descriptors) when, e.g.
<td><p>ID3D12Fence have an associated UINT64 value (see also timeline VkFence is signaled.</p></td>
semaphores). In addition, ID3D12Fence can be signaled by GPU or CPU, and <td></td>
can also be waited for on CPU or ID3D12CommandQueue. Moreover, it's <td><p>Timeline semaphores.</p></td>
possible to signal native Win32 events when a fence reaches a certain </tr>
value. In Vulkan, there is no way to signal native synchronization <tr class="even">
objects (e.g. HANDLEs to Win32 events or file descriptors) when, e.g. <td><p>Sampler border color</p></td>
VkFence is signaled.</p></td> <td><p>In Direct3D 12 the sampler border color is defined as a float4
<td></td> vector. In Vulkan the border color is constrained by the values of the
<td><p>Timeline semaphores.</p></td> VkBorderColor enum. (It might not be that important because we haven't
</tr> encountered application which needs this yet).</p></td>
<tr class="even"> <td></td>
<td><p>Sampler border color</p></td> <td></td>
<td><p>In Direct3D 12 the sampler border color is defined as a float4 </tr>
vector. In Vulkan the border color is constrained by the values of the <tr class="odd">
VkBorderColor enum. (It might not be that important because we haven't <td><p>Separate resource state for depth-stencil</p></td>
encountered application which needs this yet).</p></td> <td><p>In Direct3D, the depth aspect and the stencil aspect of an image
<td></td> can be in different image layouts.</p></td>
<td></td> <td></td>
</tr> <td><p>Vulkan extension.</p></td>
<tr class="odd"> </tr>
<td><p>Separate resource state for depth-stencil</p></td> <tr class="even">
<td><p>In Direct3D, the depth aspect and the stencil aspect of an image <td><p>Out-of-bounds resource access</p></td>
can be in different image layouts.</p></td> <td><p>Vulkan doesn't give the same guarantees as Direct3D 12 when it
<td></td> comes to out-of-bounds resource access.</p></td>
<td><p>Vulkan extension.</p></td> <td></td>
</tr> <td></td>
<tr class="even"> </tr>
<td><p>Out-of-bounds resource access</p></td> <tr class="odd">
<td><p>Vulkan doesn't give the same guarantees as Direct3D 12 when it <td><p>D3D12_DEFAULT_RESOURCE_PLACEMENT_ALIGNMENT</p></td>
comes to out-of-bounds resource access.</p></td> <td><p>On radv with AMD Polaris GPUs, the required alignment for
<td></td> textures may be higher than 0x10000
<td></td> (D3D12_DEFAULT_RESOURCE_PLACEMENT_ALIGNMENT), e.g. 0x20000 or 0x40000.
</tr> World of Warcraft aligns only to
<tr class="odd"> D3D12_DEFAULT_RESOURCE_PLACEMENT_ALIGNMENT and ignores the alignment
<td><p>D3D12_DEFAULT_RESOURCE_PLACEMENT_ALIGNMENT</p></td> returned from `GetResourceAllocationInfo()`.</p></td>
<td><p>On radv with AMD Polaris GPUs, the required alignment for <td><p>We currently allocate additional device memory when the heap
textures may be higher than 0x10000 offset is misaligned.</p></td>
(D3D12_DEFAULT_RESOURCE_PLACEMENT_ALIGNMENT), e.g. 0x20000 or 0x40000. <td></td>
World of Warcraft aligns only to </tr>
D3D12_DEFAULT_RESOURCE_PLACEMENT_ALIGNMENT and ignores the alignment <tr class="even">
returned from `GetResourceAllocationInfo()`.</p></td> <td><p>Swapchain</p></td>
<td><p>We currently allocate additional device memory when the heap <td><ul>
offset is misaligned.</p></td> <li>sRGB views.</li>
<td></td> <li>Scaling.</li>
</tr> <li>Present mode without recreating.</li>
<tr class="even"> </ul></td>
<td><p>Swapchain</p></td> <td><p>We currently use additional set of images and blit from them to
<td><ul> the real swapchain.</p></td>
<li>sRGB views.</li> <td></td>
<li>Scaling.</li> </tr>
<li>Present mode without recreating.</li> <tr class="odd">
</ul></td> <td><p>Conditional rendering</p></td>
<td><p>We currently use additional set of images and blit from them to <td><p>In D3D12, 64-bit values are used.
the real swapchain.</p></td> `VK_EXT_conditional_rendering` uses 32-bit values. In
<td></td> D3D12, conditional rendering affects copy commands.</p></td>
</tr> <td><p>We do what the `VK_EXT_conditional_rendering`
<tr class="odd"> extension does.</p></td>
<td><p>Conditional rendering</p></td> <td></td>
<td><p>In D3D12, 64-bit values are used. </tr>
`VK_EXT_conditional_rendering` uses 32-bit values. In <tr class="even">
D3D12, conditional rendering affects copy commands.</p></td> <td><p>Binary occlusion queries</p></td>
<td><p>We do what the `VK_EXT_conditional_rendering` <td><p>D3D12 guarantees binary occlusion queries result in only 0 and
extension does.</p></td> 1.</p></td>
<td></td> <td></td>
</tr> <td></td>
<tr class="even"> </tr>
<td><p>Binary occlusion queries</p></td> <tr class="odd">
<td><p>D3D12 guarantees binary occlusion queries result in only 0 and <td><p>Strip cut value</p></td>
1.</p></td> <td><p>In Vulkan the strip cut value is derived from the index format.
<td></td> In Direct3D 12 0xffff or 0xffffffff can be used as the strip cut value
<td></td> with 16-bit and 32-bit index buffer formats.</p></td>
</tr> <td><p>Not supported in Vulkan.</p></td>
<tr class="odd"> <td></td>
<td><p>Strip cut value</p></td> </tr>
<td><p>In Vulkan the strip cut value is derived from the index format. <tr class="even">
In Direct3D 12 0xffff or 0xffffffff can be used as the strip cut value <td><p>GPU virtual addresses</p></td>
with 16-bit and 32-bit index buffer formats.</p></td> <td><p>In Direct3D 12, vertex buffers, index buffers, stream output
<td><p>Not supported in Vulkan.</p></td> buffers and root descriptors are bound using GPU virtual addresses. In
<td></td> Vulkan, VkBuffer objects with an offset are used instead.</p></td>
</tr> <td><p>Fake virtual addresses are allocated for buffers. Virtual
<tr class="even"> addresses have to be resolved to VkBuffer and an offset. The resolving
<td><p>GPU virtual addresses</p></td> of GPU virtual address introduces unnecessary overhead.</p></td>
<td><p>In Direct3D 12, vertex buffers, index buffers, stream output <td><ul>
buffers and root descriptors are bound using GPU virtual addresses. In <li>`VK_EXT_device_buffer_address` can be used for root
Vulkan, VkBuffer objects with an offset are used instead.</p></td> descriptors. Unfortunately, the extension doesn't help with vertex,
<td><p>Fake virtual addresses are allocated for buffers. Virtual index and stream output buffers. The extension also introduces some
addresses have to be resolved to VkBuffer and an offset. The resolving complications, e.g. multiple buffers can be bound to the same virtual
of GPU virtual address introduces unnecessary overhead.</p></td> memory address.</li>
<td><ul> <li>Ideally, we could bind vertex, index and stream output buffers using
<li>`VK_EXT_device_buffer_address` can be used for root `VkDeviceAddress` in Vulkan.</li>
descriptors. Unfortunately, the extension doesn't help with vertex, </ul></td>
index and stream output buffers. The extension also introduces some </tr>
complications, e.g. multiple buffers can be bound to the same virtual <tr class="odd">
memory address.</li> <td><p>`GetResourceAllocationInfo()`</p></td>
<li>Ideally, we could bind vertex, index and stream output buffers using <td><p>In Vulkan, a resource needs to be created to get allocation
`VkDeviceAddress` in Vulkan.</li> info.</p></td>
</ul></td> <td><p>We create temporary resources to get allocation info.</p></td>
</tr> <td></td>
<tr class="odd"> </tr>
<td><p>`GetResourceAllocationInfo()`</p></td> <tr class="even">
<td><p>In Vulkan, a resource needs to be created to get allocation <td><p>`SetEventOnCompletion()` /
info.</p></td> `SetEventOnMultipleFenceCompletion()`</p></td>
<td><p>We create temporary resources to get allocation info.</p></td> <td></td>
<td></td> <td><p>We have a separate thread that signals Win32 events.</p></td>
</tr> <td><p>Timeline semaphores.</p></td>
<tr class="even"> </tr>
<td><p>`SetEventOnCompletion()` / <tr class="odd">
`SetEventOnMultipleFenceCompletion()`</p></td> <td><p>Copy between depth-stencil and color formats</p></td>
<td></td> <td><p>In Direct3D 12 it is possible to copy data between compatible
<td><p>We have a separate thread that signals Win32 events.</p></td> color and depth-stencil resources.</p></td>
<td><p>Timeline semaphores.</p></td> <td><p>We currently use a temporary buffer to perform the copy
</tr> operation.</p></td>
<tr class="odd"> <td><p>We should implement the copy operation in shaders for graphics
<td><p>Copy between depth-stencil and color formats</p></td> and compute queues.</p></td>
<td><p>In Direct3D 12 it is possible to copy data between compatible </tr>
color and depth-stencil resources.</p></td> <tr class="even">
<td><p>We currently use a temporary buffer to perform the copy <td><p>Dynamic states</p></td>
operation.</p></td> <td><p>In Direct3D 12 the following states are dynamic: vertex buffer
<td><p>We should implement the copy operation in shaders for graphics strides, the primitive topology and viewport/scissor counts. In Vulkan,
and compute queues.</p></td> those states require compiling a new pipeline. The primitive topology
</tr> type is still specified when Direct3D 12 pipeline states are created
<tr class="even"> (one of points, lines, triangles, or patches).</p></td>
<td><p>Dynamic states</p></td> <td><p>Vulkan pipelines are created on draw call time when we know all
<td><p>In Direct3D 12 the following states are dynamic: vertex buffer parameters to compile the pipeline.</p></td>
strides, the primitive topology and viewport/scissor counts. In Vulkan, <td><ul>
those states require compiling a new pipeline. The primitive topology <li>Add pipeline cache.</li>
type is still specified when Direct3D 12 pipeline states are created <li>Compile pipelines speculatively.</li>
(one of points, lines, triangles, or patches).</p></td> </ul></td>
<td><p>Vulkan pipelines are created on draw call time when we know all </tr>
parameters to compile the pipeline.</p></td> </tbody>
<td><ul> </table>
<li>Add pipeline cache.</li>
<li>Compile pipelines speculatively.</li>
</ul></td>
</tr>
</tbody>
</table>

268
Todo.md

@@ -1,134 +1,134 @@
## libvkd3d ## libvkd3d
- Try to use VK_EXT_buffer_device_address for GPU addresses (partially - Try to use VK_EXT_buffer_device_address for GPU addresses (partially
done - jkucia). done - jkucia).
- Add tests for out-of-bounds access with vertex buffers. - Add tests for out-of-bounds access with vertex buffers.
- Improve multi-queue support. - Improve multi-queue support.
- Queue family ownership transfer. - Queue family ownership transfer.
- Fix all Vulkan validation errors. - Fix all Vulkan validation errors.
- Fix clears for A8_UNORM. - Fix clears for A8_UNORM.
- Implement UAVs in vertex processing shader stages. - Implement UAVs in vertex processing shader stages.
- Implement support for multiple viewports. - Implement support for multiple viewports.
- Test and fix copying between BC and other compatible formats. - Test and fix copying between BC and other compatible formats.
- State decay for resources and queue ownership transfer for resources. - State decay for resources and queue ownership transfer for resources.
- Reduce the number of queue submits. Queue submits are generally - Reduce the number of queue submits. Queue submits are generally
expensive, especially on recent kernels with amdgpu (mostly done - expensive, especially on recent kernels with amdgpu (mostly done -
jkucia). jkucia).
- Merge vkCmdPipelineBarrier() calls. - Merge vkCmdPipelineBarrier() calls.
- Try to avoid fence worker thread when possible. - Try to avoid fence worker thread when possible.
- Implement stencil aspect resource state transitions. - Implement stencil aspect resource state transitions.
- Implement cache for SPIR-V shaders? - Implement cache for SPIR-V shaders?
- Implement disk pipeline/shader cache? - Implement disk pipeline/shader cache?
- Implement sparse resources? - Implement sparse resources?
- Optimize barriers (render passes, ClearUnorderedAccessView, transform - Optimize barriers (render passes, ClearUnorderedAccessView, transform
feedback). feedback).
- Memory residency. - Memory residency.
- Raytracing? - Raytracing?
- DirectML? - DirectML?
- Add support for sRGB swapchain views (VK_KHR_image_format_list). - Add support for sRGB swapchain views (VK_KHR_image_format_list).
- Add tests for validation of view format compatibility (RTV, SRV, UAV, - Add tests for validation of view format compatibility (RTV, SRV, UAV,
DSV). DSV).
## libvkd3d-shader ## libvkd3d-shader
- Add support for capturing components with stream output. - Add support for capturing components with stream output.
- Finish the DXIL work (Conor). - Finish the DXIL work (Conor).
- Add tests for OpenGL atomic counters. - Add tests for OpenGL atomic counters.
- Import SM4 to GLSL shader translation from wined3d (Henri). - Import SM4 to GLSL shader translation from wined3d (Henri).
- Allow ignoring checking the checksum when parsing DXBC, both from the - Allow ignoring checking the checksum when parsing DXBC, both from the
API and from the command line. API and from the command line.
- Always check that memory allocation didn't fail; for example, calls to - Always check that memory allocation didn't fail; for example, calls to
vkd3d_string_buffer_printf() usually are not checked. vkd3d_string_buffer_printf() usually are not checked.
- Finish API for scanning/gathering info from shaders (registers used, - Finish API for scanning/gathering info from shaders (registers used,
bindings used, parameters used, required limits, extensions). bindings used, parameters used, required limits, extensions).
- Implement ID3D11ShaderReflection et al. - Implement ID3D11ShaderReflection et al.
- Should we put everything into the same (chained) - Should we put everything into the same (chained)
vkd3d_shader_scan_dxbc_info struct, or split them up? (Split up the vkd3d_shader_scan_dxbc_info struct, or split them up? (Split up the
DXBC-specific ones from the rest?) DXBC-specific ones from the rest?)
- I guess HLSL compile flags should be preserved verbatim...? I don't - I guess HLSL compile flags should be preserved verbatim...? I don't
like the disparity we currently have. like the disparity we currently have.
- How to do things like constant table types? - How to do things like constant table types?
- Add support for SSBO. - Add support for SSBO.
- Support HLSL -\> sm6 compilation. - Support HLSL -\> sm6 compilation.
- Support direct HLSL -\> spirv compilation. This will be easier as - Support direct HLSL -\> spirv compilation. This will be easier as
things are refactored to account for vsir. things are refactored to account for vsir.
- Consider adding a CUDA frontend. - Consider adding a CUDA frontend.
#### TPF validation #### TPF validation
Vkd3d-shader generally assumes that Direct3D shader bytecode is valid Vkd3d-shader generally assumes that Direct3D shader bytecode is valid
and doesn't do much validation. We should introduce some kind of and doesn't do much validation. We should introduce some kind of
validation pass. The validation potentially could be optional, e.g. used validation pass. The validation potentially could be optional, e.g. used
only in debug builds. only in debug builds.
- Interpolation mode is the same for all variables in the input - Interpolation mode is the same for all variables in the input
register. register.
- Number of indices for resources (SM5 vs SM5.1). - Number of indices for resources (SM5 vs SM5.1).
## Tests ## Tests
- Make it possible to run all reasonable test combinations mixing these - Make it possible to run all reasonable test combinations mixing these
factors: factors:
- the library used to compile the shaders: vkd3d-shader, - the library used to compile the shaders: vkd3d-shader,
d3dcompiler_xx.dll or dxcompiler.dll; d3dcompiler_xx.dll or dxcompiler.dll;
- the Shader Model to target; - the Shader Model to target;
- the API to use to run the shader (d3d8, d3d9, d3d10, d3d11, d3d12, - the API to use to run the shader (d3d8, d3d9, d3d10, d3d11, d3d12,
Vulkan, GL); Vulkan, GL);
- when running on Windows, the actual library to use to run the - when running on Windows, the actual library to use to run the
shader: vkd3d or a native implementation; shader: vkd3d or a native implementation;
- possibly, one day, the library to use to recompile the shaders (it - possibly, one day, the library to use to recompile the shaders (it
currently only makes sense on macOS once we support the Apple shader currently only makes sense on macOS once we support the Apple shader
compiler for Metal; in all the other cases the choice is forced). compiler for Metal; in all the other cases the choice is forced).
- Run a decent subsets of those combinations in the CI. - Run a decent subsets of those combinations in the CI.
- Need more shader runners: OpenGL + GLSL (Henri has WIP), d3d10core, - Need more shader runners: OpenGL + GLSL (Henri has WIP), d3d10core,
d3d8 d3d8
- Some HLSL functionality was accepted despite a lack of tests. We need - Some HLSL functionality was accepted despite a lack of tests. We need
tests for: tests for:
- all tex\*() variants - all tex\*() variants
- D3DCOLORtoUBYTE4() different results on sm1 - D3DCOLORtoUBYTE4() different results on sm1
- min() - min()
- texture arrays - texture arrays
- centroid interpolation - centroid interpolation
- "linear centroid" keywords - "linear centroid" keywords
- noperspective interpolation - noperspective interpolation
- precise? - precise?
- texture types other than 2D - texture types other than 2D
- nontrivial tests for 2D multisample textures - nontrivial tests for 2D multisample textures
- GetDimensions() - GetDimensions()
- SampleCmp(), SampleCmpLevelZero() - SampleCmp(), SampleCmpLevelZero()
- depth output - depth output
- GS SV_PrimitiveID - GS SV_PrimitiveID
- For the sake of sm1 and its weird disjoint instruction sets, a lot - For the sake of sm1 and its weird disjoint instruction sets, a lot
of tests probably deserve VS variants as well. of tests probably deserve VS variants as well.
- Uniform reflection, which depends on uniform reflection API design - Uniform reflection, which depends on uniform reflection API design
- SM1 semantic matching (Zeb has this) - SM1 semantic matching (Zeb has this)
- Test that all of the SM1 input semantics work - Test that all of the SM1 input semantics work
- tbuffer - tbuffer
- We should properly gate features based on profile version, and test - We should properly gate features based on profile version, and test
that we are correctly doing this. that we are correctly doing this.
None of this necessarily needs to be extensions to the shader runner; we None of this necessarily needs to be extensions to the shader runner; we
can find a way to write C tests for these. 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 - 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. bit unfortunate that the tests in hlsl_d3d12.c are d3d12-specific.
- Untested sm4 -\> spirv paths: - Untested sm4 -\> spirv paths:
- "lod" shader instruction - "lod" shader instruction
- bufinfo and resinfo with NULL SRV and UAV descriptors - bufinfo and resinfo with NULL SRV and UAV descriptors
- D3D discard semantics - D3D discard semantics
## DXGI ## DXGI
- Fix adapter LUIDs in Wine. - Fix adapter LUIDs in Wine.
- Reimplement IDXGIAdapter3::QueryVideoMemoryInfo() on top of - Reimplement IDXGIAdapter3::QueryVideoMemoryInfo() on top of
VK_EXT_memory_budget. Ideally, Vulkan implementations should return VK_EXT_memory_budget. Ideally, Vulkan implementations should return
the memory budget based on total system load (memory used by all the memory budget based on total system load (memory used by all
graphics APIs). graphics APIs).
## Vulkan ## Vulkan
- Try to fix detached WSI surfaces after D3D9/D3D11 swapchain (OpenGL) - Try to fix detached WSI surfaces after D3D9/D3D11 swapchain (OpenGL)
is created for a window with D3D12 swapchain (Vulkan). is created for a window with D3D12 swapchain (Vulkan).
- Fix child window rendering for D3D12 RenderDoc. - Fix child window rendering for D3D12 RenderDoc.

268
home.md

@@ -1,134 +1,134 @@
--- ---
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)