rhi: Make it a QPA-style private but semi-public API

qrhi.h, qshader.h, qshaderdescription.h (and qshaderbaker.h from
shadertools; done separately) become "RHI APIs", following the concept
of QPA APIs.

Mirror completely what is done for QPA headers, but using the "rhi"
prefix for the headers. This involves updating syncqt to handle the
new category of headers. (a note on the regex: matching everything
starting with "qrhi" is not acceptable due to incorrectly matching
existing and future headers, hence specifying the four header names
explicitly)

There is going to be one difference to QPA: the documentation for
everything RHI is going to be public and part of the regular docs, not
hidden with \internal.

In addition to the header renaming and adding the comments and
documentation notes and warnings, there is one significant change
here: there is no longer a need to do API-specific includes, such as
qrhid3d11[_p].h, qrhivulkan[_p].h, etc. These are simply merged into a
single header that is then included from qrhi.h. This means that users
within Qt, and any future applications can just do #include
<rhi/qrhi.h> (or rhi/qshader.h if the QRhi stuff is not relevant), no
other headers are needed.

There are no changes to functionality in this patch. Only the
documentation is expanded, quite a lot, to eliminate all qdoc warnings
and make the generated API docs complete. An example, with a quite
extensive doc page is added as well.

Task-number: QTBUG-113331
Change-Id: I91c749826348f14320cb335b1c83e9d1ea2b1d8b
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>

1 files changed, 101 insertions, 6 deletions

diff --git a/src/gui/rhi/qrhivulkan.cpp b/src/gui/rhi/qrhivulkan.cpp
index 2f8afb389a..6fe79f223e 100644
--- a/src/gui/rhi/qrhivulkan.cpp
+++ b/src/gui/rhi/qrhivulkan.cpp
@@ -1,7 +1,7 @@
-// Copyright (C) 2019 The Qt Company Ltd.
+// Copyright (C) 2023 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
 
-#include "qrhivulkan_p_p.h"
+#include "qrhivulkan_p.h"
 #include "qrhivulkanext_p.h"
 #include <qpa/qplatformvulkaninstance.h>
 
@@ -60,10 +60,13 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QRhiVulkanInitParams
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Vulkan specific initialization parameters.
 
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
+
     A Vulkan-based QRhi needs at minimum a valid QVulkanInstance. It is up to
     the user to ensure this is available and initialized. This is typically
     done in main() similarly to the following:
@@ -166,18 +169,80 @@ QT_BEGIN_NAMESPACE
  */
 
 /*!
+    \variable QRhiVulkanInitParams::inst
+
+    The QVulkanInstance that has already been successfully
+    \l{QVulkanInstance::create()}{created}, required.
+*/
+
+/*!
+    \variable QRhiVulkanInitParams::window
+
+    Optional, but recommended when targeting a QWindow.
+*/
+
+/*!
+    \variable QRhiVulkanInitParams::deviceExtensions
+
+    Optional, empty by default. The list of Vulkan device extensions to enable.
+    Unsupported extensions are ignored gracefully.
+*/
+
+/*!
     \class QRhiVulkanNativeHandles
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Collects device, queue, and other Vulkan objects that are used by the QRhi.
 
     \note Ownership of the Vulkan objects is never transferred.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
 /*!
+    \variable QRhiVulkanNativeHandles::physDev
+
+    When different from \nullptr, specifies the Vulkan physical device to use.
+*/
+
+/*!
+    \variable QRhiVulkanNativeHandles::dev
+
+    When wanting to import not just a physical device, but also use an already
+    existing VkDevice, set this and the graphics queue index and family index.
+*/
+
+/*!
+    \variable QRhiVulkanNativeHandles::gfxQueueFamilyIdx
+
+    Graphics queue family index.
+*/
+
+/*!
+    \variable QRhiVulkanNativeHandles::gfxQueueIdx
+
+    Graphics queue index.
+*/
+
+/*!
+    \variable QRhiVulkanNativeHandles::gfxQueue
+
+    Output only, not used by QRhi::create(), only set by the
+    QRhi::nativeHandles() accessor. The graphics VkQueue used by the QRhi.
+*/
+
+/*!
+    \variable QRhiVulkanNativeHandles::vmemAllocator
+
+    Relevant only when importing an existing memory allocator object,
+    leave it set to \nullptr otherwise.
+*/
+
+/*!
     \class QRhiVulkanCommandBufferNativeHandles
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Holds the Vulkan command buffer object that is backing a QRhiCommandBuffer.
 
     \note The Vulkan command buffer object is only guaranteed to be valid, and
@@ -185,15 +250,33 @@ QT_BEGIN_NAMESPACE
     \l{QRhi::beginFrame()}{beginFrame()} - \l{QRhi::endFrame()}{endFrame()} or
     \l{QRhi::beginOffscreenFrame()}{beginOffscreenFrame()} -
     \l{QRhi::endOffscreenFrame()}{endOffscreenFrame()} pair.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
 /*!
+    \variable QRhiVulkanCommandBufferNativeHandles::commandBuffer
+
+    The VkCommandBuffer object.
+*/
+
+/*!
     \class QRhiVulkanRenderPassNativeHandles
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Holds the Vulkan render pass object backing a QRhiRenderPassDescriptor.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
+/*!
+    \variable QRhiVulkanRenderPassNativeHandles::renderPass
+
+    The VkRenderPass object.
+*/
+
 template <class Int>
 inline Int aligned(Int v, Int byteAlign)
 {
@@ -222,6 +305,13 @@ static inline VmaAllocator toVmaAllocator(QVkAllocator a)
     return reinterpret_cast<VmaAllocator>(a);
 }
 
+/*!
+    \return the list of instance extensions that are expected to be enabled on
+    the QVulkanInstance that is used for the Vulkan-based QRhi.
+
+    The returned list can be safely passed to QVulkanInstance::setExtensions()
+    as-is, because unsupported extensions are filtered out automatically.
+ */
 QByteArrayList QRhiVulkanInitParams::preferredInstanceExtensions()
 {
     return {
@@ -229,6 +319,11 @@ QByteArrayList QRhiVulkanInitParams::preferredInstanceExtensions()
     };
 }
 
+/*!
+    \return the list of device extensions that are expected to be enabled on the
+    \c VkDevice when creating a Vulkan-based QRhi with an externally created
+    \c VkDevice object.
+ */
 QByteArrayList QRhiVulkanInitParams::preferredExtensionsForImportedDevice()
 {
     return {