Documentation: Embedded hardware acceleration

Adding docs on how to use hardware acceleration on Embedded Linux and Windows CE

Task-number: QT-1109

Rev-by: Anders Bakken

Rev-by: Rhys Weatherley

Rev-by: Thomas Hartmann

14 files changed, 1299 insertions, 44 deletions

diff --git a/doc/src/images/platformHWAcc.png b/doc/src/images/platformHWAcc.png
new file mode 100644
index 0000000..76a5a48
--- /dev/null
+++ b/doc/src/images/platformHWAcc.png
diff --git a/doc/src/modules.qdoc b/doc/src/modules.qdoc
index ea5a9dc..ac264d0 100644
--- a/doc/src/modules.qdoc
+++ b/doc/src/modules.qdoc
@@ -226,10 +226,11 @@
 
     The QtOpenGL module is part of the \l{Qt Full Framework Edition} and the
     \l{Open Source Versions of Qt}. It is available on Windows, X11, and Mac OS X.
-    \l{Qt for Embedded Linux} supports OpenGL ES (OpenGL for Embedded Systems).
-    To be able to use the OpenGL API in \l{Qt for Embedded Linux}, it must be
+    \l{Qt for Embedded and OpenGL} supports OpenGL ES (OpenGL for Embedded Systems).
+    \note To be able to use the OpenGL API in \l{Qt for Embedded Linux}, it must be
     integrated with the Q Window System (QWS). See the
     \l{Qt for Embedded Linux and OpenGL} documentation for details.
+
 */
 
 /*!
diff --git a/doc/src/platforms/emb-HwAcc-LinuxEmbedded.qdoc b/doc/src/platforms/emb-HwAcc-LinuxEmbedded.qdoc
new file mode 100644
index 0000000..9c18d87
--- /dev/null
+++ b/doc/src/platforms/emb-HwAcc-LinuxEmbedded.qdoc
@@ -0,0 +1,71 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+
+    \page qt-embeddedLinux-accel.html
+
+    \target Hardware Acceleration with Qt for Embedded Linux
+
+    \title Qt for Embedded Linux Hardware Accelerated Graphics
+    \ingroup qt-embedded-linux
+
+
+  \input platforms/emb-hardwareacceleration.qdocinc
+
+\section1 Supported Hardware Accelerated Graphics APIs
+
+This list shows which Hardware Accelerated Graphics APIs currently
+supported by Qt.
+
+ \table 
+ \header
+	\o Supported Hardware Accelerated Graphics APIs
+ \row
+    \o \l {Qt for Embedded Linux and OpenGL}{OpenGL ES}
+ \row
+    \o \l {Qt for Embedded Linux and OpenVG}{OpenVG} 
+ \row
+    \o \l {Qt for Embedded Linux and DirectFB}{DirectFB}
+ \endtable 
+
+
+*/
diff --git a/doc/src/platforms/emb-HwAcc-WinCE.qdoc b/doc/src/platforms/emb-HwAcc-WinCE.qdoc
new file mode 100644
index 0000000..66b6948
--- /dev/null
+++ b/doc/src/platforms/emb-HwAcc-WinCE.qdoc
@@ -0,0 +1,69 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qt-embeddedWinCE-accel.html
+
+    \target Hardware Acceleration with Qt for Windows CE
+
+    \title Qt for Windows CE Hardware Accelerated Graphics
+    \ingroup qtce
+
+
+    \input platforms/emb-hardwareacceleration.qdocinc
+
+    \section1 Supported Hardware Accelerated Graphics APIs
+
+    This list shows which Hardware Accelerated Graphics APIs currently
+supported by Qt.
+
+ \table
+    \header
+        \o Supported Hardware Accelerated Graphics APIs
+    \row
+        \o \l {Qt for Windows CE and OpenGL ES}{OpenGL ES}
+    \row
+        \o \l {Qt for Windows CE and OpenVG}{OpenVG} 
+ \endtable
+
+
+
+*/
diff --git a/doc/src/platforms/emb-directfb-EmbLinux.qdoc b/doc/src/platforms/emb-directfb-EmbLinux.qdoc
new file mode 100644
index 0000000..b863951
--- /dev/null
+++ b/doc/src/platforms/emb-directfb-EmbLinux.qdoc
@@ -0,0 +1,340 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qt-embeddedLinux-directfb.html
+
+\title Qt for Embedded Linux and DirectFB
+
+\ingroup qt-embedded-linux
+
+\section1 Introduction
+
+DirectFB is an open source LGPL licensed project founded by Denis Oliver Kropp
+and generally chip vendors start out with the official version and
+implement their own plugins to optimize the operations their hardware
+supports.
+
+We recommend using Qt 4.6 with DirectFB. DirectFB support was introduced
+already into Qt for Embedded Linux as a labs project for Qt 4.3 and folded
+into Qt as a screen driver for Qt 4.4, but not supported fully. In Qt 4.5,
+major changes were made to make it work with the optimized raster paint
+engine. And in Qt 4.6 these have been further improved.
+
+\tableofcontents
+
+\section1 Using DirectFB with Qt
+DirectFB is centered around \l
+{http://www.directfb.org/docs/DirectFB_Reference_1_4/IDirectFBSurface.html}{Surfaces}
+which is the equivalent of a QPaintDevice. In the Qt/DirectFB plugin,
+DirectFB maps onto either a QPixmap or a QWindowSurface which essentially
+means that drawing onto QPixmap or a QWidget can be accelerated and drawing
+onto any other paint device (e.g. QImage) cannot.
+
+\section2 Configure
+
+When configuring Qt there are two options, from which you can choose:
+
+\code
+    ./configure -plugin-gfx-directfb 
+    ./configure -qt-gfx-directfb 
+
+\endcode
+
+With either mode, Qt will try the following to look for the DirectFB
+includes/libs.
+
+\list
+    \o Use pkg-config
+    \o Use directfb-config
+    \o Check in your qmake.conf
+\endlist
+
+Often the values returned from pkg-config/directfb-config indicates the
+locations of the libs/headers on the target rootfs, rather than their
+location on your host. The safest option is usually to explicitly populate
+these variables in your qmake.conf like this:
+
+\code
+
+QT_CFLAGS_DIRECTFB =
+/opt/toolchain/gcc4.3_mipsel_linux/usr/include/directfb -D_REENTRANT
+QT_LIBS_DIRECTFB = -L/opt/toolchain/gcc4.3_mipsel_linux/usr/lib/-ldirect
+-ldirectfb -lfusion
+
+\note While DirectFB supports a multi-process setup through a
+kernel-extension called Fusion this setup is not well tested with Qt.
+
+\section2 Supported graphics operations
+
+IDirectFBSurface supports blitting, filling, drawing lines rects etc, but
+it does not support everything Qt allows you to do. E.g. painter paths,
+polygons, complex transformations, antialiasing, gradients. Some of these
+things are handled in newer versions of DirectFB and could be supported by
+Qt. They are seemingly optional at the driver level, so you need to have
+fall back code paths for older drivers and drivers on which this is not
+implemented.
+
+The QDirectFBPaintEngine is a subclass of the QRasterPaintEngine, thus
+essentially supporting everything QRasterPaintEngine supports. This means
+that it supports all graphical operations that Qt supports, but certain
+operations will have to fall back to software rendering and that should be
+avoided due to performance issues. Instead, these operations should be
+rendered into a QPixmap once, and then reuse the pixmap.
+
+Note: Fallbacks to software rendering should be avoided. If unsupported
+operations are used, the paint engine must fallback to the
+QRasterPaintEngine engine. A good debugging tip is to make Qt warn you when
+such fall backs occur, and to disable the fall back and only return.
+Debugging options are listed below.
+
+\section2 DirectFB driver
+DirectFB also provides an abstraction for keyboard and mouse drivers. This
+simplifies the process of getting the target hardware up and running. It
+also brings us to a feature fragmentation issue between different versions
+of DirectFB.
+
+The Qt DirectFB driver currently supports DirectFB versions >= 0.9. Still,
+there are large differences in what each actual implementation handles
+correctly. It is relatively common not to properly support
+\l{http://www.directfb.org/docs/DirectFB_Reference_1_4/IDirectFBWindow}{DirectFB
+windows}, so Qt needs to handle this case with a different code path. In
+addition, certain drivers do not properly support DirectFB's cursor
+handling. This means Qt has to have a code path for rendering the cursor
+itself when this is the case. Some drivers do not let us create \l
+{http://www.directfb.org/docs/DirectFB_Reference_1_4/types.html#DFBSurfaceDescription}{preallocated
+surfaces} which means we have to have a conditional code path for that
+case. 
+
+\section2 Optimize performance using define options
+
+Qt/DirectFB comes with a number of defines that can be either
+uncommented in directfb.pri or added to the QT_DEFINES_DIRECTFB variable in
+your qmake.conf.
+
+\note The defines have been moved from \i
+{src/plugins/gfxdrivers/directfb/directfb.pro} to \i
+{src/gui/embedded/directfb.pri}
+
+\code
+
+#DIRECTFB_DRAWINGOPERATIONS=DRAW_RECTS|DRAW_LINES|DRAW_IMAGE|DRAW_PIXMAP|
+    DRAW_TILED_PIXMAP|STROKE_PATH|DRAW_PATH|DRAW_POINTS|DRAW_ELLIPSE|DRAW_POLYGON|
+    DRAW_TEXT|FILL_PATH|FILL_RECT|DRAW_COLORSPANS|DRAW_ROUNDED_RECT
+
+ #DEFINES += \"QT_DIRECTFB_WARN_ON_RASTERFALLBACKS=$$DIRECTFB_DRAWINGOPERATIONS\"
+ #DEFINES += \"QT_DIRECTFB_DISABLE_RASTERFALLBACKS=$$DIRECTFB_DRAWINGOPERATIONS\"
+ 
+\endcode
+
+As demonstrated above, you need to Qt which drawing operations you want to
+warn/disable. Since there are varying implementations of DirectFB from
+manufacturer to manufacture, different operations will be optimized. This
+require you to define the operations you want to warn about or disable.
+These are listed above in the DIRECTFB_DRAWINGOPERATIONS variable.
+
+Following is a table showing which options you have.
+
+\table
+    \header
+        \o Define option
+        \o Description
+    \row
+        \o QT_DIRECTFB_IMAGECACHE
+        \o Defining this means that Qt will cache an IDirectFBSurface per
+QImage you draw based on its \l
+{http://doc.trolltech.com/4.5/qimage.html#cacheKey}{cacheKey}.
+Use this define if your application draws many QImages that
+remain the same. Note that if you in this situation draw an image and then
+change it, by calling bits() or opening a QPainter on it, the cache will
+not benefit you. You can control the cache size with the imageCacheSize
+connect option.
+
+    \row
+        \o QT_NO_DIRECTFB_WM
+        \o If your DirectFB implementation does not support windows, you
+have to define this to make Qt work properly. You can test this by checking
+if the \l {
+http://www.directfb.org/index.php?path=Main%2FDownloads&page=1}{df_window
+example} runs well.
+This means that all drawing operations onto a QWidget involves
+an extra blitting step since Qt essentially first has to draw into an
+off-screen buffer and then blit this buffer to the back buffer of the
+primary surface. Finally, Qt must flip the back buffer to the front buffer,
+which usually involves another blit. Still, blits are usually very fast
+with DirectFB.
+
+To work around this you can make your widget paint on screen, \l
+Qt::WA_PaintOnScreen but this comes with other limitations. This should be
+avoided if you want more than one full-screen window in your application.
+In addition, it will not work without proper DirectFB mouse support from the
+layer. Also, see QT_NO_DIRECTFB_LAYER for more.
+
+    \row
+        \o QT_NO_DIRECTFB_LAYER
+        \o If your DirectFB display layer cannot be used for e.g. drawing
+mouse cursor, creating windows you have to define this. Defining this also
+requires defining QT_NO_DIRECTFB_WM and involves making Qt render the
+cursor rather than letting DirectFB do it.
+
+    \row
+        \o QT_NO_DIRECTFB_PALETTE
+        \o Define this if your DirectFB driver does not support surfaces
+with \l
+{http://www.directfb.org/docs/DirectFB_Reference_1_4/IDirectFBPalette.html}{color
+tables}.
+The effect of defining this is that Qt will have to convert
+images with \l QImage::Format_Indexed8 format to another format before
+rendering them.
+
+    \row
+        \o QT_NO_DIRECTFB_PREALLOCATED
+        \o Define this if your DirectFB driver does not support creating a
+surface with preallocated data. This will make a more frequent use of \l
+{http://www.cplusplus.com/reference/clibrary/cstring/memcpy/}{memcpy()}
+when drawing images. If you define this, you might want to consider
+defining QT_DIRECTFB_IMAGECACHE for better image rendering performance.
+
+    \row
+        \o QT_NO_DIRECTFB_MOUSE and QT_NO_DIRECTFB_KEYBOARD
+        \o Define this if your driver does not provide keyboard/mouse
+events through \l
+{http://www.directfb.org/docs/DirectFB_Reference_1_4/IDirectFB_CreateInputEventBuffer.html}{CreateInputEventBuffer}.
+This means that Qt cannot use DirectFB to receive keyboard/mouse events and
+if you want such events in your application, you will have to provide
+another driver. For more info see \l {Qt for Embedded Linux Pointer
+Handling}{Qt for Embedded Linux Pointer Handling} and \l{Qt for Embedded
+Linux Character Input}{Qt for Embedded Linux Character Input}
+
+    \row
+        \o QT_DIRECTFB_TIMING
+        \o Define this when debugging to get output on stderr about the
+frames per second.
+
+    \row
+        \o QT_NO_DIRECTFB_OPAQUE_DETECTION
+        \o When blitting a surface Qt has to decide whether to set the \l
+{http://www.directfb.org/docs/DirectFB_Reference_1_4/types.html#DFBSurfaceBlittingFlags}{DSBLIT_BLEND_ALPHACHANNEL}
+flag. If you load an image from file or network data that has a format that
+includes an alpha channel, the image might still be completely opaque.
+Normally Qt runs through every pixel to check if there really is an alpha
+channel there. This involves some overhead but usually pays off in the end
+because blitting is cheaper than blending. If you define this Qt will
+assume that an image with a format that has alpha channel contains at least
+one pixel with an alpha value != 255.
+
+ \row
+    \o QT_DIRECTFB_SUBSURFACE
+    \o Defining this enables a mode that tries to minimize overhead from
+locking/unlocking surfaces. Note that this currently is experimental.
+
+ \row
+    \o QT_DIRECTFB_WINDOW_AS_CURSOR
+    \o Define this if your DirectFB implementation supports windows but
+can not render the cursor properly. This involves creating a small top level
+window and moving it around when the cursor moves. It does not always
+perform well.
+
+ \row
+    \o QT_NO_DIRECTFB_IMAGEPROVIDER
+    \o By default Qt will use DirectFB to load QPixmaps from disk/memory. If
+your DirectFB implementation does not support this it might make sense to
+define this.
+
+ \row
+    \o QT_DIRECTFB_IMAGEPROVIDER_KEEPALIVE
+    \o Define this to make sure Qt always keeps at least one \l
+{http://directfb.org/docs/DirectFB_Reference_1_4/IDirectFBImageProvider.html}{IDirectFBImageProvider}
+object alive. This is to avoid considerable overhead when the first
+IDirectFBImageProvider is created, the last IDirectFBImageProvider is
+removed.
+
+\endtable
+
+\section2 Unsupported graphics operations
+
+There are a number of unsupported operations causing fallbacks. DirectFB
+does not support the following functions.
+
+
+
+\table
+ \header
+  \o Functions
+ \row
+  \o QPainter::strokePath(const QPainterPath & path, const QPen & pen)
+ \row
+  \o QPainter::drawPath(const QPainterPath & path)
+ \row
+  \o QPainter::fillPath(const QPainterPath & path, const QBrush & brush)
+ \row
+  \o QPainter::drawPoints(const QPointF * points, int pointCount)
+ \row
+  \o QPainter::drawEllipse(const QRectF & rectangle)
+ \row
+  \o QPainter::drawPolygon(const QPointF * points, int pointCount,
+ Qt::FillRule fillRule = Qt::OddEvenFill)
+ \row
+  \o QPainter::drawText(const QPointF & position, const QString & text)
+ \row
+  \o QGradient
+ \endtable
+
+\section2 Avoiding fallbacks
+To avoid fallbacks make sure that the following points are true:
+
+\list
+    \o QPen::isSolid() returns true and uses a color with a one pixel
+width. (QPen::width() returns 1.
+    \o QTransform::TransformationType() <= QTransform::TxScale are not
+supported.
+    \o Clipping must be a simple rectangle or a QRegion.
+\endlist
+
+\section2 When painting images
+\note You should use QPixmap instead of QImage. QImages are drawn by
+the QRasterPaintEngine. To get a warning for every fallback to the
+QRasterPaintEngine, use QT_DIRECTFB_WARN_ON_RASTERFALLBACKS. If
+QT_DIRECTFB_DISABLE_RASTERFALLBACKS is defined, DirectFB will only return
+instead of falling back to QRasterPaintEngine. Please note that these
+defines should only be used when optimizing the application. 
+
+*/
diff --git a/doc/src/platforms/emb-hardwareacceleration.qdocinc b/doc/src/platforms/emb-hardwareacceleration.qdocinc
new file mode 100644
index 0000000..3851628
--- /dev/null
+++ b/doc/src/platforms/emb-hardwareacceleration.qdocinc
@@ -0,0 +1,129 @@
+
+\section1 Hardware Acceleration
+
+When designing applications for embedded devices the choice often stands
+between graphics effects and performance. On most devices, you cannot have
+both simply because the hardware needed for such operations just is not
+there. Still a growing number of devices use hardware dedicated to graphics
+operations to improve performance. 
+
+Using graphics acceleration hardware is more power efficient than using the
+CPU. The reason for this is that the CPU might require a clock speed that
+is up to 20 times higher than the GPU, achieving the same results. E.g. a
+typical hardware accelerated mobile graphics unit can rasterize one or two
+bilinear texture fetches in one cycle, while a software implementation
+takes easily more than 20 cycles. Graphics hardware generally have a much
+lower clock speed and memory bandwidth and different level of acceleration
+than desktop GPUs. One example is that many GPUs leave out transformation
+and lighting from the graphics pipeline and only implements rasterization.
+
+So the key to write good applications for devices is therefore to limit the
+wow factor down to what the target hardware can handle, and to take
+advantage of any graphics dedicated hardware. Qt provides several ways to
+both render advanced effects on the screen and speed up your application
+using hardware accelerated graphics.
+
+\tableofcontents 
+
+\section2 Qt for Embedded Graphics pipeline
+
+Qt uses QPainter for all graphics operations. By using the same API
+regardless of platform, the code can be reused on different devices.
+QPainter use different paint engines implemented in the QPaintEngine API to
+do the actual painting.
+
+The QPaintEngine API provides paint engines for each window system and
+painting framework supported by Qt. In regards to Qt for Embedded, this
+also includes implementations for OpenGL ES versions 1.1 and 2.0, as well
+as OpenVG and DirectFB(Embedded Linux only).
+
+By using one of these paint engines, you will be able to improve the
+graphics performance of your Qt application. However, if the graphics
+operations used are not supported, this might as well be a trap, slowing
+down your application significantly. This all depends on what kind of
+graphics operations that are supported by the target devices hardware
+configuration.
+
+\image platformHWAcc.png
+
+The paint engine will direct all graphics operations supported by the
+devices hardware to the GPU, and from there they are sent to the
+framebuffer. Unsupported graphics operations falls back to the
+QRasterPaintEngine and are handled by the CPU before sent to the
+framebuffer. In the end, the operating system sends the paint updates off
+to the screen/display. The fallback operation is quite expensive in regards
+to memory consumption, and should be avoided.
+
+\section2 Hardware configuration requirements
+
+Before implementing any application using hardware acceleration, it is wise
+to get an overview of what kind of hardware accelerated graphics operations
+that are available for the target device. 
+
+\note On devices with no hardware acceleration, Qt will use
+QRasterPaintEngine, which handles the acceleration using software. On
+devices supporting OpenGL ES, OpenVG or DirectFB(not supported by Windows
+CE), Qt will use the
+respective paint engines to accelerate painting. However, hardware
+configurations that only support a limited set of hardware acceleration
+features, might slow the application graphics down rather than speeding it
+up when using unsupported operations that must fall back to the raster
+engine.
+
+\section3 Different architectures
+
+Based on the architecture used in a device we can make a recommendation on
+which hardware acceleration techniques to use. There are mainly two
+different architectures on embedded devices. These are devices with a
+Unified Memory Architecture (UMA), and devices with dedicated graphics
+memory. Generally, high-end devices will have dedicated graphics memory.
+Low-end devices will just use system memory, sometimes reserving a memory
+region and sometimes not.
+
+In addition to this, we can categorize the devices into five types based on
+the different graphics operations supported by their hardware.
+
+\list 1
+    \o No support for graphics acceleration.
+    \o Support for blitter and alpha blending.
+    \o Support for path based 2D vector graphics.
+    \o Support for fixed function 3D graphics.
+    \o Support for programmable 3D graphics.
+\endlist
+
+Based on these characteristics the table below recommends which paint
+engines to use with the different types of hardware configurations.
+
+\section3 Recommended use of hardware acceleration based on hardware
+
+ \table
+     \header
+         \o Type
+         \o UMA
+         \o Non-UMA
+     \row
+         \o \bold {None}
+         \o Qt Raster Engine
+         \o Qt Raster Engine
+     \row
+         \o \bold {Blitter}
+         \o DirectFB
+         \o DirectFB
+     \row
+         \o \bold {2D Vector}
+         \o OpenVG
+         \o OpenVG
+     \row
+         \o \bold {Fixed 3D}
+         \o OpenGL (ES) 1.x
+         \o OpenGL (ES) 1.x
+     \row
+         \o \bold {Programmable 3D}
+         \o OpenGL (ES) 2.x
+         \o OpenGL (ES) 2.x
+
+ \endtable
+
+\note Since the DirectFB API is quite primitive, the raster paint engine
+handles most of the operations.
+\note Blitter and Alpha blending is currently not supported on Windows CE.
diff --git a/doc/src/platforms/emb-opengl-EmbLinux.qdoc b/doc/src/platforms/emb-opengl-EmbLinux.qdoc
new file mode 100644
index 0000000..bede2ca
--- /dev/null
+++ b/doc/src/platforms/emb-opengl-EmbLinux.qdoc
@@ -0,0 +1,164 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qt-embeddedLinux-opengl.html
+
+\title Qt for Embedded Linux and OpenGL
+
+\ingroup qt-embedded-linux
+
+\input platforms/emb-opengl.qdocinc
+
+\section1 Using OpenGL with Qt for Embedded Linux
+Qt for Embedded Linux provides support for integrating OpenGL ES for
+drawing into a QGLWidget. The current implementation supports OpenGL and 2D
+painting within a QGLWidget. Using OpenGL to accelerate regular widgets and
+compositing top-level windows with OpenGL are not currently supported.
+
+\note OpenGL rendering only works with QGLWidget under QWS.  Regular
+widgets cannot currently support it.
+
+\section2 Configure
+
+It is recommended that Qt for Embedded Linux is configured with the
+\c{-DQT_QWS_CLIENTBLIT} and \c{-DQT_NO_QWS_CURSOR} options for optimum
+performance.  OpenGL is rendered direct to the screen and these options
+prevent Qt for Embedded Linux from trying to do its own non-OpenGL
+compositing on the QGLWidget contents.
+
+\section2 Using OpenGL to Implement Window Compositing and Effects
+
+Compositing effects can be simulated by adjusting the opacity and other
+parameters of the items within a QGraphicsView canvas on a QGLWidget
+viewport.
+
+While Qt for Embedded Linux does include a complete windowing system,
+using OpenGL to composite regular window surfaces can be quite difficult.
+Most of Qt for Embedded Linux assumes that the window surface is a plain
+raster memory buffer, with QGLWidget being the sole exception.
+The need to constantly re-upload the raster memory buffers into OpenGL
+textures for compositing can have a significant impact on performance,
+which is why we do not recommend implementing that form of compositing.
+We intend to address this problem in future versions of Qt.
+
+\section1 Integrating OpenGL/ES into Qt for Embedded Linux
+\section2 Reference Integration
+The reference integration for OpenGL into Qt for Embedded Linux is for the
+PowerVR chipset from \l{http://www.imgtec.com/}{Imagination Technologies}.
+It consists of two components: \c{pvreglscreen}, which provides the Qt for
+Embedded Linux screen driver, and \c{QWSWSEGL}, which implements a plug-in
+to the PowerVR EGL implementation to implement low-level OpenGL drawing
+surfaces.
+
+\section2 Integrating Other Chipsets
+In this section, we discuss the essential features of the reference
+integration that need to be provided for any other chipset integration.
+
+The QtOpenGL module assumes that a QGLWidget can be represented
+by an \c EGLNativeWindowType value in some underlying window system
+implementation, and that \c{eglSwapBuffers()} is sufficient to copy
+the contents of the native window to the screen when requested.
+
+However, many EGL implementations do not have a pre-existing window system.
+Usually only a single full-screen window is provided, and everything else
+must be simulated some other way.  This can be a problem because
+of QtOpenGL's assumptions.  We intend to address these assumptions in a
+future version of Qt, but for now, it is the responsibility of the integrator
+to provide a rudimentary window system within the EGL implementation.
+This is the purpose of \c{QWSWSEGL} in the reference integration.
+
+If it isn't possible for the EGL implementation to provide a rudimentary
+window system, then full-screen windows using QGLWidget can be supported,
+but very little else.
+
+The screen driver needs to inherit from QGLScreen and perform the
+following operations in its constructor:
+
+\snippet src/plugins/gfxdrivers/powervr/pvreglscreen/pvreglscreen.cpp 0
+
+The \c{setSurfaceFunctions()} call supplies an object that takes care
+of converting Qt paint devices such as widgets and pixmaps into
+\c EGLNativeWindowType and \c EGLNativePixmapType values.  Here we
+only support native windows.  Because OpenGL rendering is direct to
+the screen, we also indicate that client blit is supported.
+
+Next, we override the \c{createSurface()} functions in QGLScreen:
+
+\snippet src/plugins/gfxdrivers/powervr/pvreglscreen/pvreglscreen.cpp 1
+
+Even if Qt for Embedded Linux is used in single-process mode, it is
+necessary to create both client-side and server-side versions of the
+window surface.  In our case, the server-side is just a stub because
+the client side directly renders to the screen.
+
+Note that we only create a \c{PvrEglWindowSurface} if the widget is a
+QGLWidget.  All other widgets use the normal raster processing.
+It can be tempting to make \c{createSurface()} create an OpenGL
+window surface for other widget types as well.  This has not been
+extensively tested and we do not recommend its use at this time.
+
+The other main piece is the creation of the \c EGLNativeWindowType
+value for the widget.  This is done in the \c{createNativeWindow()}
+override:
+
+\snippet src/plugins/gfxdrivers/powervr/pvreglscreen/pvreglscreen.cpp 2
+
+The details of what needs to be placed in this function will vary
+from chipset to chipset.  The simplest is to return the native window
+handle corresponding to the "root" full-screen window:
+
+\code
+*native = rootWindowHandle;
+return true;
+\endcode
+
+The most common value for \c rootWindowHandle is zero, but this may
+not always be the case.  Consult the chipset documentation for the
+actual value to use.  The important thing is that whatever value is
+returned must be suitable for passing to the \c{eglCreateWindowSurface()}
+function of the chipset's EGL implementation.
+
+In the case of PowerVR, the rudimentary window system in \c{QWSWSEGL}
+provides a \c PvrQwsDrawable object to represent the \c EGLNativeWindowType
+value for the widget.
+
+*/
diff --git a/doc/src/platforms/emb-opengl.qdocinc b/doc/src/platforms/emb-opengl.qdocinc
new file mode 100644
index 0000000..dac5379
--- /dev/null
+++ b/doc/src/platforms/emb-opengl.qdocinc
@@ -0,0 +1,85 @@
+\section1 Introduction
+
+\l {http://www.opengl.org}{OpenGL} is an industry standard API for
+2D/3D graphics. It provides a powerful, low-level interface between
+software and acceleration hardware, and it is operating system and
+window system independent. \l {http://www.khronos.org/opengles}{OpenGL ES}
+is a subset of the \l {http://www.opengl.org}{OpenGL} standard. Because it
+is designed for use with embedded systems, it has a smaller, more
+constrained API.
+
+\l {http://www.khronos.org/opengles/1_X}{OpenGL ES version 1.x} is designed for
+fixed function hardware, while its successor \l
+{http://www.khronos.org/opengles/2_X}{OpenGL ES version 2.x} is designed for
+programmable hardware. It is worth noting that there is a significant
+difference between the two, and that they are not compatible with each
+other. OpenGL ES 1.x limits processing to a pre-defined set of fixed
+options for drawing and lighting objects. OpenGL 2.x has a significantly
+shorter graphics pipeline than 1.x. Instead of using function
+transformation and a fragment pipeline, 2.x uses the \l
+{http://www.khronos.org/registry/gles/specs/2.0/GLSL_ES_Specification_1.0.17.pdf}{OpenGL
+ES Shading Language (GLSL ES)}. Instead of using the pre-defined functions,
+the programmer writes small shader programs telling the hardware in detail
+how to render each object.
+
+The \l {QtOpenGL module} offers classes that make it easy to draw 3D
+graphics in GUI applications using OpenGL ES. Qt provides a plugin that
+integrates both OpenGL ES versions \l
+{http://www.khronos.org/opengles/1_X}{1.x} and \l
+{http://www.khronos.org/opengles/2_X}{2.x} with Qt for Embedded. However,
+Qt for Embedded can be adapted to a wide range of OpenGL versions.
+
+To translate QPainter operations into OpenGL ES calls (there are actually
+two subclasses, one for OpenGL/ES 1.1 and another for OpenGL/ES 2.0), Qt
+uses a subclass of QPaintEngine.  This specialized paint engine can be used
+to improve 2D rendering performance on appropriate hardware.  It can also
+overlay controls and decorations onto 3D scenes drawn using OpenGL. 
+
+\tableofcontents 
+
+\section1 Using OpenGL ES with Qt
+To use OpenGL-enabled widgets in a Qt for Embedded application, all that is
+required is to subclass QGLWidget and draw into instances of the subclass
+with standard OpenGL functions. The current implementation only
+supports OpenGL ES and 2D painting within a QGLWidget. Using OpenGL ES to
+accelerate regular widgets as well as compositing top-level windows with
+OpenGL ES are not currently supported. These issues will be addressed in
+future versions of Qt.
+
+\note The OpenGL paint engine is not currently supported in regular
+widgets. However, any application that uses QGraphicsView can set a
+QGLWidget as the viewport and obtain access to the OpenGL paint engine that
+way:
+
+\code
+    QGraphicsView view(&scene);
+    view.setViewport(new QGLWidget());
+    view.setHorizontalScrollBarPolicy(Qt::ScrollBarAlwaysOff);
+    view.setVerticalScrollBarPolicy(Qt::ScrollBarAlwaysOff);
+    view.setViewportUpdateMode(QGraphicsView::FullViewportUpdate);
+    view.setFrameStyle(0);
+    view.showFullScreen();
+\endcode
+
+It is recommended that the QGraphicsView::FullViewportUpdate flag
+be set because the default double-buffered behavior of QGLWidget
+does not support partial updates. It is also recommended that the
+window be shown full-screen because that usually has the best
+performance on current OpenGL ES implementations.
+
+Once a QGraphicsView has been initialized as above, regular widgets
+can be added to the canvas using QGraphicsProxyWidget if the
+application requires them.
+
+\note OpenGL ES 2.X does not support PBuffers, so QGLPixelBuffer will not
+work. In this case, QGLFramebufferObject should be used instead. However,
+OpenGL ES 1.X does not support Framebuffer objects, with the exception of
+some OpenGL ES 1.X extensions. In this case, please use QGLPixelBuffer. 
+
+\note On most embedded hardware, the OpenGL implementation is
+actually \l{http://www.khronos.org/opengles/1_X/}{OpenGL/ES 1.1} or
+\l{http://www.khronos.org/opengles/2_X/}{OpenGL/ES 2.0}.  When painting
+within a QGLWidget::paintGL() override, it is necessary to limit the
+application to only the features that are present in the OpenGL/ES
+implementation.
+
diff --git a/doc/src/platforms/emb-openvg-EmbLinux.qdoc b/doc/src/platforms/emb-openvg-EmbLinux.qdoc
new file mode 100644
index 0000000..abdb617
--- /dev/null
+++ b/doc/src/platforms/emb-openvg-EmbLinux.qdoc
@@ -0,0 +1,53 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qt-embeddedLinux-openvg.html
+
+\title Qt for Embedded Linux and OpenVG
+
+\ingroup qt-embedded-linux
+
+\input platforms/emb-openvg.qdocinc
+
+
+
+*/
diff --git a/doc/src/platforms/emb-openvg.qdocinc b/doc/src/platforms/emb-openvg.qdocinc
new file mode 100644
index 0000000..37ccb9c
--- /dev/null
+++ b/doc/src/platforms/emb-openvg.qdocinc
@@ -0,0 +1,288 @@
+\section1 Introduction
+
+\l {http://www.khronos.org/openvg}{OpenVG} is a standard API from the
+\l{http://www.khronos.org/openvg}{Khronos Group} for accelerated 2D vector
+graphics and raster graphics. It is a dedicated API for 2D graphics on
+mobile devices. It is therefore more likely to be a better alternative for
+2D acceleration than OpenGL/ES. 
+
+\tableofcontents
+
+\section1 Using OpenVG with Qt
+The QtOpenVG plugin provides support for OpenVG painting. OpenVG is
+optimized for 2D vector operations, and closely matches the functionality
+in QPainter. To translate QPainter operations into OpenVG calls, Qt uses a
+subclass of QPaintEngine. Unlike with OpenGL ES, OpenVG can be used for
+acceleration of regular widgets. It can therefore be an excellent substitute
+for the default raster-based QPaintEngine on hardware that supports the
+OpenVG API.
+
+\section2 Configure
+OpenVG support can be enabled by passing the \c{-openvg} option to
+configure.  It is assumed that the following qmake variables are set to
+appropriate values in the qmake.conf file for your platform:
+
+    \list
+    \o QMAKE_INCDIR_OPENVG
+    \o QMAKE_LIBDIR_OPENVG
+    \o QMAKE_LIBS_OPENVG
+    \endlist
+
+Most OpenVG implementations are based on EGL, so the following variables
+may also need to be set:
+
+    \list
+    \o QMAKE_INCDIR_EGL
+    \o QMAKE_LIBDIR_EGL
+    \o QMAKE_LIBS_EGL
+    \endlist
+
+See \l{qmake Variable Reference} for more information on these variables.
+
+\section2 Supported OpenVG Engines
+
+Two kinds of OpenVG engines are currently supported: EGL based, and engines
+built on top of OpenGL such as
+\l{http://sourceforge.net/projects/shivavg}{ShivaVG}. EGL based engines are
+preferred.
+
+It is assumed that the EGL implementation has some way to turn a
+QWidget::winId() into an EGL rendering surface with
+\c{eglCreateWindowSurface()}.  If this is not the case, then modifications
+may be needed to the code under \c{src/gui/egl} and
+\c{src/plugins/graphicssystems/openvg} to accomodate the EGL
+implementation.
+
+The ShivaVG graphics system under \c{src/plugins/graphicssystems/shivavg}
+is an example of how to integrate a non-EGL implementation of OpenVG into
+Qt. It is currently only supported with Qt/X11 and being an example only,
+the resulting screen output may not be as good as with other OpenVG
+engines.
+
+\section1 Using the OpenVG graphics system
+
+Once the graphics system plugin has been built and installed, applications
+can be run as follows to use the plugin:
+
+    \code
+    app -graphicssystem OpenVG
+    \endcode
+
+If ShivaVG is being used, then substitute \c ShivaVG instead of \c OpenVG
+in the line above.
+
+If the plugin fails to load, try setting the \c QT_DEBUG_PLUGINS
+environment variable to 1 and try again.  Usually the plugin cannot be
+loaded because Qt cannot locate it in the directory
+\c{plugins/graphicssystems} within the Qt installation, or the dynamic
+library path does not include the directory containing the system's \c
+libOpenVG.so library.
+
+\section2 Supported features
+
+\table
+    \header
+        \o Feature
+        \o Description
+
+    \row
+        \o Context modes
+        \o The default configuration is "single-context" mode, where a single
+EGLContext object is used for all drawing, regardless of the surface.
+Multiple EGLSurfaces are created, one for each window surface or pixmap.
+eglMakeCurrent() is called with the same EGLContext every time, but a
+different EGLSurface.
+
+Single-context mode is necessary for QPixmapData to be implemented in terms
+of a VGImage. If single-context mode is not enabled, then QPixmapData will
+use the fallback QRasterPixmapData implementation, which is less efficient
+performance-wise.
+
+Single-context mode can be disabled with the QVG_NO_SINGLE_CONTEXT
+define if the OpenVG engine does not support one context with multiple
+surfaces.
+
+    \row
+        \o Transformation matrices
+        \o All affine and projective transformation matrices are supported.
+
+QVGPaintEngine will use the engine to accelerate affine transformation
+matrices only. When a projective transformation matrix is used,
+QVGPaintEngine will transform the coordinates before passing them to the
+engine. This will probably incur a performance penalty.
+
+Pixmaps and images are always transformed by the engine, because OpenVG
+specifies that projective transformations must work for images.
+
+It is recommended that client applications should avoid using projective
+transformations for non-image elements in performance critical code.
+
+    \row
+        \o Composition modes
+        \o The following composition modes are supported:
+
+\list
+\o QPainter::CompositionMode_SourceOver
+\o QPainter::CompositionMode_DestinationOver
+\o QPainter::CompositionMode_Source
+\o QPainter::CompositionMode_SourceIn
+\o QPainter::CompositionMode_DestinationIn
+\o QPainter::CompositionMode_Plus
+\o QPainter::CompositionMode_Multiply
+\o QPainter::CompositionMode_Screen
+\o QPainter::CompositionMode_Darken
+\o QPainter::CompositionMode_Lighten
+\endlist
+
+The other members of QPainter::CompositionMode are not supported
+because OpenVG 1.1 does not have an equivalent in its \c VGBlendMode
+enumeration.  Any attempt to set an unsupported mode will result in
+the actual mode being set to QPainter::CompositionMode_SourceOver.
+Client applications should avoid using unsupported modes.
+
+    \row
+        \o Pens and brushes
+        \o All pen styles are supported, including cosmetic pens.
+
+All brush styles are supported except for conical gradients, which are not
+supported by OpenVG 1.1.  Conical gradients will be converted into a solid
+color brush corresponding to the first color in the gradient's color ramp.
+
+Affine matrices are supported for brush transforms, but not projective
+matrices.
+
+
+    \row
+        \o Rectangles, lines, and points
+        \o Rectangles, lines, and rounded rectangles use cached VGPath
+objects to try to accelerate drawing operations.  vgModifyPathCoords() is
+used to modify the co-ordinates in the cached VGPath object each time
+fillRect(), drawRects(), drawLines(), or drawRoundedRect() is called.
+
+If the engine does not implement vgModifyPathCoords() properly, then the
+QVG_NO_MODIFY_PATH define can be set to disable path caching.  This will
+incur a performance penalty.
+
+Points are implemented as lines from the point to itself.  The cached line
+drawing VGPath object is used when drawing points.
+
+    \row
+        \o Polygons and Ellipses
+        \o Polygon and ellipse drawing creates a new VGPath object every
+time drawPolygon() or drawEllipse() is called.  If the client application
+is making heavy use of these functions, the constant creation and
+destruction of VGPath objects could have an impact on performance.
+
+If a projective transformation is active, ellipses are converted into cubic
+curves prior to transformation, which may further impact performance.
+
+Client applications should avoid polygon and ellipse drawing in performance
+critical code if possible.
+
+    \row
+        \o Other Objects
+        \o Most other objects (arcs, pies, etc) use drawPath(), which takes
+a QPainterPath argument.  The default implementation in QPainterEngineEx
+converts the QPainterPath into a QVectorPath and then calls draw(), which
+in turn converts the QVectorPath into a VGPath for drawing.
+ 
+To reduce the overhead, we have overridden drawPath() in QVGPaintEngine to
+convert QPainterPath's directly into VGPath's.  This should help improve
+performance compared to the default implementation.
+
+Client applications should try to avoid these types of objects in
+performance critical code because of the QPainterPath to VGPath conversion
+cost.
+
+    \row
+        \o Clipping
+        \o Clipping with QRect, QRectF, and QRegion objects is supported on
+all OpenVG engines with vgMask() if the transformation matrix is the
+identity or a simple origin translation.
+ 
+Clipping with an arbitrary QPainterPath, or setting the clip region when
+the transformation matrix is simple, is supported only if the OpenVG engine
+has the vgRenderToMask() function (OpenVG 1.1 and higher).
+
+The QVG_NO_RENDER_TO_MASK define will disable the use of vgRenderToMask().
+
+The QVG_SCISSOR_CLIP define will disable clipping with vgMask() or
+vgRenderToMask() and instead use the scissor rectangle list to perform
+clipping.  Clipping with an arbitrary QPainterPath will not be supported.
+ 
+The QVG_SCISSOR_CLIP define should only be used if the OpenVG engine does
+not support vgMask() or vgRenderToMask().
+
+    \row
+        \o Opacity
+        \o Opacity is supported for all drawing operations.  Solid color
+pens, solid color brushes, gradient brushes, and image drawing with
+drawPixmap() and drawImage() will probably have the best performance
+compared to other kinds of pens and brushes.
+
+    \row
+        \o Text Drawing
+        \o If OpenVG 1.1 is used, the paint engine will use VG fonts to
+cache glyphs while drawing.  If the engine does not support VG fonts
+correctly, QVG_NO_DRAW_GLYPHS can be defined to disable this mode.  Text
+drawing performance will suffer if VG fonts are not used.
+
+By default, image-based glyphs are used. If QVG_NO_IMAGE_GLYPHS is defined,
+then path-based glyphs will be used instead. QVG_NO_IMAGE_GLYPHS is ignored
+if QVG_NO_DRAW_GLYPHS is defined.
+
+If path-based glyphs are used, then the OpenVG engine will need to support
+hinting to render text with good results.  Image-based glyphs avoids the
+need for hinting and will usually give better results than path-based
+glyphs.
+
+    \row
+        \o Pixmaps
+        \o In single-context mode, pixmaps will be implemented using
+VGImage unless QVG_NO_PIXMAP_DATA is defined.
+
+QVGPixmapData will convert QImage's into VGImage's when the application
+calls drawPixmap(), and the pixmap will be kept in VGImage form for the
+lifetime of the QVGPixmapData object.  When the application tries to paint
+into a QPixmap with QPainter, the data will be converted back into a QImage
+and the raster paint engine will be used to render into the QImage.
+
+This arrangement optimizes for the case of drawing the same static pixmap
+over and over (e.g. for icons), but does not optimize the case of drawing
+into pixmaps.
+
+Bitmaps must use QRasterPixmapData.  They are not accelerated with VGImage
+at present.
+
+    \row
+        \o Pixmap filters
+        \o Convolution, colorize, drop shadow, and blur filters are
+accelerated using OpenVG operations.
+
+\endtable
+
+\section2 Known issues
+
+Performance of copying the contents of an OpenVG-rendered window to the
+screen needs platform-specific work in the QVGWindowSurface class.
+
+Clipping with arbitrary non-rectangular paths only works on engines that
+support vgRenderToMask(). Simple rectangular paths are supported on all
+engines that correctly implement vgMask().
+
+The paint engine is not yet thread-safe, so it is not recommended for use
+in threaded Qt applications that draw from multiple threads. Drawing should
+be limited to the main GUI thread.
+
+Performance of projective matrices for non-image drawing is not as good
+as for affine matrices.
+
+QPixmap's are implemented as VGImage objects so that they can be quickly
+rendered with drawPixmap().  Rendering into a QPixmap using QPainter will
+use the default Qt raster paint engine on a QImage copy of the QPixmap, and
+will not be accelerated.  This issue may be addressed in a future version
+of the engine.
+
+ShivaVG support is highly experimental and limited to Qt/X11. It is
+provided as an example of how to integrate a non-EGL engine.
+
diff --git a/doc/src/platforms/qt-embedded-linux.qdoc b/doc/src/platforms/qt-embedded-linux.qdoc
index 21cbf3b..a6524d7 100644
--- a/doc/src/platforms/qt-embedded-linux.qdoc
+++ b/doc/src/platforms/qt-embedded-linux.qdoc
@@ -96,7 +96,7 @@
         \o \l {Qt for Embedded Linux Pointer Handling}{Pointer Handling}
         \o \l {Qt for Embedded Linux Character Input}{Character Input}
         \o \l {Qt for Embedded Linux Display Management}{Display Management}
-        \o \l {Qt for Embedded Linux and OpenGL}{OpenGL}
+        \o \l {Qt for Embedded Linux Hardware Accelerated Graphics}{Hardware Accelerated Graphics}
         \o \l {Qt for Embedded Linux Fonts}{Fonts}
     \endlist
 
diff --git a/doc/src/platforms/wince-introduction.qdoc b/doc/src/platforms/wince-introduction.qdoc
index 46ecbf6..886b084 100644
--- a/doc/src/platforms/wince-introduction.qdoc
+++ b/doc/src/platforms/wince-introduction.qdoc
@@ -65,7 +65,7 @@
     \endlist
     \o
     \list
-        \o \l {Windows CE OpenGL ES}{OpenGL ES}
+        \o \l {Qt for Windows CE Hardware Accelerated Graphics}{Hardware Accelerated Graphics}
         \o \l {Qt Performance Tuning}
         \o \l {Fine-Tuning Features in Qt}
     \endlist
diff --git a/doc/src/platforms/wince-opengl.qdoc b/doc/src/platforms/wince-opengl.qdoc
index 4fc4d7b..0ea2ec6 100644
--- a/doc/src/platforms/wince-opengl.qdoc
+++ b/doc/src/platforms/wince-opengl.qdoc
@@ -41,58 +41,48 @@
 
 /*!
     \page windowsce-opengl.html
-    \title Windows CE OpenGL ES
+    \title Qt for Windows CE and OpenGL ES
     \ingroup qtce
     \brief Information about support for OpenGL ES with Qt for Windows CE.
 
-    \section1 Introduction
+    \input platforms/emb-opengl.qdocinc
 
-    \l {http://www.opengl.org}{OpenGL} is an industry standard API for 2D/3D
-    graphics. It provides a powerful, low-level interface between software
-    and acceleration hardware, and it is operating system and window system
-    independent.
+\section1 Using OpenGL with Qt for Windows CE
+Qt for Windows CE uses EGL 1.1 to embed OpenGL ES windows within the
+Windows CE window manager.
 
-    \l {http://www.khronos.org/opengles}{OpenGL ES} is a subset of the
-    \l {http://www.opengl.org}{OpenGL} standard. It is meant for use in
-    embedded systems. Hence, it has a smaller, more constrained API.
+\section2 Configure
 
-    Qt for Windows CE uses EGL 1.1 to embed OpenGL ES windows within the
-    Windows CE window manager.
+To configure Qt for Windows Mobile 5.0 and OpenGL ES Common Lite support
+you can run \c{configure} like this:
 
-    To use OpenGL ES enabled widgets in a Qt for Windows CE application, you
-    only need to subclass QGLWidget and draw on instances of the subclass with
-    OpenGL ES functions.
-
-    OpenGL ES includes profiles for floating-point and fixed-point arithmetic.
-    The floating point profile is called OpenGL ES CM (Common) and the
-    fixed-point profile is called OpenGL ES CL (Common Lite).
-
-    You can run \c{configure} with the \c{-opengl-es-cm} option for the Common
-    profile or \c{-opengl-es-cl} for the Common Lite profile. In both cases,
-    ensure that the \c{lib} and \c{includes} paths include the OpenGL ES
-    headers and libararies from your SDK. The OpenGL ES lib should be called
-    either \c{libGLES_CM.lib} for the Common profile or \c{libGLES_CL.lib}
-    for the Common Lite profile.
+    \snippet doc/src/snippets/code/doc_src_wince-opengl.qdoc 0
 
-    To configure Qt for Windows Mobile 5.0 and OpenGL ES Common Lite support
-    you can run \c{configure} like this:
+OpenGL ES includes profiles for floating-point and fixed-point arithmetic.
+The floating point profile is called OpenGL ES CM (Common) and the
+fixed-point profile is called OpenGL ES CL (Common Lite).
 
-    \snippet doc/src/snippets/code/doc_src_wince-opengl.qdoc 0
+You can run \c{configure} with the \c{-opengl-es-cm} option for the Common
+profile or \c{-opengl-es-cl} for the Common Lite profile. In both cases,
+ensure that the \c{lib} and \c{includes} paths include the OpenGL ES
+headers and libararies from your SDK. The OpenGL ES lib should be called
+either \c{libGLES_CM.lib} for the Common profile or \c{libGLES_CL.lib} for
+the Common Lite profile.
 
-    The distinction between the Common and Common Lite profiles is important,
-    because the Common Lite profile has less functionality and only supports a
-    fixed-point vertex format.
+The distinction between the Common and Common Lite profiles is important,
+because the Common Lite profile has less functionality and only supports a
+fixed-point vertex format.
 
-    To start programming with Qt and OpenGL ES on Windows CE, you can start
-    with the \l{Hello GL ES Example}. This example shows how to use QGLWidget
-    and QGLPainter with OpenGL ES. It also provides some hints on how to port
-    OpenGL code to OpenGL ES.
+To start programming with Qt and OpenGL ES on Windows CE, you can start
+with the \l{Hello GL ES Example}. This example shows how to use QGLWidget
+and QGLPainter with OpenGL ES. It also provides some hints on how to port
+OpenGL code to OpenGL ES.
 
-    \section2 Using OpenGL to Accelerate Normal 2D Painting
+\section2 Using OpenGL to Accelerate Normal 2D Painting
 
-    Qt provides QOpenGLPaintEngine, a subclass of QPaintEngine that translates
-    QPainter operations into OpenGL calls. This is especially convenient for
-    drawing text or QImage objects in an OpenGL ES context. For further
-    details, refer to the \l{Hello GL ES Example}.
+Qt provides QOpenGLPaintEngine, a subclass of QPaintEngine that translates
+QPainter operations into OpenGL calls. This is especially convenient for
+drawing text or QImage objects in an OpenGL ES context. For further
+details, refer to the \l{Hello GL ES Example}.
 
 */
diff --git a/doc/src/platforms/wince-openvg.qdoc b/doc/src/platforms/wince-openvg.qdoc
new file mode 100644
index 0000000..047c655
--- /dev/null
+++ b/doc/src/platforms/wince-openvg.qdoc
@@ -0,0 +1,65 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page windowsce-openvg.html
+    \title Qt for Windows CE and OpenVG
+    \ingroup qtce
+    \brief Information about support for OpenVG with Qt for Windows CE.
+
+    \input platforms/emb-openvg.qdocinc
+
+\section1 Using OpenVG with Qt for Windows CE
+Qt for Windows CE uses EGL 1.1 to embed OpenVG windows within the Windows
+CE window manager.
+
+\note Make sure that your Windows CE SDK have a working EGL implementation.
+If not, OpenVG will not work.
+
+\note There is currently no support for Blitting and Alpha blending in Qt
+for Windows CE.
+
+\note To configure Qt for Windows Mobile 5.0 and OpenVG support you can run
+\c{configure} like this:
+
+    \snippet doc/src/snippets/code/doc_src_wince-opengl.qdoc 0
+
+*/