1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the documentation of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** GNU Free Documentation License
10 ** Alternatively, this file may be used under the terms of the GNU Free
11 ** Documentation License version 1.3 as published by the Free Software
12 ** Foundation and appearing in the file included in the packaging of
16 ** Alternatively, this file may be used in accordance with the terms
17 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
29 \title Qt Quick Scene Graph
30 \page qtquick-visualcanvas-scenegraph.html
32 \section1 What is a Scene Graph?
34 When drawing visual objects of a user-interface, it can be beneficial to group
35 drawing operations which are similar. For example, if a user-interface
36 includes many similar text boxes, each with a light-blue background, then all
37 of those text boxes could be painted at the same time, prior to painting any
38 of the text in each box, as this might be more performant than painting one of
39 the text boxes, and then painting its text, and then painting the next text
40 box, and then its text, and so on.
42 \section1 The Scene Graph in Qt Quick
44 Qt Quick 2 makes use of a dedicated scene graph based on OpenGL ES 2.0
45 or OpenGL 2.0 for its rendering. Using a scene graph for graphics
46 rather than the traditional imperative painting systems (QPainter and
47 similar), means the scene to be rendered can be retained between
48 frames and the complete set of primitives to render is known before
49 rendering starts. This opens up for a number of optimizations, such as
50 batch rendering to minimize state changes and discarding obscured primitives.
52 The scene graph is closely tied to QML and can not be used as
53 stand-alone. The scene graph is managed and rendered by the
54 QQuickWindow class and custom QML elements will add their graphical
55 primitives into the scene graph through a call to
56 QQuickItem::updatePaintNode().
58 The QML scene graph is a graphical representation of the QML scene. It
59 can be thought of as a graphical deep copy, an independent structure that
60 contains enough information to render the QML Scene. Once it has been set
61 up, it can be manipulated and rendered independently of the state of
62 the QML scene. On some platforms, the scene graph will even be
63 rendered on a dedicated render thread.
67 \section1 Scene Graph Nodes
69 The scene graph can only contain a predefined set of node types, each
70 serving a dedicated purpose.
74 \li QSGGeometryNode - for all rendered content in the scene
75 graph. In most cases, it will be enough for a custom QQuickItem object to
76 simply return a single QSGGeometryNode object from the
77 QQuickItem::updatePaintNode() call.
79 \li QSGTransformNode - implements transformations in the scene
80 graph. Nested transforms are multiplied together.
82 \li QSGOpacityNode - for node opacity changes. Nested opacity nodes have
85 \li QSGClipNode - implements clipping in the scene graph. Nested clips
88 \li QSGNode - base class for all nodes in the scene graph. Its primary purpose
89 is provide the ability to insert nodes into the scene graph that do not affect
90 the rendering, such as the shared root for a subtree of geometry nodes.
98 The rendering of the scene graph happens internally in the
99 QQuickWindow class and is described under the \l{Scene Graph and
102 How to integrate QPainter based graphics is explained in \l{Custom
103 Items using QPainter}.
107 \section1 Scene Graph Backend
109 In addition to the public API, the scene graph has an adaptation layer
110 which opens up the implementation to do hardware specific
111 adaptations. This is an undocumented, internal and private plugin API,
112 which lets hardware adaptation teams make the most of their hardware.
117 \li Custom textures; specifically the implementation of
118 QQuickWindow::createTextureFromImage and the internal representation
119 of the texture used by \l Image and \l BorderImage elements.
121 \li Custom renderer; the adaptation layer lets the plugin decide how
122 the scene graph is traversed and rendered, making it possible to
123 optimize the rendering algorithm for a specific hardware or to make
124 use of extensions which improve performance.
126 \li Custom scene graph implementation of many of the default QML
127 elements, including its text and font rendering.
129 \li Custom animation driver; allows the animation system to hook
130 into the low-level display vertical refresh to get smooth rendering.
132 \li Custom render loop; allows better control over how QML deals
133 with multiple windows.