From 37bf3b883d428d2fe0cae6513777d0c25c18d4ad Mon Sep 17 00:00:00 2001
From: Laszlo Agocs <laszlo.agocs@qt.io>
Date: Mon, 22 Aug 2022 16:22:49 +0200
Subject: [PATCH] rhi: metal: Update out-of-date internal comments

Would have been nice to provide a flag to set the METAL_DEVICE_WRAPPER_TYPE
env.var. but apparently it needs to be set very early, the QRhi just cannot
do it, it's too late to qputenv then. So just update the internal docs.

Change-Id: I94926debe3af73b67018c5449d7893df38f31f0d
Reviewed-by: Andy Nichols <andy.nichols@qt.io>
---
 src/gui/rhi/qrhimetal.mm | 21 ++++++++++++---------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/src/gui/rhi/qrhimetal.mm b/src/gui/rhi/qrhimetal.mm
index dc21feb74c9..ddf8961fe26 100644
--- a/src/gui/rhi/qrhimetal.mm
+++ b/src/gui/rhi/qrhimetal.mm
@@ -33,11 +33,11 @@ QT_BEGIN_NAMESPACE
 #endif
 
 // Note: we expect everything here pass the Metal API validation when running
-// in Debug mode in XCode. Some of the issues that break validation are not
-// obvious and not visible when running outside XCode.
-//
-// An exception is the nextDrawable Called Early blah blah warning, which is
-// plain and simply false.
+// in Debug mode in XCode (or with METAL_DEVICE_WRAPPER_TYPE=1). An exception
+// is the nextDrawable Called Early blah blah warning, which is plain and
+// simply false. This may not be present with newer XCode. There may also be
+// warnings about threading (e.g. about accessing view.layer), those are
+// expected for now.
 
 /*!
     \class QRhiMetalInitParams
@@ -52,10 +52,13 @@ QT_BEGIN_NAMESPACE
         rhi = QRhi::create(QRhi::Metal, &params);
     \endcode
 
-    \note Metal API validation cannot be enabled by the application. Instead,
-    run the debug build of the application in XCode. Generating a
-    \c{.xcodeproj} file via \c{qmake -spec macx-xcode} provides a convenient
-    way to enable this.
+    \note Metal API validation cannot be enabled programmatically by the QRhi.
+    Instead, either run the debug build of the application in XCode, by
+    generating a \c{.xcodeproj} file via \c{cmake -G Xcode}, or set the
+    environment variable \c{METAL_DEVICE_WRAPPER_TYPE=1}. The variable needs to
+    be set early on in the environment, perferably before starting the process;
+    attempting to set it at QRhi creation time is not functional in practice.
+    (too late probably)
 
     \note QRhiSwapChain can only target QWindow instances that have their
     surface type set to QSurface::MetalSurface.