QRhiVulkanInitParams Struct

Detailed Description

A Vulkan-based QRhi needs at minimum a valid QVulkanInstance. It is up to the user to ensure this is available and initialized. This is typically done in main() similarly to the following:

 int main(int argc, char **argv)
 {
     ...

     QVulkanInstance inst;
     inst.setLayers({ "VK_LAYER_KHRONOS_validation" }); // for debugging only, not for release builds
     inst.setExtensions(QRhiVulkanInitParams::preferredInstanceExtensions());
     if (!inst.create())
         qFatal("Vulkan not available");

     ...
 }

This example enables the Vulkan validation layers, when they are available, and also enables the instance-level extensions QRhi reports as desirable (such as, VK_KHR_get_physical_device_properties2), as long as they are supported by the Vulkan implementation at run time.

The former is optional, and is useful during the development phase QVulkanInstance conveniently redirects messages and warnings to qDebug. Avoid enabling it in production builds, however. The latter is strongly recommended, and is important in order to make certain features functional (for example, QRhi::CustomInstanceStepRate).

Once this is done, a Vulkan-based QRhi can be created by passing the instance and a QWindow with its surface type set to QSurface::VulkanSurface:

 QRhiVulkanInitParams params;
 params.inst = vulkanInstance;
 params.window = window;
 rhi = QRhi::create(QRhi::Vulkan, &params);

The window is optional and can be omitted. This is not recommended however because there is then no way to ensure presenting is supported while choosing a graphics queue.

To request additional extensions to be enabled on the Vulkan device, list them in deviceExtensions. This can be relevant when integrating with native Vulkan rendering code.

It is expected that the backend's desired list of instance extensions will be queried by calling the static function preferredInstanceExtensions() before initializing a QVulkanInstance. The returned list can be safely passed to QVulkanInstance::setExtensions() as-is, because unsupported extensions are filtered out automatically. If this is not done, certain features, such as QRhi::CustomInstanceStepRate may be reported as unsupported even when the Vulkan implementation on the system has support for the relevant functionality.

For full functionality the QVulkanInstance needs to have API 1.1 enabled, when available. This means calling QVulkanInstance::setApiVersion() with 1.1 or higher whenever QVulkanInstance::supportedApiVersion() reports that at least Vulkan 1.1 is supported. If this is not done, certain features, such as QRhi::RenderTo3DTextureSlice may be reported as unsupported even when the Vulkan implementation on the system supports Vulkan 1.1 or newer.

Working with existing Vulkan devices

When interoperating with another graphics engine, it may be necessary to get a QRhi instance that uses the same Vulkan device. This can be achieved by passing a pointer to a QRhiVulkanNativeHandles to QRhi::create().

The physical device must always be set to a non-null value. If the intention is to just specify a physical device, but leave the rest of the VkDevice and queue creation to QRhi, then no other members need to be filled out in the struct. For example, this is the case when working with OpenXR.

To adopt an existing VkDevice, the device field must be set to a non-null value as well. In addition, the graphics queue family index is required. The queue index is optional, as the default of 0 is often suitable.

Optionally, an existing command pool object can be specified as well. Also optionally, vmemAllocator can be used to share the same Vulkan memory allocator between two QRhi instances.

The QRhi does not take ownership of any of the external objects.

Applications are encouraged to query the list of desired device extensions by calling the static function preferredExtensionsForImportedDevice(), and enable them on the VkDevice. Otherwise certain QRhi features may not be available.