Make rendernode suitable for public consumption

For non-OpenGL APIs the primary (and likely the only) way to add custom
rendering into the Qt Quick scene is via the render node. Other
approaches,like the before/afterRendering signals,
QQuickFramebufferObject, remain OpenGL-only. (although QQuickFramebufferObject
may get a multi-API replacement based on QSGRenderNode at a later time)

Note that this is not a generic 3D content integration enabler. It targets
creating 2D and 2.5D Quick items with custom rendering via the graphics
API in use.

Make QSGRenderNode public, enhance the docs a bit and add a releaseResources().
Add a QSGRendererInterface with a query function in QQuickWindow and
QSGEngine. The scenegraph adaptation can then return a custom implementation of
the interface. This will be necessary to query API-specific values, f.ex. the
ID3D12Device and ID3D12CommandList when running with the d3d12 backend.

The interface allows querying the API and void* resources. Resources that
we know about in advance are enum-based to prevent the
QPlatformNativeInterface-like ugliness of string keys.

Support is there in the batch renderer already, fix this up according to
the new public API, and implement the corresponding bits for the D3D12
renderer.

For D3D12, fix also an issue with QSGNode destruction where graphics resources
in use were attempted to be final-released without a proper wait.

The semantics of changedStates() in QSGRenderNode is changed so that it can be
called at any time, including before render(). This is very useful since we can
implement some state restoring in a more efficient manner.

Added a new example as well. Documentation for QSGRenderNode is heavily
expanded.

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

1 files changed, 119 insertions, 0 deletions

diff --git a/src/quick/scenegraph/coreapi/qsgrendererinterface.cpp b/src/quick/scenegraph/coreapi/qsgrendererinterface.cpp
new file mode 100644
index 0000000000..6a01fac212
--- /dev/null
+++ b/src/quick/scenegraph/coreapi/qsgrendererinterface.cpp
@@ -0,0 +1,119 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the QtQuick module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL3 included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 2.0 or (at your option) the GNU General
+** Public license version 3 or any later version approved by the KDE Free
+** Qt Foundation. The licenses are as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-2.0.html and
+** https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "qsgrendererinterface.h"
+
+QT_BEGIN_NAMESPACE
+
+/*!
+    \class QSGRendererInterface
+    \brief An interface providing access to some of the graphics API specific internals
+    of the scenegraph.
+    \inmodule QtQuick
+    \since 5.8
+
+    Renderer interfaces allow accessing graphics API specific functionality in
+    the scenegraph. Such internals are not typically exposed. However, when
+    integrating custom rendering via QSGRenderNode for example, it may become
+    necessary to query certain values, for instance the graphics device (e.g.
+    the Direct3D or Vulkan device) that is used by the scenegraph.
+
+    \note QSGRendererInterface is only available after the scenegraph is
+    initialized. Additionally, there may be backend-specific limitations on
+    when the functions can be called. The only way that is guaranteed to
+    succeed is calling them when the rendering of a node (i.e. the preparation
+    of the command list for the next frame) is active. In practice this
+    typically means QSGRenderNode::render().
+ */
+
+/*!
+    \enum QSGRenderNode::GraphicsAPI
+    \value Unknown An unknown graphics API is in use
+    \value Software The Qt Quick 2D Renderer is in use
+    \value OpenGL OpenGL ES 2.0 or higher
+    \value Direct3D12 Direct3D 12
+    \value Vulkan Vulkan
+    \value Metal Metal
+  */
+
+/*!
+    \enum QSGRenderNode::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
+ */
+
+QSGRendererInterface::~QSGRendererInterface()
+{
+}
+
+/*!
+    \fn QSGRenderNode::GraphicsAPI QSGRenderNode::graphicsAPI() const
+
+    Returns the graphics API that is in use by the Qt Quick scenegraph.
+ */
+
+/*!
+    Queries a graphics \a resource. Returns null when the resource in question is
+    not supported or not available.
+
+    When successful, the returned pointer is either a direct pointer to an
+    interface (and can be cast, for example, to \c{ID3D12Device *}) or a
+    pointer to an opaque handle that needs to be dereferenced first (for
+    example, \c{VkDevice dev = *static_cast<VkDevice *>(result)}). The latter
+    is necessary since such handles may have sizes different from a pointer.
+ */
+void *QSGRendererInterface::getResource(Resource resource) const
+{
+    Q_UNUSED(resource);
+    return nullptr;
+}
+
+/*!
+    Queries a graphics resource. \a resource is a backend-specific key. This
+    allows supporting any future resources that are not listed in the
+    Resource enum.
+ */
+void *QSGRendererInterface::getResource(const char *resource) const
+{
+    Q_UNUSED(resource);
+    return nullptr;
+}
+
+QT_END_NAMESPACE