Revision control
++ // Copyright (C) 2023 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example rhiwindow
++ \title RHI Window Example
++ \examplecategory {Graphics}
++
++ \brief This example shows how to create a minimal QWindow-based
++ application using QRhi.
++
++ \image rhiwindow_example.jpg {Screenshot of example}
++
++ Qt 6.6 starts offering its accelerated 3D API and shader abstraction layer
++ for application use as well. Applications can now use the same 3D graphics
++ classes Qt itself uses to implement the Qt Quick scenegraph or the Qt Quick
++ 3D engine. In earlier Qt versions QRhi and the related classes were all
++ private APIs. From 6.6 on these classes are in a similar category as QPA
++ family of classes: neither fully public nor private, but something
++ in-between, with a more limited compatibility promise compared to public
++ APIs. On the other hand, QRhi and the related classes now come with full
++ documentation similarly to public APIs.
++
++ There are multiple ways to use QRhi, the example here shows the most
++ low-level approach: targeting a QWindow, while not using Qt Quick, Qt Quick
++ 3D, or Widgets in any form, and setting up all the rendering and windowing
++ infrastructure in the application.
++
++ In contrast, when writing a QML application with Qt Quick or Qt Quick 3D,
++ and wanting to add QRhi-based rendering to it, such an application is going
++ to rely on the window and rendering infrastructure Qt Quick has already
++ initialized, and it is likely going to query an existing QRhi instance from
++ the QQuickWindow. There dealing with QRhi::create(), platform/API specifics
++ such as \l{QVulkanInstance}{Vulkan instances}, or correctly handling
++ \l{QExposeEvent}{expose} and resize events for the window are all managed
++ by Qt Quick. Whereas in this example, all that is managed and taken care
++ of by the application itself.
++
++ \note For QWidget-based applications in particular, it should be noted that
++ QWidget::createWindowContainer() allows embedding a QWindow (backed by a
++ native window) into the widget-based user interface. Therefore, the \c
++ HelloWindow class from this example is reusable in QWidget-based
++ applications, assuming the necessary initialization from \c main() is in
++ place as well.
++
++ \section1 3D API Support
++
++ The application supports all the current \l{QRhi::Implementation}{QRhi
++ backends}. When no command-line arguments are specified, platform-specific
++ defaults are used: Direct 3D 11 on Windows, OpenGL on Linux, Metal on
++ macOS/iOS.
++
++ Running with \c{--help} shows the available command-line options:
++
++ \list
++ \li -d or --d3d11 for Direct 3D 11
++ \li -D or --d3d12 for Direct 3D 12
++ \li -m or --metal for Metal
++ \li -v or --vulkan for Vulkan
++ \li -g or --opengl for OpenGL or OpenGL ES
++ \li -n or --null for the \l{QRhi::Null}{Null backend}
++ \endlist
++
++ \section1 Build System Notes
++
++ This application relies solely on the Qt GUI module. It does not use Qt
++ Widgets or Qt Quick.
++
++ In order to access the RHI APIs, which are available to all Qt applications
++ but come with a limited compatibility promise, the \c target_link_libraries
++ CMake command lists \c{Qt6::GuiPrivate}. This is what enables the
++ \c{#include <rhi/qrhi.h>} include statement to compile successfully.
++
++ \section1 Features
++
++ The application features:
++
++ \list
++
++ \li A resizable QWindow,
++
++ \li a swapchain and depth-stencil buffer that properly follows the size of
++ the window,
++
++ \li logic to initialize, render, and tear down at the appropriate time
++ based on events such as \l QExposeEvent and \l QPlatformSurfaceEvent,
++
++ \li rendering a fullscreen textured quad, using a texture the contents of
++ which is generated in a QImage via QPainter (using the raster paint engine,
++ i.e. the generating of the image's pixel data is all CPU-based, that data
++ is then uploaded into a GPU texture),
++
++ \li rendering a triangle with blending and depth testing enabled, using a
++ perspective projection, while applying a model transform that changes on
++ every frame,
++
++ \li an efficient, cross-platform render loop using
++ \l{QWindow::requestUpdate()}{requestUpdate()}.
++
++ \endlist
++
++ \section1 Shaders
++
++ The application uses two sets of vertex and fragment shader pairs:
++
++ \list
++
++ \li one for the fullscreen quad, which uses no vertex inputs and the
++ fragment shader samples a texture (\c quad.vert, \c quad.frag),
++
++ \li and another pair for the triangle, where vertex positions and colors
++ are provided in a vertex buffer and a modelview-projection matrix is
++ provided in a uniform buffer (\c color.vert, \c color.frag).
++
++ \endlist
++
++ The shaders are written as Vulkan-compatible GLSL source code.
++
++ Due to being a Qt GUI module example, this example cannot have a dependency
++ on the \l{Qt Shader Tools} module. This means that CMake helper functions
++ such as \l qt_add_shaders() are not available for use. Therefore, the
++ example has the pre-processed \c{.qsb} files included in the
++ \c{shaders/prebuilt} folder, and they are simply included within the
++ executable via \c{qt_add_resources}. This approach is not generally
++ recommended for applications, consider rather using \l{qt_add_shaders}(),
++ which avoids the need to manually generate and manage the \c{.qsb} files.
++
++ To generate the \c{.qsb} files for this example, the command \c{qsb --qt6
++ color.vert -o prebuilt/color.vert.qsb} etc. was used. This leads to
++ compiling to \l{https://www.khronos.org/spir/}{SPIR-V} and than transpiling
++ into GLSL (\c{100 es} and \c 120), HLSL (5.0), and MSL (1.2). All the
++ shader versions are then packed together into a QShader and serialized to
++ disk.
++
++ \section1 API-specific Initialization
++
++ For some of the 3D APIs the main() function has to perform the appropriate
++ API-specific initialiation, e.g. to create a QVulkanInstance when using
++ Vulkan. For OpenGL we have to ensure a depth buffer is available, this is
++ done via QSurfaceFormat. These steps are not in the scope of QRhi since
++ QRhi backends for OpenGL or Vulkan build on the existing Qt facilities such
++ as QOpenGLContext or QVulkanInstance.
++
++ \snippet rhiwindow/main.cpp api-setup
++
++ \note For Vulkan, note how
++ QRhiVulkanInitParams::preferredInstanceExtensions() is taken into account
++ to ensure the appropriate extensions are enabled.
++
++ \c HelloWindow is a subclass of \c RhiWindow, which in turn is a QWindow.
++ \c RhiWindow contains everything needed to manage a resizable window with
++ a\ swapchain (and depth-stencil buffer), and is potentially reusable in
++ other applications as well. \c HelloWindow contains the rendering logic
++ specific to this particular example application.
++
++ In the QWindow subclass constructor the surface type is set based on the
++ selected 3D API.
++
++ \snippet rhiwindow/rhiwindow.cpp rhiwindow-ctor
++
++ Creating and initializing a QRhi object is implemented in
++ RhiWindow::init(). Note that this is invoked only when the window is
++ \c renderable, which is indicated by an \l{QExposeEvent}{expose event}.
++
++ Depending on which 3D API we use, the appropriate InitParams struct needs
++ to be passed to QRhi::create(). With OpenGL for example, a
++ QOffscreenSurface (or some other QSurface) must be created by the
++ application and provided for use to the QRhi. With Vulkan, a successfully
++ initialized QVulkanInstance is required. Others, such as Direct 3D or Metal
++ need no additional information to be able to initialize.
++
++ \snippet rhiwindow/rhiwindow.cpp rhi-init
++
++ Apart from this, everything else, all the rendering code, is fully
++ cross-platform and has no branching or conditions specific to any of the 3D
++ API.
++
++ \section1 Expose Events
++
++ What \c renderable exactly means is platform-specific. For example, on
++ macOS a window that is fully obscured (fully behind some other window) is
++ not renderable, whereas on Windows obscuring has no significance.
++ Fortunately, the application needs no special knowledge about this: Qt's
++ platform plugins abstract the differences behind the expose event. However,
++ the \l{QWindow::exposeEvent()}{exposeEvent()} reimplementation also needs
++ to be aware that an empty output size (e.g. width and height of 0) is also
++ something that should be treated as a non-renderable situation. On Windows
++ for example, this is what is going to happen when minimizing the window.
++ Hence the check based on QRhiSwapChain::surfacePixelSize().
++
++ This implementation of expose event handling attempts to be robust, safe,
++ and portable. Qt Quick itself also implements a very similar logic in its
++ render loops.
++
++ \snippet rhiwindow/rhiwindow.cpp expose
++
++ In RhiWindow::render(), which is invoked in response to the
++ \l{QEvent::UpdateRequest}{UpdateRequest} event generated by
++ \l{QWindow::requestUpdate()}{requestUpdate()}, the following check is in
++ place, to prevent attempting to render when the swapchain initialization
++ failed, or when the window became non-renderable.
++
++ \snippet rhiwindow/rhiwindow.cpp render-precheck
++
++ \section1 Swapchain, Depth-Stencil buffer, and Resizing
++
++ To render to the QWindow, a QRhiSwapChain is needed. In addition, a
++ QRhiRenderBuffer acting as the depth-stencil buffer is created as well
++ since the application demonstrates how depth testing can be enabled in a
++ graphics pipeline. With some legacy 3D APIs managing the depth/stencil
++ buffer for a window is part of the corresponding windowing system interface
++ API (EGL, WGL, GLX, etc., meaning the depth/stencil buffer is implicitly
++ managed together with the \c{window surface}), whereas with modern APIs
++ managing the depth-stencil buffer for a window-based render target is no
++ different from offscreen render targets. QRhi abstracts this, but for best
++ performance it still needs to be indicated that the QRhiRenderBuffer is
++ \l{QRhiRenderBuffer::UsedWithSwapChainOnly}{used with together with a
++ QRhiSwapChain}.
++
++ The QRhiSwapChain is associated with the QWindow and the depth/stencil
++ buffer.
++
++ \snippet rhiwindow/rhiwindow.h swapchain-data
++ \codeline
++ \snippet rhiwindow/rhiwindow.cpp swapchain-init
++
++ When the window size changes, the swapchain needs to be resized as well.
++ This is implemented in resizeSwapChain().
++
++ \snippet rhiwindow/rhiwindow.cpp swapchain-resize
++
++ Unlike other QRhiResource subclasses, QRhiSwapChain features slightly
++ different semantics when it comes to its create-function. As the name,
++ \l{QRhiSwapChain::createOrResize()}{createOrResize()}, suggests, this needs
++ to be called whenever it is known that the output window size may be out of
++ sync with what the swapchain was last initialized. The associated
++ QRhiRenderBuffer for depth-stencil gets its
++ \l{QRhiRenderBuffer::pixelSize()}{size} set automatically, and
++ \l{QRhiRenderBuffer::create()}{create()} is called on it implicitly from the
++ swapchain's createOrResize().
++
++ This is also a convenient place to (re)calculate the projection and view
++ matrices since the perspective projection we set up depends on the output
++ aspect ratio.
++
++ \note To eliminate coordinate system differences, the
++ \l{QRhi::clipSpaceCorrMatrix()}{a backend/API-specific "correction" matrix}
++ is queried from QRhi and baked in to the projection matrix. This is what
++ allows the application to work with OpenGL-style vertex data, assuming a
++ coordinate system with the origin at the bottom-left.
++
++ The resizeSwapChain() function is called from RhiWindow::render() when it
++ is discovered that the currently reported size is not the same anymore as
++ what the swapchain was last initialized with.
++
++ See QRhiSwapChain::currentPixelSize() and QRhiSwapChain::surfacePixelSize()
++ for further details.
++
++ High DPI support is built-in: the sizes, as the naming indicates, are
++ always in pixels, taking the window-specific
++ \l{QWindow::devicePixelRatio()}{scale factor} into account. On the QRhi
++ (and 3D API) level there is no concept of high DPI scaling, everything is
++ always in pixels. This means that a QWindow with a size() of 1280x720 and
++ a devicePixelRatio() of 2 is a render target (swapchain) with a (pixel) size
++ of 2560x1440.
++
++ \snippet rhiwindow/rhiwindow.cpp render-resize
++
++ \section1 Render Loop
++
++ The application renders continuously, throttled by the presentation rate
++ (vsync). This is ensured by calling
++ \l{QWindow::requestUpdate()}{requestUpdate()} from RhiWindow::render() when
++ the currently recorded frame has been submitted.
++
++ \snippet rhiwindow/rhiwindow.cpp request-update
++
++ This eventually leads to getting a \l{QEvent::UpdateRequest}{UpdateRequest}
++ event. This is handled in the reimplementation of event().
++
++ \snippet rhiwindow/rhiwindow.cpp event
++
++ \section1 Resource and Pipeline Setup
++
++ The application records a single render pass that issues two draw calls,
++ with two different graphics pipelines. One is the "background", with the
++ texture containing the QPainter-generated image, then a single triangle is
++ rendered on top with blending enabled.
++
++ The vertex and uniform buffer used with the triangle is created like this.
++ The size of the uniform buffer is 68 bytes since the shader specific a \c
++ mat4 and a \c float member in the uniform block. Watch out for the
++ layout rules}. This presents no surprises in this example since the \c
++ float member that follows the \c mat4 has the correct alignment without any
++ additional padding, but it may become relevant in other applications,
++ especially when working with types such as \c vec2 or \c vec3. When in
++ doubt, consider checking the QShaderDescription for the
++ \l{QShader::description()}{QShader}, or, what is often more convenient, run
++ the \c qsb tool on the \c{.qsb} file with the \c{-d} argument to inspect
++ the metadata in human-readable form. The printed information includes,
++ among other things, the uniform block member offsets, sizes, and the total
++ size in bytes of each uniform block.
++
++ \snippet rhiwindow/rhiwindow.cpp render-init-1
++
++ The vertex and fragment shaders both need a uniform buffer at binding point
++ 0. This is ensured by the QRhiShaderResourceBindings object. The graphics
++ pipeline is then setup with the shaders and a number of additional
++ information. The example also relies on a number of convenient defaults,
++ e.g. the primitive topology is
++ \l{QRhiGraphicsPipeline::Triangles}{Triangles}, but that is the default,
++ and therefore it is not explicitly set. See QRhiGraphicsPipeline for
++ further details.
++
++ In addition to specifying the topology and various state, the pipeline must
++ also be associated with:
++
++ \list
++
++ \li The vertex input layout in form of a QRhiVertexInputLayout. This
++ specifies the type and component count for each vertex input location, the
++ total stride in bytes per vertex, and other related data.
++ QRhiVertexInputLayout only holds data, not actual native resources, and is
++ copiable.
++
++ \li A valid and successfully initialized QRhiShaderResourceBindings object.
++ This describes the layout of the resource bindings (uniform buffers,
++ textures, samplers) the shaders expect. This must either by the
++ QRhiShaderResourceBindings used when recording the draw calls, or another
++ that is
++ \l{QRhiShaderResourceBindings::isLayoutCompatible()}{layout-compatible with it}.
++ This simple application takes the former approach.
++
++ \li A valid QRhiRenderPassDescriptor object. This must be retrieved from,
++ or \l{QRhiRenderPassDescriptor::isCompatible()}{be compatible with} the
++ render target. The example uses the former, by creating a
++ QRhiRenderPassDescriptor object via
++ QRhiSwapChain::newCompatibleRenderPassDescriptor().
++
++ \endlist
++
++ \snippet rhiwindow/rhiwindow.cpp render-init-2
++
++ getShader() is a helper function that loads a \c{.qsb} file and
++ deserializes a QShader from it.
++
++ \snippet rhiwindow/rhiwindow.cpp getshader
++
++ The \c{color.vert} shader specifies the following as the vertex inputs:
++
++ \badcode
++ layout(location = 0) in vec4 position;
++ layout(location = 1) in vec3 color;
++ \endcode
++
++ The C++ code however provides vertex data as 2 floats for position, with 3
++ floats for the color interleaved. (\c x, \c y, \c r, \c g, \c b for each
++ vertex) This is why the stride is \c{5 * sizeof(float)} and the inputs for
++ locations 0 and 1 are specified as \c Float2 and \c Float3, respectively.
++ This is valid, and the \c z and \c w of the \c vec4 position will get set
++ automatically.
++
++ \section1 Rendering
++
++ Recording a frame is started by calling \l{QRhi::beginFrame()} and finished
++ by calling \l{QRhi::endFrame()}.
++
++ \snippet rhiwindow/rhiwindow.cpp beginframe
++
++ Some of the resources (buffers, textures) have static data in the
++ application, meaning the content never changes. The vertex buffer's content
++ is provided in the initialization step for example, and is not changed
++ afterwards. These data update operations are recorded in \c
++ m_initialUpdates. When not yet done, the commands on this resource update
++ batch are merged into the per-frame batch.
++
++ \snippet rhiwindow/rhiwindow.cpp render-1
++
++ Having a per-frame resource update batch is necessary since the uniform
++ buffer contents with the modelview-projection matrix and the opacity
++ changes on every frame.
++
++ \snippet rhiwindow/rhiwindow.cpp render-rotation
++
++ \snippet rhiwindow/rhiwindow.cpp render-opacity
++
++ To begin recording the render pass, a QRhiCommandBuffer is queried, and the
++ output size is determined, which will be useful for setting up the viewport
++ and resizing our fullscreen texture, if needed.
++
++ \snippet rhiwindow/rhiwindow.cpp render-cb
++
++ Starting a render pass implies clearing the render target's color and
++ depth-stencil buffers (unless the render target flags indicate otherwise,
++ but that is only an option for texture-based render targets). Here we
++ specify black for color, 1.0f for depth, and 0 for stencil (unused). The
++ last argument, \c resourceUpdates, is what ensures that the data update
++ commands recorded on the batch get committed. Alternatively, we could have
++ used QRhiCommandBuffer::resourceUpdate() instead. The render pass targets a
++ swapchain, hence calling
++ \l{QRhiSwapChain::currentFrameRenderTarget()}{currentFrameRenderTarget()}
++ to get a valid QRhiRenderTarget.
++
++ \snippet rhiwindow/rhiwindow.cpp render-pass
++
++ Recording the draw call for the triangle is straightforward: set the
++ pipeline, set the shader resources, set the vertex/index buffer(s), and
++ record the draw call. Here we use a non-indexed draw with just 3 vertices.
++
++ \snippet rhiwindow/rhiwindow.cpp render-pass-record
++
++ The \l{QRhiCommandBuffer::setShaderResources()}{setShaderResources()} call
++ has no arguments given, which implies using \c m_colorTriSrb since that was
++ associated with the active QRhiGraphicsPipeline (\c m_colorPipeline).
++
++ We will not dive into the details of the rendering of the fullscreen
++ background image. See the example source code for that. It is however worth
++ noting a common pattern for "resizing" a texture or buffer resource. There
++ is no such thing as changing the size of an existing native resource, so
++ changing a texture or buffer size must be followed by a call to create(),
++ to release and recreate the underlying native resources. To ensure that the
++ QRhiTexture always has the required size, the application implements the
++ following logic. Note that \c m_texture stays valid for the entire lifetime
++ of the window, which means object references to it, e.g. in a
++ QRhiShaderResourceBindings, continue to be valid all the time. It is only
++ the underlying native resources that come and go over time.
++
++ Note also that we set a device pixel ratio on the image that matches
++ the window that we're drawing into. This ensures that the drawing code
++ can be DPR-agnostic, producing the same layout regardless of the DPR,
++ while also taking advantage of the additional pixels for improved fidelity.
++
++ \snippet rhiwindow/rhiwindow.cpp ensure-texture
++
++ Once a QImage is generated and the QPainter-based drawing into it has
++ finished, we use
++ \l{QRhiResourceUpdateBatch::uploadTexture()}{uploadTexture()} to record a
++ texture upload on the resource update batch:
++
++ \snippet rhiwindow/rhiwindow.cpp ensure-texture-2
++
++ \sa QRhi, QRhiSwapChain, QWindow, QRhiCommandBuffer, QRhiResourceUpdateBatch, QRhiBuffer, QRhiTexture
++ */