Revision control
++ // Copyright (C) 2019 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example scenegraph/vulkanunderqml
++ \title Scene Graph - Vulkan Under QML
++ \examplecategory {Graphics}
++ \ingroup qtquickexamples
++ \brief Shows how to render directly with Vulkan under a Qt Quick scene.
++
++ \image vulkanunderqml-example.jpg {Animated squircle rendered with
++ Vulkan under Qt Quick scene with text overlay}
++
++ \note Compiling this example requires an SDK. See \l{Vulkan Integration} for
++ information on what to install.
++
++ \section1 Overview
++
++ This example makes use of the \l QQuickWindow::beforeRendering()
++ and \l QQuickWindow::beforeRenderPassRecording() signals to draw custom Vulkan
++ content under a Qt Quick scene. QML is used to render a text label on top.
++
++ The example is equivalent in most ways to the \l{Scene Graph - OpenGL Under
++ QML}{OpenGL Under QML}, \l{Scene Graph - Direct3D 11 Under QML}{Direct3D 11
++ Under QML}, and \l{Scene Graph - Metal Under QML}{Metal Under QML}
++ examples, they all render the same custom content, just via different
++ native APIs.
++
++ The particulars of utilizing QML will be covered in this documentation
++ without delving into the detail of custom Vulkan rendering.
++
++ \section1 Affecting Vulkan rendering from QML
++
++ The example shows how to use values that are exposed to QML to control
++ Vulkan rendering.
++
++ To expose the threshold value \c t to QML, in the definition of \c VulkanSquircle,
++ we use the \l Q_OBJECT, \l Q_PROPERTY, and \l QML_ELEMENT macros like so:
++
++ \quotefromfile scenegraph/vulkanunderqml/vulkansquircle.h
++ \skipto class VulkanSquircle
++ \printto public:
++
++ We then go on to declare public and private items:
++
++ \printto };
++
++ Then in \c main.qml we animate the threshold value using a \l NumberAnimation.
++
++ \quotefromfile scenegraph/vulkanunderqml/main.qml
++ \skipto VulkanSquircle {
++ \printto running: true
++ The \c t variable is ultimately used by the SPIR-V shader program that draws
++ the squircles.
++
++ \section1 Using signals to render custom Vulkan content
++
++ The \l QQuickWindow::beforeRendering()
++ and \l QQuickWindow::beforeRenderPassRecording() signals are what are used.
++
++ The QQuickWindow::beforeRendering() signal is emitted at the start of
++ every frame, before the scene graph starts its rendering. This means any Vulkan
++ draw calls that are made as a response to this signal, will stack under the
++ Qt Quick items. There are two signals because the custom Vulkan commands
++ are recorded onto the same command buffer used by the scene graph.
++
++ The beforeRendering() function on its own is not sufficient for this, because
++ it gets emitted at the start of the frame, before recording the start of a
++ \c renderpass instance by using
++ \l{https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkCmdBeginRenderPass.html}{vkCmdBeginRenderPass}.
++
++ The solution: by connecting to beforeRenderPassRecording(), the application's
++ own commands and the scene graph's scaffolding will end up in the right order.
++
++ Connecting the signals is done by the \c sync() function:
++
++ \quotefromfile scenegraph/vulkanunderqml/vulkansquircle.cpp
++ \skipto void VulkanSquircle::sync()
++ \printto m_renderer->setWindow(window());
++
++ Another way you can render Vulkan content on top of the Qt Quick scene is by
++ connecting to the \l QQuickWindow::afterRendering() and
++ \l QQuickWindow::afterRenderPassRecording() signals.
++
++ */