Add an API to set the scenegraph backend

As an alternative to QT_QUICK_BACKEND and QMLSCENE_DEVICE.

The need for this is twofold: it is requested by Creator since environment
variables have potential issues with child processes inheriting them.
Also, platforms like WinRT may have issues with environment variables - as
such a concept may not necessarily exist.

Change-Id: Ia66b78dc83fce5af0f36d4b34dc094582eb6e61d
Reviewed-by: Robin Burchell <robin.burchell@viroteck.net>

4 files changed, 78 insertions, 12 deletions

diff --git a/src/quick/items/qquickwindow.cpp b/src/quick/items/qquickwindow.cpp
index cdde780932..b9fb0721b3 100644
--- a/src/quick/items/qquickwindow.cpp
+++ b/src/quick/items/qquickwindow.cpp
@@ -78,7 +78,6 @@
 # include <private/qopenglvertexarrayobject_p.h>
 # include <private/qsgdefaultrendercontext_p.h>
 #endif
-#include <qsgrendererinterface.h>
 
 QT_BEGIN_NAMESPACE
 
@@ -4430,6 +4429,57 @@ QSGRendererInterface *QQuickWindow::rendererInterface() const
     return isSceneGraphInitialized() ? d->context->sceneGraphContext()->rendererInterface(d->context) : nullptr;
 }
 
+/*!
+    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.
+
+    \note The call to the function must happen before constructing the first
+    QQuickWindow in the application. It cannot be changed afterwards.
+
+    If \a backend is invalid or an error occurs, the default backend (OpenGL or
+    software, depending on the Qt configuration) is used.
+
+    \since 5.8
+ */
+void QQuickWindow::setSceneGraphBackend(QSGRendererInterface::GraphicsAPI api)
+{
+    switch (api) {
+    case QSGRendererInterface::Software:
+        setSceneGraphBackend(QStringLiteral("software"));
+        break;
+    case QSGRendererInterface::Direct3D12:
+        setSceneGraphBackend(QStringLiteral("d3d12"));
+        break;
+    default:
+        break;
+    }
+}
+
+/*!
+    Requests the specified Qt Quick scenegraph \a backend. Backends can either
+    be built-in or be installed in form of dynamically loaded plugins.
+
+    \overload
+
+    \note The call to the function must happen before constructing the first
+    QQuickWindow in the application. It cannot be changed afterwards.
+
+    If \a backend is invalid or an error occurs, the default backend (OpenGL or
+    software, depending on the Qt configuration) is used.
+
+    \note Calling this function is equivalent to setting the
+    \c QT_QUICK_BACKEND or \c QMLSCENE_DEVICE environment variables. However, this
+    API is safer to use in applications that spawn other processes as there is
+    no need to worry about environment inheritance.
+
+    \since 5.8
+ */
+void QQuickWindow::setSceneGraphBackend(const QString &backend)
+{
+    QSGContext::setBackend(backend);
+}
+
 #include "moc_qquickwindow.cpp"
 
 QT_END_NAMESPACE
diff --git a/src/quick/items/qquickwindow.h b/src/quick/items/qquickwindow.h
index 977b4956b2..37be6d591c 100644
--- a/src/quick/items/qquickwindow.h
+++ b/src/quick/items/qquickwindow.h
@@ -41,6 +41,7 @@
 #define QQUICKWINDOW_H
 
 #include <QtQuick/qtquickglobal.h>
+#include <QtQuick/qsgrendererinterface.h>
 #include <QtCore/qmetatype.h>
 #include <QtGui/qopengl.h>
 #include <QtGui/qwindow.h>
@@ -60,7 +61,6 @@ class QQmlIncubationController;
 class QInputMethodEvent;
 class QQuickCloseEvent;
 class QQuickRenderControl;
-class QSGRendererInterface;
 
 class Q_QUICK_EXPORT QQuickWindow : public QWindow
 {
@@ -156,6 +156,9 @@ public:
 
     QSGRendererInterface *rendererInterface() const;
 
+    static void setSceneGraphBackend(QSGRendererInterface::GraphicsAPI api);
+    static void setSceneGraphBackend(const QString &backend);
+
 Q_SIGNALS:
     void frameSwapped();
     Q_REVISION(2) void openglContextCreated(QOpenGLContext *context);
diff --git a/src/quick/scenegraph/qsgcontext_p.h b/src/quick/scenegraph/qsgcontext_p.h
index 2139377ebb..2fef0ff1e8 100644
--- a/src/quick/scenegraph/qsgcontext_p.h
+++ b/src/quick/scenegraph/qsgcontext_p.h
@@ -181,6 +181,8 @@ public:
     static QSGContext *createDefaultContext();
     static QQuickTextureFactory *createTextureFactoryFromImage(const QImage &image);
     static QSGRenderLoop *createWindowManager();
+
+    static void setBackend(const QString &backend);
 };
 
 QT_END_NAMESPACE
diff --git a/src/quick/scenegraph/qsgcontextplugin.cpp b/src/quick/scenegraph/qsgcontextplugin.cpp
index 5a5a16e005..7569cd2495 100644
--- a/src/quick/scenegraph/qsgcontextplugin.cpp
+++ b/src/quick/scenegraph/qsgcontextplugin.cpp
@@ -67,9 +67,9 @@ Q_GLOBAL_STATIC_WITH_ARGS(QFactoryLoader, loader,
     (QSGContextFactoryInterface_iid, QLatin1String("/scenegraph")))
 #endif
 
-struct QSGAdaptionBackendData
+struct QSGAdaptationBackendData
 {
-    QSGAdaptionBackendData();
+    QSGAdaptationBackendData();
 
     bool tried;
     QSGContextFactoryInterface *factory;
@@ -77,9 +77,11 @@ struct QSGAdaptionBackendData
     QSGContextFactoryInterface::Flags flags;
 
     QVector<QSGContextFactoryInterface *> builtIns;
+
+    QString quickWindowBackendRequest;
 };
 
-QSGAdaptionBackendData::QSGAdaptionBackendData()
+QSGAdaptationBackendData::QSGAdaptationBackendData()
     : tried(false)
     , factory(nullptr)
     , flags(0)
@@ -88,7 +90,7 @@ QSGAdaptionBackendData::QSGAdaptionBackendData()
     builtIns.append(new QSGSoftwareAdaptation);
 }
 
-Q_GLOBAL_STATIC(QSGAdaptionBackendData, qsg_adaptation_data)
+Q_GLOBAL_STATIC(QSGAdaptationBackendData, qsg_adaptation_data)
 
 // This only works when the backend is loaded (contextFactory() was called),
 // otherwise the return value is 0.
@@ -100,15 +102,15 @@ QSGContextFactoryInterface::Flags qsg_backend_flags()
     return qsg_adaptation_data()->flags;
 }
 
-QSGAdaptionBackendData *contextFactory()
+QSGAdaptationBackendData *contextFactory()
 {
-    QSGAdaptionBackendData *backendData = qsg_adaptation_data();
+    QSGAdaptationBackendData *backendData = qsg_adaptation_data();
 
     if (!backendData->tried) {
         backendData->tried = true;
 
         const QStringList args = QGuiApplication::arguments();
-        QString requestedBackend;
+        QString requestedBackend = backendData->quickWindowBackendRequest; // empty or set via QQuickWindow::setBackend()
 
         for (int index = 0; index < args.count(); ++index) {
             if (args.at(index).startsWith(QLatin1String("--device="))) {
@@ -184,7 +186,7 @@ QSGAdaptionBackendData *contextFactory()
 */
 QSGContext *QSGContext::createDefaultContext()
 {
-    QSGAdaptionBackendData *backendData = contextFactory();
+    QSGAdaptationBackendData *backendData = contextFactory();
     if (backendData->factory)
         return backendData->factory->create(backendData->name);
 #ifndef QT_NO_OPENGL
@@ -205,7 +207,7 @@ QSGContext *QSGContext::createDefaultContext()
 
 QQuickTextureFactory *QSGContext::createTextureFactoryFromImage(const QImage &image)
 {
-    QSGAdaptionBackendData *backendData = contextFactory();
+    QSGAdaptationBackendData *backendData = contextFactory();
     if (backendData->factory)
         return backendData->factory->createTextureFactoryFromImage(image);
     return 0;
@@ -219,10 +221,19 @@ QQuickTextureFactory *QSGContext::createTextureFactoryFromImage(const QImage &im
 
 QSGRenderLoop *QSGContext::createWindowManager()
 {
-    QSGAdaptionBackendData *backendData = contextFactory();
+    QSGAdaptationBackendData *backendData = contextFactory();
     if (backendData->factory)
         return backendData->factory->createWindowManager();
     return 0;
 }
 
+void QSGContext::setBackend(const QString &backend)
+{
+    QSGAdaptationBackendData *backendData = qsg_adaptation_data();
+    if (backendData->tried)
+        qWarning("Scenegraph already initialized, setBackend() request ignored");
+
+    backendData->quickWindowBackendRequest = backend;
+}
+
 QT_END_NAMESPACE