Revision control
++ // Copyright (C) 2023 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example rhi/cuberhiwidget
++ \title Cube RHI Widget Example
++ \examplecategory {Graphics}
++ \ingroup examples-widgets
++ \brief Shows how to render a textured cube and integrate with QPainter and widgets, using QRhi Qt's 3D API and shading language abstraction layer.
++
++ \image cuberhiwidget-example.jpg
++ {Application showing complex rendering overlays}
++ \caption Screenshot of the Cube RHI Widget example
++
++ This example builds on the \l{Simple RHI Widget Example}. While the simple
++ example is intentionally minimal and as compact as possible, rendering only
++ a single triangle with no additional widgets in the window, this
++ application demonstrates:
++
++ \list
++
++ \li Having various widgets in the window, some of them controlling data
++ that is consumed by the QRhiWidget subclass.
++
++ \li Instead of continuously requesting updates, the QRhiWidget here only
++ updates the content in its backing texture when some related data changes.
++
++ \li The cube is textured using a \l QRhiTexture that sources its content
++ from a \l QImage that contains software-based rendering performed with
++ \l QPainter.
++
++ \li The contents of the QRhiWidget \l{QRhiWidget::grab()}{can be
++ read back} and saved to an image file (e.g. a PNG file).
++
++ \li 4x multisample antialiasing \l{QRhiWidget::sampleCount()}{can be toggled}
++ at run time. The QRhiWidget subclass is prepared to handle the changing
++ sample count correctly.
++
++ \li Forcing an \l{QRhiWidget::fixedColorBufferSize}{explicitly specified backing
++ texture size} can be toggled dynamically and controlled with a slider
++ between 16x16 up to 512x512 pixels.
++
++ \li The QRhiWidget subclass deals with a changing \l QRhi correctly. This
++ can be seen in action when making the widget top-level (no parent; becomes
++ a separate window) and then reparenting it again into the main window's
++ child hierarchy.
++
++ \li Most importantly, some widgets, with semi-transparency even, can be
++ placed on top of the QRhiWidget, proving that correct stacking and blending
++ is feasible. This is a case where QRhiWidget is superior to embedding a
++ native window, i.e. a QRhi-based QWindow using
++ QWidget::createWindowContainer(), because it allows stacking and clipping
++ the same way as any ordinary, software-rendered QWidget, whereas native
++ window embedding may, depending on the platform, have various limitations,
++ e.g. often it can be difficult or inefficient to place additional controls
++ on top.
++
++ \endlist
++
++ In the reimplementation of \l{QRhiWidget::initialize()}{initialize()}, the
++ first thing to do is to check if the QRhi we last worked with is still
++ up-to-date, and if the sample count (for multisample antialiasing) has
++ changed. The former is important because all graphics resources must be
++ released when the QRhi changes, whereas with a dynamically changing sample
++ count a similar problem arises specifically for QRhiGraphicsPipeline
++ objects as those bake the sample count in. For simplicity, the application
++ handles all such changes the same way, by resetting its \c scene struct to
++ a default constructed one, which conveniently drops all graphics resources.
++ All resources are then recreated.
++
++ When the backing texture size (so the render target size) changes, no
++ special action is needed, but a signal is emitted for convenience, just so
++ that main() can reposition the overlay label. The 3D API name is also
++ exposed via a signal by querying \l QRhi::backendName() whenever the QRhi
++ changes.
++
++ The implementation has to be aware that multisample antialiasing implies
++ that \l{QRhiWidget::colorTexture()}{colorTexture()} is \nullptr, while
++ \l{QRhiWidget::msaaColorBuffer()}{msaaColorBuffer()} is valid. This is
++ the opposite of when MSAA is not in use. The reason for differentiating
++ and using different types (QRhiTexture, QRhiRenderBuffer) is to allow
++ using MSAA with 3D graphics APIs that do not have support for
++ multisample textures, but have support for multisample renderbuffers.
++ An example of this is OpenGL ES 3.0.
++
++ When checking the up-to-date pixel size and sample count, a convenient and
++ compact solution is to query via the QRhiRenderTarget, because this way one
++ does not need to check which of colorTexture() and msaaColorBuffer() are
++ valid.
++
++ \snippet rhi/cuberhiwidget/examplewidget.cpp init-1
++
++ The rest is quite self-explanatory. The buffers and pipelines are
++ (re)created, if necessary. The contents of the texture that is used to
++ texture the cube mesh is updated. The scene is rendered using a perspective
++ projection. The view is just a simple translation for now.
++
++ \snippet rhi/cuberhiwidget/examplewidget.cpp init-2
++
++ The function that performs the actual enqueuing of the uniform buffer write
++ is also taking the user-provided rotation into account, thus generating the
++ final modelview-projection matrix.
++
++ \snippet rhi/cuberhiwidget/examplewidget.cpp rotation-update
++
++ Updating the \l QRhiTexture that is sampled in the fragment shader when
++ rendering the cube, is quite simple, even though a lot is happening in
++ there: first a QPainter-based drawing is generated within a QImage. This
++ uses the user-provided text. Then the CPU-side pixel data is uploaded to a
++ texture (more precisely, the upload operation is recorded on a \l
++ QRhiResourceUpdateBatch, which is then submitted later in render()).
++
++ \snippet rhi/cuberhiwidget/examplewidget.cpp texture-update
++
++ The graphics resource initialization is simple. There is only a vertex
++ buffer, no index buffer, and a uniform buffer with only a 4x4 matrix in it
++ (16 floats).
++
++ The texture that contains the QPainter-generated drawing has a size of
++ 512x512. Note that all sizes (texture sizes, viewports, scissors, texture
++ upload regions, etc.) are always in pixels when working with QRhi. To
++ sample this texture in the shader, a \l{QRhiSampler}{sampler object} is
++ needed (irrespective of the fact that QRhi-based applications will
++ typically use combined image samplers in the GLSL shader code, which then
++ may be transpiled to separate texture and sampler objects with some shading
++ languages, or may stay a combined texture-sampler object with others,
++ meaning there may not actually be a native sampler object under the hood at
++ run time, depending on the 3D API, but this is all transparent to the
++ application)
++
++ The vertex shader reads from the uniform buffer at binding point 0,
++ therefore
++ \c{scene.ubuf} is exposed at that binding location. The fragment shader
++ samples a texture provided at binding point 1,
++ therefore a combined texture-sampler pair is specified for that binding location.
++
++ The QRhiGraphicsPipeline enables depth test/write, and culls backfaces. It
++ also relies on a number of defaults, e.g. the depth comparison function
++ defaults to \c Less, which is fine for us, and the front face mode is
++ counter-clockwise, which is also good as-is so does not need to be set
++ again.
++
++ \snippet rhi/cuberhiwidget/examplewidget.cpp setup-scene
++
++ In the reimplementation of \l{QRhiWidget::render()}{render()}, first the
++ user-provided data is checked. If the \l QSlider controlling the rotation
++ has provided a new value, or the \l QTextEdit with the cube text has
++ changed its text, the graphics resources the contents of which depend on
++ such data get updated.
++
++ Then, a single render pass with a single draw call is recorded. The cube
++ mesh data is provided in a non-interleaved format, hence the need for two
++ vertex input bindings, one is the positions (x, y, z) the other is the UVs
++ (u, v), with a start offset that corresponds to 36 x-y-z float pairs.
++
++ \snippet rhi/cuberhiwidget/examplewidget.cpp render
++
++ How is the user-provided data sent? Take the rotation for example. main()
++ connects to the QSlider's \l{QSlider::valueChanged}{valueChanged} signal.
++ When emitted, the connected lamda calls setCubeRotation() on the
++ ExampleRhiWidget. Here, if the value is different from before, it is
++ stored, and a dirty flag is set. Then, most importantly,
++ \l{QWidget::update()}{update()} is called on the ExampleRhiWidget. This is
++ what triggers rendering a new frame into the QRhiWidget's backing texture.
++ Without this the content of the ExampleRhiWidget would not update when
++ dragging the slider.
++
++ \snippet rhi/cuberhiwidget/examplewidget.h data-setters
++
++ \sa QRhi, {Simple RHI Widget Example}, {RHI Window Example}
++ */