QVulkanWindow Class

There are two notable differences to be aware of: First, with Vulkan Y points down the screen in clip space, while OpenGL uses an upwards pointing Y axis. Second, the standard OpenGL projection matrix assume a near and far plane values of -1 and 1, while Vulkan prefers 0 and 1.

In order to help applications migrate from OpenGL-based code without having to flip Y coordinates in the vertex data, and to allow using QMatrix4x4 functions like QMatrix4x4::perspective() while keeping the Vulkan viewport's minDepth and maxDepth set to 0 and 1, QVulkanWindow provides a correction matrix retrievable by calling clipCorrectionMatrix().

While disabled by default, multisample antialiasing is fully supported by QVulkanWindow. Additional color buffers and resolving into the swapchain's non-multisample buffers are all managed automatically.

To query the supported sample counts, call supportedSampleCounts(). When the returned set contains 4, 8, ..., passing one of those values to setSampleCount() requests multisample rendering.

When supportsGrab() returns true, QVulkanWindow can perform readbacks from the color buffer into a QImage. grab() is a slow and inefficient operation, so frequent usage should be avoided. It is nonetheless valuable since it allows applications to take screenshots, or tools and tests to process and verify the output of the GPU rendering.

While many applications will be fine with the default behavior of QVulkanWindow when it comes to swapchain image formats, setPreferredColorFormats() allows requesting a pre-defined format. This is useful most notably when working in the sRGB color space. Passing a format like VK_FORMAT_B8G8R8A8_SRGB results in choosing an sRGB format, when available.

During application development it can be extremely valuable to have the Vulkan validation layers enabled. As shown in the example code above, calling QVulkanInstance::setLayers() on the QVulkanInstance before QVulkanInstance::create() enables validation, assuming the Vulkan driver stack in the system contains the necessary layers.

To enable instance layers, call QVulkanInstance::setLayers() before creating the QVulkanInstance. To query what instance layer are available, call QVulkanInstance::supportedLayers().

To enable device extensions, call setDeviceExtensions() early on when setting up the QVulkanWindow. To query what device extensions are available, call supportedDeviceExtensions().

Specifying an unsupported layer or extension is handled gracefully: this will not fail instance or device creation, but the layer or extension request is rather ignored.

When it comes to device features, QVulkanWindow enables all Vulkan 1.0 features that are reported as supported from vkGetPhysicalDeviceFeatures(). As an exception to this rule, robustBufferAccess is never enabled. Use the callback mechanism described below, if enabling that feature is desired.

Just enabling the 1.0 core features is not always sufficient, and therefore full control over the VkPhysicalDeviceFeatures used for device creation is possible too by registering a callback function with setEnabledFeaturesModifier(). When set, the callback function is invoked, letting it alter the VkPhysicalDeviceFeatures, instead of enabling only the 1.0 core features.

See also QVulkanInstance, QWindow

A function that is called during graphics initialization to alter the VkPhysicalDeviceFeatures that is passed in when creating a Vulkan device object.

By default QVulkanWindow enables all Vulkan 1.0 core features that the physical device reports as supported, with certain exceptions. In praticular, robustBufferAccess is always disabled in order to avoid unexpected performance hits.

This however is not always sufficient when working with Vulkan 1.1 or 1.2 features and extensions. Hence this callback mechanism.

The VkPhysicalDeviceFeatures reference passed in is all zeroed out at the point when the function is invoked. It is up to the function to change members to true, or set up pNext chains as it sees fit.

See Also▲

flags QVulkanWindow::Flags

This enum describes the flags that can be passed to setFlags().

The Flags type is a typedef for QFlags<Flag>. It stores an OR combination of Flag values.

A function that is called during graphics initialization to add additional queues that should be created.

Set if the renderer needs additional queues besides the default graphics queue (e.g. a transfer queue). The provided queue family properties can be used to select the indices for the additional queues. The renderer can subsequently request the actual queue in initResources().

See Also▲

Constructs a new QVulkanWindow with the given parent.

The surface type is set to QSurface::VulkanSurface.

Destructor.

Returns the list of properties for the supported physical devices in the system.

Returns a QMatrix4x4 that can be used to correct for coordinate system differences between OpenGL and Vulkan.

By pre-multiplying the projection matrix with this matrix, applications can continue to assume that Y is pointing upwards, and can set minDepth and maxDepth in the viewport to 0 and 1, respectively, without having to do any further corrections to the vertex Z positions. Geometry from OpenGL applications can then be used as-is, assuming a rasterization state matching the OpenGL culling and front face settings.

Returns the color buffer format used by the swapchain.

See Also▲

Returns the number of frames that can be potentially active at the same time.

    class Renderer {
        void startNextFrame();
        // ...

        VkDescriptorBufferInfo m_uniformBufInfo[QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT];
        QVulkanWindow *m_window = nullptr;
    };

    void Renderer::startNextFrame()
    {
        const int count = m_window->concurrentFrameCount();
        // for (int i = 0; i < count; ++i)
            // m_uniformBufInfo[i] = ...
        // ...
    }

See Also▲

Returns a new instance of QVulkanWindowRenderer.

This virtual function is called once during the lifetime of the window, at some point after making it visible for the first time.

The default implementation returns null and so no rendering will be performed apart from clearing the buffers.

The window takes ownership of the returned renderer object.

Returns The active command buffer for the current swap chain image. Implementations of QVulkanWindowRenderer::startNextFrame() are expected to add commands to this command buffer.

Returns the current frame index in the range [0, concurrentFrameCount() - 1].

Renderer implementations will have to ensure that uniform data and other dynamic resources exist in multiple copies, in order to prevent frame N altering the data used by the still-active frames N - 1, N - 2, ... N - concurrentFrameCount() + 1.

To avoid relying on dynamic array sizes, applications can use MAX_CONCURRENT_FRAME_COUNT when declaring arrays. This is guaranteed to be always equal to or greater than the value returned from concurrentFrameCount(). Such arrays can then be indexed by the value returned from this function.

    class Renderer {
        void startNextFrame();
        // ...

        VkDescriptorBufferInfo m_uniformBufInfo[QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT];
        QVulkanWindow *m_window = nullptr;
    };

    void Renderer::startNextFrame()
    {
        VkDescriptorBufferInfo &uniformBufInfo(m_uniformBufInfo[m_window->currentFrame()]);
        // ...
    }

See Also▲

Returns a VkFramebuffer for the current swapchain image using the default render pass.

The framebuffer has two attachments (color, depth-stencil) when multisampling is not in use, and three (color resolve, depth-stencil, multisample color) when sampleCountFlagBits() is greater than VK_SAMPLE_COUNT_1_BIT. Renderers must take this into account, for example when providing clear values.

See Also▲

Returns the current swap chain image index in the range [0, swapChainImageCount() - 1].

Returns a typical render pass with one sub-pass.

See Also▲

Returns the format used by the depth-stencil buffer(s).

Returns the depth-stencil image.

Returns the depth-stencil image view.

Returns the active logical device.

Returns a device local memory type index suitable for general use.

Return the requested flags.

See Also▲

This signal is emitted when the image is ready.

This function must be called exactly once in response to each invocation of the QVulkanWindowRenderer::startNextFrame() implementation. At the time of this call, the main command buffer, exposed via currentCommandBuffer(), must have all necessary rendering commands added to it since this function will trigger submitting the commands and queuing the present command.

See Also▲

Builds and renders the next frame without presenting it, then performs a blocking readback of the image content.

Returns the image if the renderer's startNextFrame() implementation calls back frameReady() directly. Otherwise, returns an incomplete image, that has the correct size but not the content yet. The content will be delivered via the frameGrabbed() signal in the latter case.

Returns the active graphics command pool.

Returns the active graphics queue.

Returns the family index of the active graphics queue.

This function was introduced in Qt 5.15.

Returns a host visible memory type index suitable for general use.

The returned memory type will be both host visible and coherent. In addition, it will also be cached, if possible.

Returns true if this window has successfully initialized all Vulkan resources, including the swapchain.

Returns the specified multisample color image, or VK_NULL_HANDLE if multisampling is not in use.

idx must be in the range [0, swapChainImageCount() - 1].

Returns the specified multisample color image view, or VK_NULL_HANDLE if multisampling is not in use.

idx must be in the range [0, swapChainImageCount() - 1].

Returns the active physical device.

Returns a pointer to the properties for the active physical device.

Returns the current sample count as a VkSampleCountFlagBits value.

When targeting the default render target, the rasterizationSamples field of VkPipelineMultisampleStateCreateInfo must be set to this value.

See Also▲

Sets the list of device extensions to be enabled.

Unsupported extensions are ignored.

The swapchain extension will always be added automatically, no need to include it in this list.

Sets the enabled device features modification function modifier.

This function was introduced in Qt 6.4.

See Also▲

Configures the behavior based on the provided flags.

See Also▲

Requests the usage of the physical device with index idx. The index corresponds to the list returned from availablePhysicalDevices().

By default the first physical device is used.

Sets the preferred formats of the swapchain.

By default no application-preferred format is set. In this case the surface's preferred format will be used or, in absence of that, VK_FORMAT_B8G8R8A8_UNORM.

The list in formats is ordered. If the first format is not supported, the second will be considered, and so on. When no formats in the list are supported, the behavior is the same as in the default case.

To query the actual format after initialization, call colorFormat().

See Also▲

Sets the queue create info modification function modifier.

This function was introduced in Qt 5.15.

See Also▲

Requests multisample antialiasing with the given sampleCount. The valid values are 1, 2, 4, 8, ... up until the maximum value supported by the physical device.

When the sample count is greater than 1, QVulkanWindow will create a multisample color buffer instead of simply targeting the swapchain's images. The rendering in the multisample buffer will get resolved into the non-multisample buffers at the end of each frame.

To examine the list of supported sample counts, call supportedSampleCounts().

When setting up the rendering pipeline, call sampleCountFlagBits() to query the active sample count as a VkSampleCountFlagBits value.

See Also▲

Returns the list of the extensions that are supported by logical devices created from the physical device selected by setPhysicalDeviceIndex().

Returns the set of supported sample counts when using the physical device selected by setPhysicalDeviceIndex(), as a sorted list.

By default QVulkanWindow uses a sample count of 1. By calling setSampleCount() with a different value (2, 4, 8, ...) from the set returned by this function, multisample anti-aliasing can be requested.

See Also▲

Returns true if the swapchain supports usage as transfer source, meaning grab() is functional.

Returns the specified swap chain image.

idx must be in the range [0, swapChainImageCount() - 1].

Returns the number of images in the swap chain.

Returns the image size of the swapchain.

This usually matches the size of the window, but may also differ in case vkGetPhysicalDeviceSurfaceCapabilitiesKHR reports a fixed size.

Returns the specified swap chain image view.

idx must be in the range [0, swapChainImageCount() - 1].

This variable holds a constant value that is always equal to or greater than the maximum value of concurrentFrameCount().