QVulkanWindow Class

 class VulkanRenderer : public QVulkanWindowRenderer
 {
 public:
     VulkanRenderer(QVulkanWindow *w) : m_window(w), m_devFuncs(nullptr) { }

     void initResources() override
     {
         m_devFuncs = m_window->vulkanInstance()->deviceFunctions(m_window->device());
         // ..
     }
     void initSwapChainResources() override { /* ... */ }
     void releaseSwapChainResources() override { /* ... */ }
     void releaseResources() override { /* ... */ }

     void startNextFrame() override
     {
         VkCommandBuffer cmdBuf = m_window->currentCommandBuffer();
         // ...
         m_devFuncs->vkCmdBeginRenderPass(commandBuffer, renderPassBegin, contents);
         // ...
         m_window->frameReady();
     }

 private:
     QVulkanWindow *m_window;
     QVulkanDeviceFunctions *m_devFuncs;
 };

 class VulkanWindow : public QVulkanWindow
 {
 public:
     QVulkanWindowRenderer *createRenderer() override {
         return new VulkanRenderer(this);
     }
 };

 int main(int argc, char *argv[])
 {
     QGuiApplication app(argc, argv);

     QVulkanInstance inst;
     // enable the standard validation layers, when available
     inst.setLayers({ "VK_LAYER_KHRONOS_validation" });
     if (!inst.create())
         qFatal("Failed to create Vulkan instance: %d", inst.errorCode());

     VulkanWindow w;
     w.setVulkanInstance(&inst);
     w.showMaximized();

     return app.exec();
 }

Member Function Documentation

[explicit] QVulkanWindow::QVulkanWindow(QWindow *parent = nullptr)

Constructs a new QVulkanWindow with the given parent.

The surface type is set to QSurface::VulkanSurface.

[virtual noexcept] QVulkanWindow::~QVulkanWindow()

Destructor.

QList<VkPhysicalDeviceProperties> QVulkanWindow::availablePhysicalDevices()

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

QMatrix4x4 QVulkanWindow::clipCorrectionMatrix()

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.

VkFormat QVulkanWindow::colorFormat() const

Returns the color buffer format used by the swapchain.

See also setPreferredColorFormats().

int QVulkanWindow::concurrentFrameCount() const

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 currentFrame().

[virtual] QVulkanWindowRenderer *QVulkanWindow::createRenderer()

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.

VkCommandBuffer QVulkanWindow::currentCommandBuffer() const

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

int QVulkanWindow::currentFrame() const

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 concurrentFrameCount().

VkFramebuffer QVulkanWindow::currentFramebuffer() const

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 defaultRenderPass().

int QVulkanWindow::currentSwapChainImageIndex() const

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

VkRenderPass QVulkanWindow::defaultRenderPass() const

Returns a typical render pass with one sub-pass.

See also currentFramebuffer().

VkFormat QVulkanWindow::depthStencilFormat() const

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

VkImage QVulkanWindow::depthStencilImage() const

Returns the depth-stencil image.

VkImageView QVulkanWindow::depthStencilImageView() const

Returns the depth-stencil image view.

VkDevice QVulkanWindow::device() const

Returns the active logical device.

uint32_t QVulkanWindow::deviceLocalMemoryIndex() const

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

QVulkanWindow::Flags QVulkanWindow::flags() const

Return the requested flags.

See also setFlags().

[signal] void QVulkanWindow::frameGrabbed(const QImage &image)

This signal is emitted when the image is ready.

void QVulkanWindow::frameReady()

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 QVulkanWindowRenderer::startNextFrame().

QImage QVulkanWindow::grab()

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.

The returned QImage always has a format of QImage::Format_RGBA8888. If the colorFormat() is VK_FORMAT_B8G8R8A8_UNORM, the red and blue channels are swapped automatically since this format is commonly used as the default choice for swapchain color buffers. With any other color buffer format, there is no conversion performed by this function.

VkCommandPool QVulkanWindow::graphicsCommandPool() const

Returns the active graphics command pool.

VkQueue QVulkanWindow::graphicsQueue() const

Returns the active graphics queue.

uint32_t QVulkanWindow::graphicsQueueFamilyIndex() const

Returns the family index of the active graphics queue.

uint32_t QVulkanWindow::hostVisibleMemoryIndex() const

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.

bool QVulkanWindow::isValid() const

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

VkImage QVulkanWindow::msaaColorImage(int idx) const

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].

VkImageView QVulkanWindow::msaaColorImageView(int idx) const

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].

VkPhysicalDevice QVulkanWindow::physicalDevice() const

Returns the active physical device.

const VkPhysicalDeviceProperties *QVulkanWindow::physicalDeviceProperties() const

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

VkSampleCountFlagBits QVulkanWindow::sampleCountFlagBits() const

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 setSampleCount() and supportedSampleCounts().

void QVulkanWindow::setDeviceExtensions(const QByteArrayList &extensions)

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.

[since 6.7] void QVulkanWindow::setEnabledFeaturesModifier(const QVulkanWindow::EnabledFeaturesModifier &modifier)

Sets the enabled device features modification function modifier.

This function was introduced in Qt 6.7.

See also EnabledFeaturesModifier.

[since 6.7] void QVulkanWindow::setEnabledFeaturesModifier(QVulkanWindow::EnabledFeatures2Modifier modifier)

Sets the enabled device features modification function modifier.

This is an overloaded function.

This function was introduced in Qt 6.7.

See also EnabledFeatures2Modifier.

void QVulkanWindow::setFlags(QVulkanWindow::Flags flags)

Configures the behavior based on the provided flags.

See also flags().

void QVulkanWindow::setPhysicalDeviceIndex(int idx)

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.

void QVulkanWindow::setPreferredColorFormats(const QList<VkFormat> &formats)

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 colorFormat().

void QVulkanWindow::setQueueCreateInfoModifier(const QVulkanWindow::QueueCreateInfoModifier &modifier)

Sets the queue create info modification function modifier.

See also QueueCreateInfoModifier.

void QVulkanWindow::setSampleCount(int sampleCount)

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 supportedSampleCounts() and sampleCountFlagBits().

QVulkanInfoVector<QVulkanExtension> QVulkanWindow::supportedDeviceExtensions()

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

QList<int> QVulkanWindow::supportedSampleCounts()

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 setSampleCount().

bool QVulkanWindow::supportsGrab() const

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

VkImage QVulkanWindow::swapChainImage(int idx) const

Returns the specified swap chain image.

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

int QVulkanWindow::swapChainImageCount() const

Returns the number of images in the swap chain.

QSize QVulkanWindow::swapChainImageSize() const

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.

In addition, it has been observed on some platforms that the Vulkan-reported surface size is different with high DPI scaling active, meaning the QWindow-reported size() multiplied with the devicePixelRatio() was 1 pixel less or more when compared to the value returned from here, presumably due to differences in rounding. Rendering code should be aware of this, and any related rendering logic must be based in the value returned from here, never on the QWindow-reported size. Regardless of which pixel size is correct in theory, Vulkan rendering must only ever rely on the Vulkan API-reported surface size. Otherwise validation errors may occur, e.g. when setting the viewport, because the application-provided values may become out-of-bounds from Vulkan's perspective.

VkImageView QVulkanWindow::swapChainImageView(int idx) const

Returns the specified swap chain image view.

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