rhi: d3d: metal: Improve docs for importing existing resources

The struct members were not described. Add something for each in the
docs.

Pick-to: 6.7
Change-Id: I75d0a5a6efee4d7b4a415b5282a9e44950ed3894
Reviewed-by: Laszlo Agocs <laszlo.agocs@qt.io>

3 files changed, 56 insertions, 0 deletions

diff --git a/src/gui/rhi/qrhid3d11.cpp b/src/gui/rhi/qrhid3d11.cpp
index ba2b783b0e..b09baf57b2 100644
--- a/src/gui/rhi/qrhid3d11.cpp
+++ b/src/gui/rhi/qrhid3d11.cpp
@@ -93,22 +93,47 @@ using namespace Qt::StringLiterals;
 
 /*!
     \variable QRhiD3D11NativeHandles::dev
+
+    Points to a
+    \l{https://learn.microsoft.com/en-us/windows/win32/api/d3d11/nn-d3d11-id3d11device}{ID3D11Device}
+    or left set to \nullptr if no existing device is to be imported.
+
+    \note When importing a device, both the device and the device context must be set to valid objects.
 */
 
 /*!
     \variable QRhiD3D11NativeHandles::context
+
+    Points to a \l{https://learn.microsoft.com/en-us/windows/win32/api/d3d11/nn-d3d11-id3d11devicecontext}{ID3D11DeviceContext}
+    or left set to \nullptr if no existing device context is to be imported.
+
+    \note When importing a device, both the device and the device context must be set to valid objects.
 */
 
 /*!
     \variable QRhiD3D11NativeHandles::featureLevel
+
+    Specifies the feature level passed to
+    \l{https://learn.microsoft.com/en-us/windows/win32/api/d3d11/nf-d3d11-d3d11createdevice}{D3D11CreateDevice()}.
+    Relevant only when QRhi creates the device, ignored when importing a device
+    and device context. When not set, the default rules outlined in the D3D
+    documentation apply.
 */
 
 /*!
     \variable QRhiD3D11NativeHandles::adapterLuidLow
+
+    The low part of the local identifier (LUID) of the DXGI adapter to use.
+    Relevant only when QRhi creates the device, ignored when importing a device
+    and device context.
 */
 
 /*!
     \variable QRhiD3D11NativeHandles::adapterLuidHigh
+
+    The high part of the local identifier (LUID) of the DXGI adapter to use.
+    Relevant only when QRhi creates the device, ignored when importing a device
+    and device context.
 */
 
 // help mingw with its ancient sdk headers
diff --git a/src/gui/rhi/qrhid3d12.cpp b/src/gui/rhi/qrhid3d12.cpp
index d77e2db091..0f176c683d 100644
--- a/src/gui/rhi/qrhid3d12.cpp
+++ b/src/gui/rhi/qrhid3d12.cpp
@@ -83,22 +83,48 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \variable QRhiD3D12NativeHandles::dev
+
+    Points to a
+    \l{https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nn-d3d12-id3d12device}{ID3D12Device}
+    or left set to \nullptr if no existing device is to be imported.
 */
 
 /*!
     \variable QRhiD3D12NativeHandles::minimumFeatureLevel
+
+    Specifies the \b minimum feature level passed to
+    \l{https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nf-d3d12-d3d12createdevice}{D3D12CreateDevice()}.
+    When not set, \c{D3D_FEATURE_LEVEL_11_0} is used. See
+    \l{https://learn.microsoft.com/en-us/windows/win32/direct3d12/hardware-feature-levels}{this
+    page} for details.
+
+    Relevant only when QRhi creates the device, ignored when importing a device
+    and device context.
 */
 
 /*!
     \variable QRhiD3D12NativeHandles::adapterLuidLow
+
+    The low part of the local identifier (LUID) of the DXGI adapter to use.
+    Relevant only when QRhi creates the device, ignored when importing a device
+    and device context.
 */
 
 /*!
     \variable QRhiD3D12NativeHandles::adapterLuidHigh
+
+    The high part of the local identifier (LUID) of the DXGI adapter to use.
+    Relevant only when QRhi creates the device, ignored when importing a device
+    and device context.
 */
 
 /*!
     \variable QRhiD3D12NativeHandles::commandQueue
+
+    When set, must point to a
+    \l{https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nn-d3d12-id3d12commandqueue}{ID3D12CommandQueue}.
+    It allows to optionally import a command queue as well, in addition to a
+    device.
 */
 
 /*!
diff --git a/src/gui/rhi/qrhimetal.mm b/src/gui/rhi/qrhimetal.mm
index b69bc17f51..e10da4ca0e 100644
--- a/src/gui/rhi/qrhimetal.mm
+++ b/src/gui/rhi/qrhimetal.mm
@@ -103,10 +103,15 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \variable QRhiMetalNativeHandles::dev
+
+    Set to a valid MTLDevice to import an existing device.
 */
 
 /*!
     \variable QRhiMetalNativeHandles::cmdQueue
+
+    Set to a valid MTLCommandQueue when importing an existing command queue.
+    When \nullptr, QRhi will create a new command queue.
 */
 
 /*!