software: Add support for QSGRenderNode

Have to change getResource() a bit since it turns out it is not suitable
currently for backends that do not have a per-window rendercontext and do
not implement the interface on the rendercontext. Pass in the window to
make sure it can always figure out which window we want the resources for.
(we do not want rendererInterface() to return window-specific instances
created on the fly, with ownership issues, so stick with the simple model
where backends implement the interface on one of their existing classes)

To support clipping, QSGRenderNode::RenderState is extended accordingly.
Also updated the docs since some claims in the rendernode docs are not true
since Qt 5.3.

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

5 files changed, 43 insertions, 19 deletions

diff --git a/src/quick/scenegraph/coreapi/qsgbatchrenderer.cpp b/src/quick/scenegraph/coreapi/qsgbatchrenderer.cpp
index d45a0ea75d..bee2015007 100644
--- a/src/quick/scenegraph/coreapi/qsgbatchrenderer.cpp
+++ b/src/quick/scenegraph/coreapi/qsgbatchrenderer.cpp
@@ -2768,6 +2768,7 @@ struct RenderNodeState : public QSGRenderNode::RenderState
     bool scissorEnabled() const override { return m_scissorEnabled; }
     int stencilValue() const override { return m_stencilValue; }
     bool stencilEnabled() const override { return m_stencilEnabled; }
+    const QRegion *clipRegion() const override { return nullptr; }
 
     const QMatrix4x4 *m_projectionMatrix;
     QRect m_scissorRect;
diff --git a/src/quick/scenegraph/coreapi/qsgrendererinterface.cpp b/src/quick/scenegraph/coreapi/qsgrendererinterface.cpp
index 04e71441f6..fa543aecad 100644
--- a/src/quick/scenegraph/coreapi/qsgrendererinterface.cpp
+++ b/src/quick/scenegraph/coreapi/qsgrendererinterface.cpp
@@ -81,9 +81,10 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \enum QSGRendererInterface::Resource
-    \value Device The graphics device
-    \value CommandQueue The graphics command queue used by the scenergaph
-    \value CommandList The command list or buffer used by the scenegraph
+    \value Device The graphics device, when applicable.
+    \value CommandQueue The graphics command queue used by the scenegraph, when applicable.
+    \value CommandList The command list or buffer used by the scenegraph, when applicable.
+    \value Painter The active QPainter used by the scenegraph, when running with the software backend.
  */
 
 /*!
@@ -134,10 +135,13 @@ QSGRendererInterface::~QSGRendererInterface()
     example, \c{VkDevice dev = *static_cast<VkDevice *>(result)}). The latter
     is necessary since such handles may have sizes different from a pointer.
 
+    \note The ownership of the returned pointer is never transferred to the caller.
+
     \note This function must only be called on the render thread.
  */
-void *QSGRendererInterface::getResource(Resource resource) const
+void *QSGRendererInterface::getResource(QQuickWindow *window, Resource resource) const
 {
+    Q_UNUSED(window);
     Q_UNUSED(resource);
     return nullptr;
 }
@@ -147,10 +151,13 @@ void *QSGRendererInterface::getResource(Resource resource) const
     allows supporting any future resources that are not listed in the
     Resource enum.
 
+    \note The ownership of the returned pointer is never transferred to the caller.
+
     \note This function must only be called on the render thread.
  */
-void *QSGRendererInterface::getResource(const char *resource) const
+void *QSGRendererInterface::getResource(QQuickWindow *window, const char *resource) const
 {
+    Q_UNUSED(window);
     Q_UNUSED(resource);
     return nullptr;
 }
diff --git a/src/quick/scenegraph/coreapi/qsgrendererinterface.h b/src/quick/scenegraph/coreapi/qsgrendererinterface.h
index 234a061d0e..a50b362aeb 100644
--- a/src/quick/scenegraph/coreapi/qsgrendererinterface.h
+++ b/src/quick/scenegraph/coreapi/qsgrendererinterface.h
@@ -44,6 +44,8 @@
 
 QT_BEGIN_NAMESPACE
 
+class QQuickWindow;
+
 class Q_QUICK_EXPORT QSGRendererInterface
 {
 public:
@@ -57,7 +59,8 @@ public:
     enum Resource {
         Device,
         CommandQueue,
-        CommandList
+        CommandList,
+        Painter
     };
 
     enum ShaderType {
@@ -83,8 +86,8 @@ public:
 
     virtual GraphicsApi graphicsApi() const = 0;
 
-    virtual void *getResource(Resource resource) const;
-    virtual void *getResource(const char *resource) const;
+    virtual void *getResource(QQuickWindow *window, Resource resource) const;
+    virtual void *getResource(QQuickWindow *window, const char *resource) const;
 
     virtual ShaderType shaderType() const = 0;
     virtual ShaderCompilationTypes shaderCompilationType() const = 0;
diff --git a/src/quick/scenegraph/coreapi/qsgrendernode.cpp b/src/quick/scenegraph/coreapi/qsgrendernode.cpp
index 29e8251cb2..365abd09e2 100644
--- a/src/quick/scenegraph/coreapi/qsgrendernode.cpp
+++ b/src/quick/scenegraph/coreapi/qsgrendernode.cpp
@@ -111,6 +111,10 @@ QSGRenderNodePrivate::QSGRenderNodePrivate()
     call related settings (root signature, descriptor heaps, etc.) are always
     set again by the scenegraph so render() can freely change them.
 
+    The software backend exposes its QPainter and saves and restores before and
+    after invoking render(). Therefore reporting any changed states from here
+    is not necessary.
+
     \note This function may be called before render().
   */
 QSGRenderNode::StateFlags QSGRenderNode::changedStates() const
@@ -125,17 +129,6 @@ QSGRenderNode::StateFlags QSGRenderNode::changedStates() const
     directly invoking commands in the graphics API (OpenGL, Direct3D, etc.)
     currently in use.
 
-    The states necessary for clipping has already been set before the function
-    is called. The clip is a combination of a stencil clip and scissor clip.
-    Information about the clip is found in \a state.
-
-    \note This means that setting viewport, scissor rectangle, stencil
-    reference value, and similar is not necessary in render() since the
-    corresponding commands are on the command list (or, in case of OpenGL, the
-    context) already. However, for APIs other than OpenGL stencil-based
-    clipping will need enabling stencil testing in the pipeline state that is
-    used by render().
-
     The effective opacity can be retrieved with \l inheritedOpacity().
 
     The projection matrix is available through \a state, while the model-view
@@ -156,6 +149,12 @@ QSGRenderNode::StateFlags QSGRenderNode::changedStates() const
     QQuickFramebufferObject, QQuickWindow::beforeRendering(), or the
     equivalents of those for APIs other than OpenGL.
 
+    Clip information is calculated before the function is called, it is however
+    not enabled. Implementations wishing to take clipping into account can set
+    up scissoring or stencil based on the information in \a state. Some
+    scenegraph backends, software in particular, use no scissor or stencil.
+    There the clip region is provided as an ordinary QRegion.
+
     For OpenGL the following states are set on the render thread's context
     before this function is called:
     \list
@@ -287,6 +286,19 @@ QSGRenderNode::RenderState::~RenderState()
  */
 
 /*!
+    \fn const QRegion *QSGRenderNode::clipRegion() const
+
+    \return the current clip region or null for backends where clipping is
+    implemented via stencil or scissoring.
+
+    The software backend uses no projection, scissor or stencil, meaning most
+    of the render state is not in use. However, the clip region that can be set
+    on the QPainter still has to be communicated since reconstructing this
+    manually in render() is not reasonable. It can therefore be queried via
+    this function.
+ */
+
+/*!
     \return pointer to a \a state value.
 
     Reserved for future use.
diff --git a/src/quick/scenegraph/coreapi/qsgrendernode.h b/src/quick/scenegraph/coreapi/qsgrendernode.h
index 17569f8c59..6eb425c03b 100644
--- a/src/quick/scenegraph/coreapi/qsgrendernode.h
+++ b/src/quick/scenegraph/coreapi/qsgrendernode.h
@@ -68,6 +68,7 @@ public:
         virtual bool scissorEnabled() const = 0;
         virtual int stencilValue() const = 0;
         virtual bool stencilEnabled() const = 0;
+        virtual const QRegion *clipRegion() const = 0;
         virtual void *get(const char *state) const;
     };