Rename setPersistentOpenGLContext and revise related docs

These persistent hints are still taken into account by the threaded
render loop, so keep them, but get rid of "OpenGL Context" from the
function names.

The qquickwindow autotest has been updated accordingly, and with a few
OpenGL-related cleanups it now runs without any warnings or skips with
OpenGL-on-RHI, while it skips only 1 case when running with some other
API, and 2 with the software backend.

[ChangeLog][Qt Quick][QQuickWindow] The setPersistentOpenGLContext() and
isPersistentOpenGLContext() functions are renamed to
setPersistentGraphics() and isPersistentGraphics().

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

4 files changed, 49 insertions, 44 deletions

diff --git a/src/quick/items/qquickrendercontrol.cpp b/src/quick/items/qquickrendercontrol.cpp
index a34d5f6a96..1f9161d70a 100644
--- a/src/quick/items/qquickrendercontrol.cpp
+++ b/src/quick/items/qquickrendercontrol.cpp
@@ -375,7 +375,7 @@ bool QQuickRenderControl::sync()
 
   \note This function does not take
   QQuickWindow::persistentSceneGraph() or
-  QQuickWindow::persistentOpenGLContext() into account. This means
+  QQuickWindow::persistentGraphics() into account. This means
   that context-specific resources are always released.
  */
 void QQuickRenderControl::invalidate()
diff --git a/src/quick/items/qquickwindow.cpp b/src/quick/items/qquickwindow.cpp
index 620f707570..262f4d58cf 100644
--- a/src/quick/items/qquickwindow.cpp
+++ b/src/quick/items/qquickwindow.cpp
@@ -746,7 +746,7 @@ QQuickWindowPrivate::QQuickWindowPrivate()
     , pointerEventRecursionGuard(0)
     , clearColor(Qt::white)
     , clearBeforeRendering(true)
-    , persistentGLContext(true)
+    , persistentGraphics(true)
     , persistentSceneGraph(true)
     , lastWheelEventAccepted(false)
     , componentCompleted(true)
@@ -1624,15 +1624,18 @@ QQuickWindow::~QQuickWindow()
     Calling this function requests the scene graph to release cached graphics
     resources, such as graphics pipeline objects or shader programs.
 
+    \note The releasing of cached graphics resources is not dependent on the
+    hint from setPersistentGraphics().
+
     Additionally, depending on the render loop in use, this function may also
     result in the scene graph and all rendering resources to be released. If
     this happens, the sceneGraphInvalidated() signal will be emitted, allowing
     users to clean up their own graphics resources. The
-    setPersistentOpenGLContext() and setPersistentSceneGraph() functions can be
+    setPersistentGraphics() and setPersistentSceneGraph() functions can be
     used to prevent this from happening, if handling the cleanup is not feasible
     in the application, at the cost of higher memory usage.
 
-    \sa sceneGraphInvalidated(), setPersistentOpenGLContext(), setPersistentSceneGraph()
+    \sa sceneGraphInvalidated(), setPersistentGraphics(), setPersistentSceneGraph()
  */
 
 void QQuickWindow::releaseResources()
@@ -1646,52 +1649,54 @@ void QQuickWindow::releaseResources()
 
 
 /*!
-    Sets whether the OpenGL context should be preserved, and cannot be
+    Sets whether the graphics resources (graphics device or context,
+    swapchain, buffers, textures) should be preserved, and cannot be
     released until the last window is deleted, to \a persistent. The
     default value is true.
 
-    The OpenGL context can be released to free up graphics resources
-    when the window is obscured, hidden or not rendering. When this
-    happens is implementation specific.
+    When calling releaseResources(), or when the window gets hidden (more
+    specifically, not renderable), some render loops have the possibility
+    to release all, not just the cached, graphics resources. This can free
+    up memory temporarily, but it also means the rendering engine will have
+    to do a full, potentially costly reinitialization of the resources when
+    the window needs to render again.
+
+    \note The rules for when a window is not renderable are platform and
+    window manager specific.
 
-    The QOpenGLContext::aboutToBeDestroyed() signal is emitted from
-    the QQuickWindow::openglContext() when the OpenGL context is about
-    to be released.  The QQuickWindow::sceneGraphInitialized() signal
-    is emitted when a new OpenGL context is created for this
-    window. Make a Qt::DirectConnection to these signals to be
-    notified.
+    \note All graphics resources are released when the last QQuickWindow is
+    deleted, regardless of this setting.
 
-    The OpenGL context is still released when the last QQuickWindow is
-    deleted.
+    \note This is a hint, and is not guaranteed that it is taken into account.
 
-    \note This only has an effect when using the default OpenGL scene
-    graph adaptation.
+    \note This hint does not apply to cached resources, that are relatively
+    cheap to drop and then recreate later. Therefore, calling releaseResources()
+    will typically lead to releasing those regardless of the value of this hint.
 
-    \sa setPersistentSceneGraph(),
-    QOpenGLContext::aboutToBeDestroyed(), sceneGraphInitialized()
+    \sa setPersistentSceneGraph(), sceneGraphInitialized(), sceneGraphInvalidated(), releaseResources()
  */
 
-void QQuickWindow::setPersistentOpenGLContext(bool persistent)
+void QQuickWindow::setPersistentGraphics(bool persistent)
 {
     Q_D(QQuickWindow);
-    d->persistentGLContext = persistent;
+    d->persistentGraphics = persistent;
 }
 
 
 
 /*!
-    Returns whether the OpenGL context can be released during the
+    Returns whether essential graphics resources can be released during the
     lifetime of the QQuickWindow.
 
-    \note This is a hint. When and how this happens is implementation
-    specific.  It also only has an effect when using the default OpenGL
-    scene graph adaptation
+    \note This is a hint, and is not guaranteed that it is taken into account.
+
+    \sa setPersistentGraphics()
  */
 
-bool QQuickWindow::isPersistentOpenGLContext() const
+bool QQuickWindow::isPersistentGraphics() const
 {
     Q_D(const QQuickWindow);
-    return d->persistentGLContext;
+    return d->persistentGraphics;
 }
 
 
@@ -1701,21 +1706,21 @@ bool QQuickWindow::isPersistentOpenGLContext() const
     Persistent means the nodes and resources cannot be released.
     The default value is \c true.
 
-    The scene graph nodes and resources can be released to free up
-    graphics resources when the window is obscured, hidden or not
-    rendering. When this happens is implementation specific.
+    When calling releaseResources(), when the window gets hidden (more
+    specifically, not renderable), some render loops have the possibility
+    to release the scene graph nodes and related graphics resources. This
+    frees up memory temporarily, but will also mean the scene graph has to
+    be rebuilt when the window renders next time.
+
+    \note The rules for when a window is not renderable are platform and
+    window manager specific.
 
-    The QQuickWindow::sceneGraphInvalidated() signal is emitted when
-    cleanup occurs. The QQuickWindow::sceneGraphInitialized() signal
-    is emitted when a new scene graph is recreated for this
-    window. Make a Qt::DirectConnection to these signals to be
-    notified.
+    \note The scene graph nodes and resources are always released when the
+    last QQuickWindow is deleted, regardless of this setting.
 
-    The scene graph nodes and resources are still released when the
-    last QQuickWindow is deleted.
+    \note This is a hint, and is not guaranteed that it is taken into account.
 
-    \sa setPersistentOpenGLContext(),
-    sceneGraphInvalidated(), sceneGraphInitialized()
+    \sa setPersistentGraphics(), sceneGraphInvalidated(), sceneGraphInitialized(), releaseResources()
  */
 
 void QQuickWindow::setPersistentSceneGraph(bool persistent)
diff --git a/src/quick/items/qquickwindow.h b/src/quick/items/qquickwindow.h
index f701cd1deb..28ff08786a 100644
--- a/src/quick/items/qquickwindow.h
+++ b/src/quick/items/qquickwindow.h
@@ -170,10 +170,10 @@ public:
     static bool hasDefaultAlphaBuffer();
     static void setDefaultAlphaBuffer(bool useAlpha);
 
-    void setPersistentOpenGLContext(bool persistent); // ### Qt 6 is this relevant / usable anymore?
-    bool isPersistentOpenGLContext() const;
+    void setPersistentGraphics(bool persistent);
+    bool isPersistentGraphics() const;
 
-    void setPersistentSceneGraph(bool persistent); // ### Qt 6 is this relevant / usable anymore?
+    void setPersistentSceneGraph(bool persistent);
     bool isPersistentSceneGraph() const;
 
     QOpenGLContext *openglContext() const; // ### Qt 6 consider if this is kept or not
diff --git a/src/quick/items/qquickwindow_p.h b/src/quick/items/qquickwindow_p.h
index 6c16504ff7..89dbe2f5dd 100644
--- a/src/quick/items/qquickwindow_p.h
+++ b/src/quick/items/qquickwindow_p.h
@@ -274,7 +274,7 @@ public:
 
     uint clearBeforeRendering : 1;
 
-    uint persistentGLContext : 1;
+    uint persistentGraphics : 1;
     uint persistentSceneGraph : 1;
 
     uint lastWheelEventAccepted : 1;