rhi: Do some internal doc fixes

Change-Id: Iefcf06ffc251d160e838ae12729314b29d4f36a1
Reviewed-by: Andy Nichols <andy.nichols@qt.io>

5 files changed, 127 insertions, 34 deletions

diff --git a/src/gui/rhi/qrhi.cpp b/src/gui/rhi/qrhi.cpp
index 567e06405d..799b21ee85 100644
--- a/src/gui/rhi/qrhi.cpp
+++ b/src/gui/rhi/qrhi.cpp
@@ -79,6 +79,8 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general")
 
     \li Direct3D 11.1
 
+    \li Direct3D 12
+
     \li Metal
 
     \li Vulkan 1.0, optionally with some extensions that are part of Vulkan 1.1
@@ -1590,10 +1592,10 @@ QDebug operator<<(QDebug dbg, const QRhiVertexInputLayout &v)
 
     \value Vertex Vertex stage
 
-    \value TessellationControlStage Tessellation control (hull shader) stage.
-    Must be used only when the QRhi::Tessellation feature is supported.
+    \value TessellationControl Tessellation control (hull shader) stage. Must
+    be used only when the QRhi::Tessellation feature is supported.
 
-    \value TessellationEvaluationStage Tessellation evaluation (domain shader)
+    \value TessellationEvaluation Tessellation evaluation (domain shader)
     stage. Must be used only when the QRhi::Tessellation feature is supported.
 
     \value Fragment Fragment (pixel shader) stage
@@ -2310,9 +2312,9 @@ QRhi *QRhiResource::rhi() const
     not supported, this usage can only be combined with the type Dynamic.
 
     \value StorageBuffer Storage buffer. This allows the QRhiBuffer to be used
-    in combination with \l{BufferLoad}{QRhiShaderResourceBinding::BufferLoad},
-    \l{BufferStore}{QRhiShaderResourceBinding::BufferStore}, or
-    \l{BufferLoadStore}{QRhiShaderResourceBinding::BufferLoadStore}. This usage
+    in combination with \l{QRhiShaderResourceBinding::BufferLoad}{BufferLoad},
+    \l{QRhiShaderResourceBinding::BufferStore}{BufferStore}, or
+    \l{QRhiShaderResourceBinding::BufferLoadStore}{BufferLoadStore}. This usage
     can only be combined with the types Immutable or Static, and is only
     available when the \l{QRhi::Compute}{Compute feature} is reported as
     supported.
@@ -2679,6 +2681,14 @@ bool QRhiRenderBuffer::createFrom(NativeRenderBuffer src)
      QRhi::TextureArrays feature. When rendering into, or uploading data to a
      texture array, the \c layer specified in the render target's color
      attachment or the upload description selects a single element in the array.
+
+     \value OneDimensional The texture is a 1D texture. Such textures can be
+     created by passing a 0 height and depth to QRhi::newTexture(). Note that
+     there can be limitations on one dimensional textures depending on the
+     underlying graphics API. For example, rendering to them or using them with
+     mipmap-based filtering may be unsupported. This is indicated by the
+     QRhi::OneDimensionalTextures and QRhi::OneDimensionalTextureMipmaps
+     feature flags.
  */
 
 /*!
@@ -2712,7 +2722,7 @@ bool QRhiRenderBuffer::createFrom(NativeRenderBuffer src)
 
     \value R32F One component, 32-bit float.
 
-    \value RGBA10A2 Four components, unsigned normalized 10 bit R, G, and B,
+    \value RGB10A2 Four components, unsigned normalized 10 bit R, G, and B,
     2-bit alpha. This is a packed format so native endianness applies. Note
     that there is no BGR10A2. This is because RGB10A2 maps to
     DXGI_FORMAT_R10G10B10A2_UNORM with D3D, MTLPixelFormatRGB10A2Unorm with
@@ -2855,7 +2865,7 @@ bool QRhiTexture::createFrom(QRhiTexture::NativeTexture src)
 /*!
     With some graphics APIs, such as Vulkan, integrating custom rendering code
     that uses the graphics API directly needs special care when it comes to
-    image layouts. This function allows communicating the expected layout the
+    image layouts. This function allows communicating the expected \a layout the
     image backing the QRhiTexture is in after the native rendering commands.
 
     For example, consider rendering into a QRhiTexture's VkImage directly with
@@ -2871,6 +2881,9 @@ bool QRhiTexture::createFrom(QRhiTexture::NativeTexture src)
 
     This function has no effect with QRhi backends where the underlying
     graphics API does not expose a concept of image layouts.
+
+    \note With Vulkan \a layout is a \c VkImageLayout. With Direct 3D 12 \a
+    layout is a value composed of the bits from \c D3D12_RESOURCE_STATES.
  */
 void QRhiTexture::setNativeLayout(int layout)
 {
@@ -3421,7 +3434,15 @@ void QRhiImplementation::updateLayoutDesc(QRhiShaderResourceBindings *srb)
 
     \value UniformBuffer Uniform buffer
 
-    \value SampledTexture Combined image sampler
+    \value SampledTexture Combined image sampler (a texture and sampler pair).
+    Even when the shading language associated with the underlying 3D API has no
+    support for this concept (e.g. D3D and HLSL), this is still supported
+    because the shader translation layer takes care of the appropriate
+    translation and remapping of binding points or shader registers.
+
+    \value Texture Texture (separate)
+
+    \value Sampler Sampler (separate)
 
     \value ImageLoad Image load (with GLSL this maps to doing imageLoad() on a
     single level - and either one or all layers - of a texture exposed to the
@@ -5572,8 +5593,8 @@ QRhi::~QRhi()
 
     \a params must point to an instance of one of the backend-specific
     subclasses of QRhiInitParams, such as, QRhiVulkanInitParams,
-    QRhiMetalInitParams, QRhiD3D11InitParams, QRhiGles2InitParams. See these
-    classes for examples on creating a QRhi.
+    QRhiMetalInitParams, QRhiD3D11InitParams, QRhiD3D12InitParams,
+    QRhiGles2InitParams. See these classes for examples on creating a QRhi.
 
     QRhi by design does not implement any fallback logic: if the specified API
     cannot be initialized, create() will fail, with warnings printed on the
@@ -5587,6 +5608,13 @@ QRhi::~QRhi()
     initialization of the infrastructure and is wasteful if that QRhi instance
     is then thrown immediately away.
 
+    \a importDevice allows using an already existing graphics device, without
+    QRhi creating its own. When not null, this parameter must point to an
+    instance of one of the subclasses of QRhiNativeHandles:
+    QRhiVulkanNativeHandles, QRhiD3D11NativeHandles, QRhiD3D12NativeHandles,
+    QRhiMetalNativeHandles, QRhiGles2NativeHandles. The exact details and
+    semantics depend on the backand and the underlying graphics API.
+
     \sa probe()
  */
 QRhi *QRhi::create(Implementation impl, QRhiInitParams *params, Flags flags, QRhiNativeHandles *importDevice)
@@ -5801,7 +5829,6 @@ const char *QRhi::backendName() const
     \struct QRhiDriverInfo
     \internal
     \inmodule QtGui
-    \since 6.1
 
     \brief Describes the physical device, adapter, or graphics API
     implementation that is used by an initialized QRhi.
@@ -6388,9 +6415,10 @@ void QRhiResourceUpdateBatchPrivate::trimOpLists()
 }
 
 /*!
-    Sometimes committing resource updates is necessary without starting a
-    render pass. Not often needed, updates should typically be passed to
-    beginPass (or endPass, in case of readbacks) instead.
+    Sometimes committing resource updates is necessary or just more convenient
+    without starting a render pass. Calling this function with \a
+    resourceUpdates is an alternative to passing \a resourceUpdates to a
+    beginPass() call (or endPass(), which would be typical in case of readbacks).
 
     \note Cannot be called inside a pass.
  */
@@ -6447,7 +6475,11 @@ void QRhiCommandBuffer::resourceUpdate(QRhiResourceUpdateBatch *resourceUpdates)
       cb->beginPass(rt, ...); // this is ok, no explicit rt->create() is required before
     \endcode
 
-    \sa endPass()
+    \a flags allow controlling certain advanced functionality. One commonly used
+    flag is \c ExternalContents. This should be specified whenever
+    beginExternal() will be called within the pass started by this function.
+
+    \sa endPass(), BeginPassFlags
  */
 void QRhiCommandBuffer::beginPass(QRhiRenderTarget *rt,
                                   const QColor &colorClearValue,
@@ -6742,8 +6774,9 @@ void QRhiCommandBuffer::drawIndexed(quint32 indexCount,
 }
 
 /*!
-    Records a named debug group on the command buffer. This is shown in
-    graphics debugging tools such as \l{https://renderdoc.org/}{RenderDoc} and
+    Records a named debug group on the command buffer with the specified \a
+    name. This is shown in graphics debugging tools such as
+    \l{https://renderdoc.org/}{RenderDoc} and
     \l{https://developer.apple.com/xcode/}{XCode}. The end of the grouping is
     indicated by debugMarkEnd().
 
@@ -6801,6 +6834,8 @@ void QRhiCommandBuffer::debugMarkMsg(const QByteArray &msg)
 
     \note Compute is only available when the \l{QRhi::Compute}{Compute} feature
     is reported as supported.
+
+    \a flags is not currently used.
  */
 void QRhiCommandBuffer::beginComputePass(QRhiResourceUpdateBatch *resourceUpdates, BeginPassFlags flags)
 {
@@ -7170,7 +7205,7 @@ bool QRhi::isDeviceLost() const
 }
 
 /*!
-    \return a binary \a data blob with data collected from the
+    \return a binary data blob with data collected from the
     QRhiGraphicsPipeline and QRhiComputePipeline successfully created during
     the lifetime of this QRhi.
 
@@ -7774,7 +7809,9 @@ QRhi::FrameOpResult QRhi::beginOffscreenFrame(QRhiCommandBuffer **cb, BeginFrame
 }
 
 /*!
-    Ends and waits for the offscreen frame.
+    Ends, submits, and waits for the offscreen frame.
+
+    \a flags is not currently used.
 
     \sa beginOffscreenFrame()
  */
diff --git a/src/gui/rhi/qrhid3d11.cpp b/src/gui/rhi/qrhid3d11.cpp
index 9b14a2f0f2..ab511d0cdf 100644
--- a/src/gui/rhi/qrhid3d11.cpp
+++ b/src/gui/rhi/qrhid3d11.cpp
@@ -44,9 +44,7 @@ using namespace Qt::StringLiterals;
     \endcode
 
     \note QRhiSwapChain should only be used in combination with QWindow
-    instances that have their surface type set to QSurface::OpenGLSurface.
-    There are currently no Direct3D specifics in the Windows platform support
-    of Qt and therefore there is no separate QSurface type available.
+    instances that have their surface type set to QSurface::Direct3DSurface.
 
     \section2 Working with existing Direct3D 11 devices
 
diff --git a/src/gui/rhi/qrhid3d12.cpp b/src/gui/rhi/qrhid3d12.cpp
index a62e41319d..eca02a8b8e 100644
--- a/src/gui/rhi/qrhid3d12.cpp
+++ b/src/gui/rhi/qrhid3d12.cpp
@@ -20,6 +20,65 @@ QT_BEGIN_NAMESPACE
   Direct 3D 12 backend.
 */
 
+/*!
+    \class QRhiD3D12InitParams
+    \inmodule QtGui
+    \brief Direct3D 12 specific initialization parameters.
+
+    A D3D12-based QRhi needs no special parameters for initialization. If
+    desired, enableDebugLayer can be set to \c true to enable the Direct3D
+    debug layer. This can be useful during development, but should be avoided
+    in production builds.
+
+    \badcode
+        QRhiD3D12InitParams params;
+        params.enableDebugLayer = true;
+        rhi = QRhi::create(QRhi::D3D12, &params);
+    \endcode
+
+    \note QRhiSwapChain should only be used in combination with QWindow
+    instances that have their surface type set to QSurface::Direct3DSurface.
+
+    \section2 Working with existing Direct3D 12 devices
+
+    When interoperating with another graphics engine, it may be necessary to
+    get a QRhi instance that uses the same Direct3D device. This can be
+    achieved by passing a pointer to a QRhiD3D12NativeHandles to
+    QRhi::create(). QRhi does not take ownership of any of the external
+    objects.
+
+    Sometimes, for example when using QRhi in combination with OpenXR, one will
+    want to specify which adapter to use, and optionally, which feature level
+    to request on the device, while leaving the device creation to QRhi. This
+    is achieved by leaving the device pointer set to null, while specifying the
+    adapter LUID and feature level.
+
+    Optionally the ID3D12CommandQueue can be specified as well, by setting \c
+    commandQueue to a non-null value.
+ */
+
+/*!
+    \class QRhiD3D12NativeHandles
+    \inmodule QtGui
+    \brief Holds the D3D12 device used by the QRhi.
+
+    \note The class uses \c{void *} as the type since including the COM-based
+    \c{d3d12.h} headers is not acceptable here. The actual type is
+    \c{ID3D12Device *}.
+ */
+
+/*!
+    \class QRhiD3D12CommandBufferNativeHandles
+    \inmodule QtGui
+    \brief Holds the ID3D12GraphicsCommandList object that is backing a QRhiCommandBuffer.
+
+    \note The command list object is only guaranteed to be valid, and
+    in recording state, while recording a frame. That is, between a
+    \l{QRhi::beginFrame()}{beginFrame()} - \l{QRhi::endFrame()}{endFrame()} or
+    \l{QRhi::beginOffscreenFrame()}{beginOffscreenFrame()} -
+    \l{QRhi::endOffscreenFrame()}{endOffscreenFrame()} pair.
+ */
+
 // https://learn.microsoft.com/en-us/windows/win32/direct3d12/hardware-feature-levels
 static const D3D_FEATURE_LEVEL MIN_FEATURE_LEVEL = D3D_FEATURE_LEVEL_11_0;
 
diff --git a/src/gui/rhi/qrhigles2.cpp b/src/gui/rhi/qrhigles2.cpp
index be03ef0a07..58eed34aa8 100644
--- a/src/gui/rhi/qrhigles2.cpp
+++ b/src/gui/rhi/qrhigles2.cpp
@@ -51,18 +51,18 @@ QT_BEGIN_NAMESPACE
     thread) are satisfied. The implicitly created context is destroyed
     automatically together with the QRhi.
 
-    The QSurfaceFormat for the context is specified in \l format. The
+    The QSurfaceFormat for the context is specified in \c format. The
     constructor sets this to QSurfaceFormat::defaultFormat() so applications
     that call QSurfaceFormat::setDefaultFormat() with the appropriate settings
-    before the constructor runs will not need to change value of \l format.
+    before the constructor runs will not need to change value of \c format.
 
     \note Remember to set the depth and stencil buffer sizes to 24 and 8 when
     the renderer relies on depth or stencil testing, either in the global
     default QSurfaceFormat, or, alternatively, separately in all the involved
-    QSurfaceFormat instances: in \l format, the format argument passed to
+    QSurfaceFormat instances: in \c format, the format argument passed to
     newFallbackSurface(), and on any QWindow that is used with the QRhi.
 
-    A QSurface has to be specified in \l fallbackSurface. In order to prevent
+    A QSurface has to be specified in \c fallbackSurface. In order to prevent
     mistakes in threaded situations, this is never created automatically by the
     QRhi because, like QWindow, instances of QSurface subclasses can often be
     created on the gui/main thread only.
@@ -77,14 +77,14 @@ QT_BEGIN_NAMESPACE
     instances that have their surface type set to QSurface::OpenGLSurface or
     QSurface::RasterGLSurface.
 
-    \note \l window is optional. It is recommended to specify it whenever
+    \note \c window is optional. It is recommended to specify it whenever
     possible, in order to avoid problems on multi-adapter and multi-screen
-    systems. When \l window is not set, the very first
-    QOpenGLContext::makeCurrent() happens with \l fallbackSurface which may be
+    systems. When \c window is not set, the very first
+    QOpenGLContext::makeCurrent() happens with \c fallbackSurface which may be
     an invisible window on some platforms (for example, Windows) and that may
     trigger unexpected problems in some cases.
 
-    In case resource sharing with an existing QOpenGLContext is desired, \l
+    In case resource sharing with an existing QOpenGLContext is desired, \c
     shareContext can be set to an existing QOpenGLContext. Alternatively,
     Qt::AA_ShareOpenGLContexts is honored as well, when enabled.
 
@@ -93,8 +93,7 @@ QT_BEGIN_NAMESPACE
     When interoperating with another graphics engine, it may be necessary to
     get a QRhi instance that uses the same OpenGL context. This can be achieved
     by passing a pointer to a QRhiGles2NativeHandles to QRhi::create(). The
-    \l{QRhiGles2NativeHandles::context}{context} must be set to a non-null
-    value.
+    \c{QRhiGles2NativeHandles::context} must be set to a non-null value then.
 
     An alternative approach is to create a QOpenGLContext that
     \l{QOpenGLContext::setShareContext()}{shares resources} with the other
diff --git a/src/gui/rhi/qrhivulkan.cpp b/src/gui/rhi/qrhivulkan.cpp
index e2f618456a..2c4f1bd18b 100644
--- a/src/gui/rhi/qrhivulkan.cpp
+++ b/src/gui/rhi/qrhivulkan.cpp
@@ -183,7 +183,7 @@ QT_BEGIN_NAMESPACE
     in recording state, while recording a frame. That is, between a
     \l{QRhi::beginFrame()}{beginFrame()} - \l{QRhi::endFrame()}{endFrame()} or
     \l{QRhi::beginOffscreenFrame()}{beginOffscreenFrame()} -
-    \l{QRhi::endOffsrceenFrame()}{endOffscreenFrame()} pair.
+    \l{QRhi::endOffscreenFrame()}{endOffscreenFrame()} pair.
  */
 
 /*!