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.

See also QVulkanInstance, QWindow

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.

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 {
        ...
        VkDescriptorBufferInfo m_uniformBufInfo[QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT];
    };

    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 {
        ...
        VkDescriptorBufferInfo m_uniformBufInfo[QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT];
    };

    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.