Initial documentation for the performance characteristics of QPainter.

Reviewed-by: Tom

1 files changed, 78 insertions, 0 deletions

diff --git a/src/gui/painting/qpainter.cpp b/src/gui/painting/qpainter.cpp
index 66bf4f7..13d9a04 100644
--- a/src/gui/painting/qpainter.cpp
+++ b/src/gui/painting/qpainter.cpp
@@ -1317,6 +1317,84 @@ void QPainterPrivate::updateState(QPainterState *newState)
     Another workaround is to convert the paths to polygons first and then draw the
     polygons instead.
 
+    \section1 Performance
+
+    QPainter is a rich framework that allows developers to do a great
+    variety of graphical operations, such as gradients, composition
+    modes and vector graphcis. And QPainter can do this across a
+    variety of different hardware and software stack. Naturally the
+    underlying combination of hardware and software has some
+    implications for performance, and ensuring that every single
+    operation is fast in combination with all the various combinations
+    of composition modes, brushes, clipping, transformation, etc, is
+    close to an impossible task because of the number of
+    permutations. As a compromise we have selected a subset of the
+    QPainter API and backends, were performance is guaranteed to be as
+    good as we can sensibly get it for the given combination of
+    hardware and software.
+
+    The backends we focus on as high-performance engines are:
+
+    \list
+
+    \o Raster - This backend implements all rendering in pure software
+    and is always used to render into QImages. For optimal performance
+    only use the format types QImage::Format_ARGB32_Premultiplied,
+    QImage::Format_RGB32 or QImage::Format_RGB16. Any other format,
+    including QImage::Format_ARGB32, has significantly worse
+    performance. This engine is also used by default on Windows and on
+    QWS. It can be used as default graphics system on any
+    OS/hardware/software combination by passing \c {-graphcissystem
+    raster} on the command line
+
+    \o OpenGL 2.0 (ES) - This backend is the primary backend for
+    hardware accellerated graphics. It can be run on desktop machines
+    and embedded devices supporting the OpenGL 2.0 or OpenGL/ES 2.0
+    spesification. This includes most graphics chips produced in the
+    last couple of years. The engine can be enabled by using QPainter
+    onto a QGLWidget or by passing \c {-graphicssystem opengl} on the
+    command line when the underlying system supports it.
+
+    \endlist
+
+    These operations are:
+
+    \list
+
+    \o Simple transformations, meaning translation and scaling, pluss
+    0, 90, 180, 270 degree rotations.
+
+    \o \c drawPixmap() in combination with simple transformations and
+    opacity with non-smooth transformation mode
+    (\c QPainter::SmoothPixmapTransform not enabled as a render hint);
+
+    \o Text drawing with regular font sizes with simple
+    transformations with solid colors using no or 8-bit antialiasing.
+
+    \o Rectangle fills with solid color, two-color linear gradients
+    and simple transforms.
+
+    \o Rectangular clipping with simple transformations and intersect
+    clip.
+
+    \o Composition Modes \c QPainter::CompositionMode_Source and
+    QPainter::CompositionMode_SourceOver
+
+    \o Rounded rectangle filling using solid color and two-color
+    linear gradients fills.
+
+    \o 3x3 patched pixmaps, via qDrawBorderPixmap.
+
+    \endlist
+
+    This list gives an indication of which features to safely use in
+    an application where performance is critical. For certain setups,
+    other operations may be fast too, but before making extensive use
+    of them, it is recommended to benchmark and verify them on the
+    system where the software will run in the end. There are also
+    cases where expensive operations are ok to use, for instance when
+    the result is cached in a QPixmap.
+
     \sa QPaintDevice, QPaintEngine, {QtSvg Module}, {Basic Drawing Example},
         {Drawing Utility Functions}
 */