doc/src/declarative/qdeclarativeperformance.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Free Documentation License
  17 ** Alternatively, this file may be used under the terms of the GNU Free
  18 ** Documentation License version 1.3 as published by the Free Software
  19 ** Foundation and appearing in the file included in the packaging of this
  20 ** file.
  21 **
  22 ** If you have questions regarding the use of this file, please contact
  23 ** Nokia at qt-info@nokia.com.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qdeclarativeperformance.html
  30 \title QML Performance
  31
  32 \section1 Opaque Items
  33
  34 Items hidden behind an opaque item incur a cost.  If an item will be enitrely
  35 obscured by an opaque item, set its opacity to 0.  One common example of
  36 this is when a "details" page is shown over the main application view.
  37
  38 \section1 Clipping
  39
  40 \e clip is set to false by default.  Enable clipping only when necessary.
  41
  42 \section1 Anchors vs. Binding
  43
  44 It is more efficient to use anchors rather than bindings to position items
  45 relative to each other.  Consider this use of bindings to position rect2
  46 relative to rect1:
  47
  48 \code
  49 Rectangle {
  50     id: rect1
  51     x: 20
  52     width: 200; height: 200
  53 }
  54 Rectangle {
  55     id: rect2
  56     x: rect1.x
  57     y: rect1.y + rect1.height
  58     width: rect1.width - 20
  59     height: 200
  60 }
  61 \endcode
  62
  63 This is achieved more efficiently using anchors:
  64
  65 \code
  66 Rectangle {
  67     id: rect1
  68     x: 20
  69     width: 200; height: 200
  70 }
  71 Rectangle {
  72     id: rect2
  73     height: 200
  74     anchors.left: rect1.left
  75     anchors.top: rect1.bottom
  76     anchors.right: rect1.right
  77     anchors.rightMargin: 20
  78 }
  79 \endcode
  80
  81 \section1 Images
  82
  83 Images consume a great deal of memory and may also be costly to load.  In order
  84 to deal with large images efficiently it is recommended that the Image::sourceSize
  85 property be set to a size no greater than that necessary to render it.  Beware that
  86 changing the sourceSize will cause the image to be reloaded.
  87
  88 Images on the local filesystem are usually loaded synchronously.  This is usually
  89 the desired behavior for user interface elements, however for large images that
  90 do not necessarily need to be visible immediately, set the Image::asynchronous
  91 property to true.  This will load the image in a low priority thread.
  92
  93 \section1 View Delegates
  94
  95 Delegates must be created quickly as the view is flicked.  There are two important
  96 aspects to maintaining a smooth view:
  97
  98 \list
  99 \o Small delegates - keep the amount of QML to a minimum.  Have just enough
 100 QML in the delegate to display the necessary information.  Any additional functionality
 101 that is only needed when the delegate is clicked, for example, should be created by
 102 a Loader as needed.
 103 \o Fast data access - ensure the data model is as fast as possible.
 104 \endlist
 105
 106 \section1 Image resources over composition
 107
 108 If possible, provide a single image resource, rather than using composition
 109 of a number of elements.  For example, a frame with a shadow could be created using
 110 a Rectangle placed over an Image providing the shadow.  It is more efficient to
 111 provide an image that includes the frame and the shadow.
 112
 113 \section1 Limit JavaScript
 114
 115 Avoid running JavaScript during animation.  For example, running a complex
 116 JavaScript expression for each frame of an x property animation.
 117
 118 \section1 Rendering
 119
 120 Often using a different graphics system will give superior performance to the native
 121 graphics system (this is especially the case on X11). This can be configured using
 122 QApplication::setGraphicsSystem() or via the command line using the \c -graphicssystem
 123 switch.
 124
 125 You can enable OpenGL acceleration using the \c opengl graphics system, or by setting a
 126 QGLWidget as the viewport of your QDeclarativeView.
 127
 128 You may need to try various options to find what works the best for your application.
 129 For embedded X11-based devices one recommended combination is to use the raster graphics
 130 system with a QGLWidget for the viewport. While this doesn't guarantee the \bold fastest
 131 performance for all use-cases, it typically has \bold{consistently good} performance for
 132 all use-cases. In contrast, only using the raster paint engine may result in very good
 133 performance for parts of your application and very poor performance elsewhere.
 134
 135 The QML Viewer uses the raster graphics system by default for X11 and OS X. It also
 136 includes a \c -opengl command line option which sets a QGLWidget as the viewport of the
 137 view. On OS X, a QGLWidget is always used.
 138
 139 You can also prevent QDeclarativeView from painting its window background if
 140 you will provide the background of your application using QML, e.g.
 141
 142 \code
 143 QDeclarativeView window;
 144 window.setAttribute(Qt::WA_OpaquePaintEvent);
 145 window.setAttribute(Qt::WA_NoSystemBackground);
 146 window.viewport()->setAttribute(Qt::WA_OpaquePaintEvent);
 147 window.viewport()->setAttribute(Qt::WA_NoSystemBackground);
 148 \endcode
 149
 150 */