Rename setSceneGraphBackend to setGraphicsApi

...and fix up the docs.

The string-based setSceneGraphBackend() stays of course (the docs have
been enhanced, however). The GraphicsApi enum-based overload is now
renamed to setGraphicsApi().

Using the same name for both functions is a historical artifact, reflecting
the evolution (5.0 - 5.8 - 5.14). In 6.0 we can give it a more appropriate
name, since it does not have much to do with "backends" from the user's
perspective.

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

7 files changed, 59 insertions, 20 deletions

diff --git a/src/quick/doc/src/concepts/visualcanvas/adaptations.qdoc b/src/quick/doc/src/concepts/visualcanvas/adaptations.qdoc
index d07885e6ad..e330806c85 100644
--- a/src/quick/doc/src/concepts/visualcanvas/adaptations.qdoc
+++ b/src/quick/doc/src/concepts/visualcanvas/adaptations.qdoc
@@ -59,7 +59,7 @@ is always built-in. As of Qt 6.0 it is always enabled. On platforms where
 multiple graphics APIs are available, the scenegraph makes a platform-specific
 choice. If this is not desired, applications can force a specified graphics API
 by setting the environment variable \c{QSG_RHI_BACKEND} or via \l
-QQuickWindow::setSceneGraphBackend() in combination with \l
+QQuickWindow::setGraphicsApi() in combination with \l
 QSGRendererInterface::GraphicsApi.
 
 Switching to a different adaptation can be achieved in two ways:
@@ -74,7 +74,7 @@ Switching to a different adaptation can be achieved in two ways:
 The following backends are supported:
 
 \list
-    \li Default - Request with the \c{""} string or a QSGRendererInterface::GraphicsApi enum value
+    \li Default - Request with the \c{"rhi"} string or a QSGRendererInterface::GraphicsApi enum value
         different than the ones listed below.
     \li Software - Request with the \c{"software"} string or the QSGRendererInterface::Software
         enum value.
diff --git a/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc b/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
index b06c972ddf..a3022f0e2b 100644
--- a/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
+++ b/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc
@@ -1020,7 +1020,7 @@ with multiple windows.
   will fail otherwise);
 
   \badcode
-      QQuickWindow::setSceneGraphBackend(QSGRendererInterface::VulkanRhi);
+      QQuickWindow::setGraphicsApi(QSGRendererInterface::VulkanRhi);
   \endcode
 
   See QSGRendererInterface::GraphicsApi. The enum values ending in \c Rhi are
diff --git a/src/quick/items/qquickrendercontrol.cpp b/src/quick/items/qquickrendercontrol.cpp
index c2adc2ef10..75472c3e6e 100644
--- a/src/quick/items/qquickrendercontrol.cpp
+++ b/src/quick/items/qquickrendercontrol.cpp
@@ -262,7 +262,7 @@ int QQuickRenderControl::samples() const
     QQuickRenderControl exists.
 
     To control what graphics API Qt Quick uses, call
-    QQuickWindow::setSceneGraphBackend() with one of the
+    QQuickWindow::setGraphicsApi() with one of the
     QSGRendererInterface:GraphicsApi constants. That must be done before
     calling this function.
 
diff --git a/src/quick/items/qquickwindow.cpp b/src/quick/items/qquickwindow.cpp
index 2cf3e09c5d..5c7c39edf6 100644
--- a/src/quick/items/qquickwindow.cpp
+++ b/src/quick/items/qquickwindow.cpp
@@ -4239,7 +4239,7 @@ bool QQuickWindow::isSceneGraphInitialized() const
 
     \since 6.0
 
-    \sa QQuickRenderControl, setGraphicsDevice(), setSceneGraphBackend()
+    \sa QQuickRenderControl, setGraphicsDevice(), setGraphicsApi()
  */
 void QQuickWindow::setRenderTarget(const QQuickRenderTarget &target)
 {
@@ -5567,39 +5567,74 @@ QSGRendererInterface *QQuickWindow::rendererInterface() const
 }
 
 /*!
-    Requests the specified scene graph or RHI \a backend. Backends can either be
-    built-in or be installed in form of dynamically loaded plugins. When the
-    built-in, default graphics adaptation is used, \a backend specifies which
-    graphics API (OpenGL, Vulkan, Metal, or Direct3D) the scene graph should use
-    to render. In addition, the \c software backend is built-in as well, and can
-    be requested by setting \a api to QSGRendererInterface::Software.
+    Requests the specified graphics \a api.
+
+    When the built-in, default graphics adaptation is used, \a api specifies
+    which graphics API (OpenGL, Vulkan, Metal, or Direct3D) the scene graph
+    should use to render. In addition, the \c software backend is built-in as
+    well, and can be requested by setting \a api to
+    QSGRendererInterface::Software.
+
+    Unlike setSceneGraphBackend(), which can only be used to request a given
+    backend (shipped either built-in or installed as dynamically loaded
+    plugins), this function works with the higher level concept of graphics
+    APIs. It covers the backends that ship with Qt Quick, and thus have
+    corresponding values in the QSGRendererInterface::GraphicsApi enum.
+
+    When this function is not called at all, and the equivalent environment
+    variable \c{QSG_RHI_BACKEND} is not set either, the scene graph will choose
+    the graphics API to use based on the platform.
+
+    This function becomes important in applications that are only prepared for
+    rendering with a given API. For example, if there is native OpenGL or
+    Vulkan rendering done by the application, it will want to ensure Qt Quick
+    is rendering using OpenGL or Vulkan too. Such applications are expected to
+    call this function early in their main() function.
 
     \note The call to the function must happen before constructing the first
     QQuickWindow in the application. The graphics API cannot be changed
-    afterwards. When used in combination with QQuickRenderControl, this rule is
+    afterwards.
+
+    \note When used in combination with QQuickRenderControl, this rule is
     relaxed: it is possible to change the graphics API, but only when all
     existing QQuickRenderControl and QQuickWindow instances have been
     destroyed.
 
+    To query what graphics API the scene graph is using to render,
+    QSGRendererInterface::graphicsApi() after the scene graph
+    \l{QQuickWindow::isSceneGraphInitialized()}{has initialized}, which
+    typically happens either when the window becomes visible for the first time, or
+    when QQuickRenderControl::initialize() is called.
+
+    To switch back to the default behavior, where the scene graph chooses a
+    graphics API based on the platform and other conditions, set \a api to
+    QSGRendererInterface::Unknown.
+
     \since 5.8
  */
-void QQuickWindow::setSceneGraphBackend(QSGRendererInterface::GraphicsApi api)
+void QQuickWindow::setGraphicsApi(QSGRendererInterface::GraphicsApi api)
 {
+    // Special cases: these are different scenegraph backends.
     switch (api) {
     case QSGRendererInterface::Software:
         setSceneGraphBackend(QStringLiteral("software"));
         break;
+    case QSGRendererInterface::OpenVG:
+        setSceneGraphBackend(QStringLiteral("openvg"));
+        break;
     default:
         break;
     }
+
+    // Standard case: tell the QRhi-based default adaptation what graphics api
+    // (QRhi backend) to use.
     if (QSGRendererInterface::isApiRhiBased(api) || api == QSGRendererInterface::Unknown)
         QSGRhiSupport::configure(api);
 }
 
 /*!
-    Requests a Qt Quick scenegraph backend for the specified graphics \a api.
-    Backends can either be built-in or be installed in form of dynamically
-    loaded plugins.
+    Requests a Qt Quick scenegraph \a backend. Backends can either be built-in
+    or be installed in form of dynamically loaded plugins.
 
     \overload
 
@@ -5627,6 +5662,9 @@ void QQuickWindow::setSceneGraphBackend(const QString &backend)
     subsequent calls to setSceneGraphBackend() until the first QQuickWindow in the
     application has been constructed.
 
+    \note The value only reflects the request in the \c{QT_QUICK_BACKEND}
+    environment variable after a QQuickWindow has been constructed.
+
     \since 5.9
  */
 QString QQuickWindow::sceneGraphBackend()
@@ -5695,7 +5733,7 @@ QString QQuickWindow::sceneGraphBackend()
 
     \since 6.0
 
-    \sa QQuickRenderControl, setRenderTarget(), setSceneGraphBackend()
+    \sa QQuickRenderControl, setRenderTarget(), setGraphicsApi()
  */
 void QQuickWindow::setGraphicsDevice(const QQuickGraphicsDevice &device)
 {
diff --git a/src/quick/items/qquickwindow.h b/src/quick/items/qquickwindow.h
index fd4fb28cbe..3a908e94f0 100644
--- a/src/quick/items/qquickwindow.h
+++ b/src/quick/items/qquickwindow.h
@@ -182,7 +182,8 @@ public:
 
     QSGRendererInterface *rendererInterface() const;
 
-    static void setSceneGraphBackend(QSGRendererInterface::GraphicsApi api);
+    static void setGraphicsApi(QSGRendererInterface::GraphicsApi api);
+
     static void setSceneGraphBackend(const QString &backend);
     static QString sceneGraphBackend();
 
diff --git a/src/quick/scenegraph/qsgrhisupport.cpp b/src/quick/scenegraph/qsgrhisupport.cpp
index 4ba0cca65e..5029103cff 100644
--- a/src/quick/scenegraph/qsgrhisupport.cpp
+++ b/src/quick/scenegraph/qsgrhisupport.cpp
@@ -120,7 +120,7 @@ void QSGRhiSupport::applySettings()
     m_settingsApplied = true;
 
     // This is also done when creating the renderloop but we may be before that
-    // in case we get here due to a setScenegraphBackend() -> configure() early
+    // in case we get here due to a setGraphicsApi() -> configure() early
     // on in main(). Avoid losing info logs since troubleshooting gets
     // confusing otherwise.
     QSGRhiSupport::checkEnvQSgInfo();
diff --git a/src/quickwidgets/qquickwidget.cpp b/src/quickwidgets/qquickwidget.cpp
index 2da5e21fb8..04c321d0a5 100644
--- a/src/quickwidgets/qquickwidget.cpp
+++ b/src/quickwidgets/qquickwidget.cpp
@@ -140,7 +140,7 @@ void QQuickWidgetPrivate::init(QQmlEngine* e)
     }
 
     if (QSGRhiSupport::instance()->rhiBackend() != QRhi::OpenGLES2)
-        qWarning("QQuickWidget is only supported on OpenGL. Use QQuickWindow::setSceneGraphBackend() to override the default.");
+        qWarning("QQuickWidget is only supported on OpenGL. Use QQuickWindow::setGraphicsApi() to override the default.");
 
     engine = e;