Set up a Vulkan backend

Tools and platform prerequisites#

Install the Vulkan SDK appropriate to the development platform, C++20 tooling, and CMake. Use vulkaninfo to inspect available implementations and device capabilities. Install a driver providing Vulkan support; an SDK alone does not supply a hardware implementation for every device. This reference profile targets Vulkan 1.3 and a Windows Win32 surface to match the primary DX12 journey. Cross-platform engine builds replace PlatformWindow’s implementation and request the appropriate WSI extensions for Linux or another supported platform. macOS deployment needs a suitable Vulkan portability implementation and its additional requirements; native Metal support is a separate backend topic.

Create an instance with deliberate extensions#

Ask the loader for its supported instance version. Enumerate instance extensions and layers before requesting them. Enable VK_KHR_surface and the platform’s surface extension. In a debug build, enable VK_LAYER_KHRONOS_validation and VK_EXT_debug_utils only when present, then create a debug messenger. On Windows, define VK_USE_PLATFORM_WIN32_KHR before including Vulkan headers and create a surface from HINSTANCE and HWND. Keep the surface alive through swap-chain use. Instance ownership is separate from VkDevice ownership; destroying the instance first invalidates dependent work.

Select a physical device#

Query device properties, Vulkan 1.3 support, extension support including VK_KHR_swapchain, queue families, surface presentation support, surface formats, and presentation modes. Query requested feature structures with vkGetPhysicalDeviceFeatures2. Do not assume every graphics queue can present to your surface.

VkPhysicalDeviceVulkan13Features supported13{
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_3_FEATURES};
VkPhysicalDeviceVulkan12Features supported12{
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_2_FEATURES};
supported13.pNext = &supported12;
VkPhysicalDeviceFeatures2 supported{
    VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2};
supported.pNext = &supported13;
vkGetPhysicalDeviceFeatures2(physicalDevice, &supported);

This excerpt assumes physicalDevice passed the API-version query. Require supported13.dynamicRendering, supported13.synchronization2, and supported12.timelineSemaphore for this chosen profile. Construct a separate requested feature chain with only the features the backend uses, and pass it to vkCreateDevice. The query chain is not a reason to enable every optional feature.

Compile HLSL to SPIR-V#

dxc -spirv -fspv-target-env=vulkan1.3 -T vs_6_0 -E VSMain -Zpr scene-vulkan.hlsl -Fo scene.vert.spv
dxc -spirv -fspv-target-env=vulkan1.3 -T ps_6_0 -E PSMain -Zpr scene-vulkan.hlsl -Fo scene.frag.spv

Use an explicitly authored Vulkan variant with non-conflicting image/sampler bindings. For example, set 0 binding 0 is the image, binding 1 is the sampler, and binding 2 is frame data. Declare matching locations between vertex attributes and stage interfaces. Do not compile the DX12 tutorial and assume its root signature is a Vulkan pipeline layout.

find_package(Vulkan REQUIRED)
add_executable(qubic_vulkan your_complete_backend_sources.cpp)
target_compile_features(qubic_vulkan PRIVATE cxx_std_20)
target_compile_definitions(qubic_vulkan PRIVATE VK_USE_PLATFORM_WIN32_KHR)
target_link_libraries(qubic_vulkan PRIVATE Vulkan::Vulkan)

Validate and diagnose#

Expected setup output is a chosen device/profile and successful instance/device creation with validation enabled in development. Record API version, driver, queue families, formats, and required features. A missing validation layer is a tooling issue; a missing presentation-capable queue is a device/surface capability issue. If vkCreateInstance fails, compare requested extensions against enumeration. If vkCreateDevice fails, inspect the requested feature chain and extension list. If SPIR-V validation fails, inspect target environment, stage interfaces, and layout declarations. Continue to backend execution. Official companion: Khronos HLSL in Vulkan.