src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   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
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \title Qt Quick Scene Graph
  30 \page qtquick-visualcanvas-scenegraph.html
  31
  32 \section1 What is a Scene Graph?
  33
  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.
  41
  42 \section1 The Scene Graph in Qt Quick
  43
  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.
  51
  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 QQuickCanvas class and custom QML elements will add their graphical
  55 primitives into the scene graph through a call to
  56 QQuickItem::updatePaintNode().
  57
  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.
  64
  65
  66
  67 \section1 Scene Graph Nodes
  68
  69 The scene graph can only contain a predefined set of node types, each
  70 serving a dedicated purpose.
  71
  72 \list
  73
  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.
  78
  79 \li QSGTransformNode - implements transformations in the scene
  80 graph. Nested transforms are multiplied together.
  81
  82 \li QSGOpacityNode - for node opacity changes. Nested opacity nodes have
  83 cumulative effect.
  84
  85 \li QSGClipNode - implements clipping in the scene graph. Nested clips
  86 are intersected.
  87
  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.
  91
  92 \endlist
  93
  94
  95
  96 \section1 Rendering
  97
  98 The rendering of the scene graph happens internally in the
  99 QQuickCanvas class and is described under the \l{Scene Graph and
 100 Rendering} section.
 101
 102 How to integrate QPainter based graphics is explained in \l{Custom
 103 Items using QPainter}.
 104
 105
 106
 107 \section1 Scene Graph Backend
 108
 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.
 113 It includes:
 114
 115 \list
 116
 117 \li Custom textures; specifically the implementation of
 118 QQuickCanvas::createTextureFromImage and the internal representation
 119 of the texture used by \l Image and \l BorderImage elements.
 120
 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.
 125
 126 \li Custom scene graph implementation of many of the default QML
 127 elements, including its text and font rendering.
 128
 129 \li Custom animation driver; allows the animation system to hook
 130 into the low-level display vertical refresh to get smooth rendering.
 131
 132 \li Custom render loop; allows better control over how QML deals
 133 with multiple windows.
 134
 135 \endlist
 136
 137 */