Doc: Adding documentation on Embedded Hardware acceleration

Added "best practice" page on HW acc for mebedded. Modified HW acc docs. Adding Hello GL ES for Wince to the list of examples.

QTBUG-5791
David Boddie
(cherry picked from commit fbbdf8698fb0444d5170b7d0a14e870ea789398f)

5 files changed, 289 insertions, 144 deletions

diff --git a/doc/src/getting-started/examples.qdoc b/doc/src/getting-started/examples.qdoc
index 2c5e9eb..c69c002 100644
--- a/doc/src/getting-started/examples.qdoc
+++ b/doc/src/getting-started/examples.qdoc
@@ -778,6 +778,7 @@
     \o \l{opengl/framebufferobject2}{Framebuffer Object 2}
     \o \l{opengl/grabber}{Grabber}
     \o \l{opengl/hellogl}{Hello GL}\raisedaster
+    \o \l{opengl/hellogl_es}{Hello GL - ported to Windows CE}\raisedaster
     \o \l{opengl/overpainting}{Overpainting}\raisedaster
     \o \l{opengl/pbuffers}{Pixel Buffers}
     \o \l{opengl/pbuffers2}{Pixel Buffers 2}
diff --git a/doc/src/howtos/HWacceleration.qdoc b/doc/src/howtos/HWacceleration.qdoc
new file mode 100644
index 0000000..80db740
--- /dev/null
+++ b/doc/src/howtos/HWacceleration.qdoc
@@ -0,0 +1,100 @@
+/****************************************************************************
+**
+** 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 HWAcc_rendering.html
+    \title Using hardware acceleration on embedded platforms.
+
+    \ingroup best-practices
+
+    \section1 Abstract
+    This document describes how to use hardware acceleration for fast
+    rendering on embedded platforms supported by Qt. In short, it explains
+    how the graphics pipeline works. Since there might be differences to 
+	how the APIs are being used on different embedded platforms, a table
+	links to documentation dedicated to platform specific documentation
+	for each supported hardware acceleration API.
+
+    \input platforms/emb-hardwareacceleration.qdocinc
+
+    \section1 Supported platforms
+	Since there might be differences to how the APIs are being used on
+	the different embedded platforms, this table provides you with links to
+	pages dedicated to platform specific documentation for each
+	supported hardware acceleration API. Click the API link for the
+	platform to go the correct documentation.
+
+    \table
+        \header
+            \o Operating System
+            \o {3,1} Hardware Acceleration Platform
+        \row
+            \o \bold {Windows CE}
+            \o \l {Qt for Windows CE and OpenGL ES}{OpenGL ES}
+            \o \l {Qt for Windows CE and OpenVG}{OpenVG} 
+            \o
+        \row
+            \o \bold {Embedded Linux}
+            \o \l {Qt for Embedded Linux and OpenGL}{OpenGL ES}
+            \o \l {Qt for Embedded Linux and OpenVG}{OpenVG} 
+            \o \l {Qt for Embedded Linux and DirectFB}{DirectFB}
+        \row
+            \o \bold {Symbian Platform}
+            \o {3,1} \e {There are currently no support for hardware
+            acceleration.}
+    \endtable
+\omit
+    \section1 Examples using hardware acceleration on embedded platforms.
+
+    \table
+        \header
+            \o Embedded Platform
+            \o Example
+        \row
+            \o Windows CE
+        \row
+            \o Embedded Linux
+    \endtable
+\endomit
+
+
+
+*/
diff --git a/doc/src/platforms/emb-HwAcc-LinuxEmbedded.qdoc b/doc/src/platforms/emb-HwAcc-LinuxEmbedded.qdoc
index 4cd82e4..b2b54d1 100644
--- a/doc/src/platforms/emb-HwAcc-LinuxEmbedded.qdoc
+++ b/doc/src/platforms/emb-HwAcc-LinuxEmbedded.qdoc
@@ -49,23 +49,57 @@
     \ingroup qt-embedded-linux
 
 
-  \input platforms/emb-hardwareacceleration.qdocinc
+	\input platforms/emb-hardwareacceleration.qdocinc
 
-\section1 Supported Hardware Accelerated Graphics APIs
+    \section1 Windowing on Embedded Linux with Hardware Accelerated Graphics
 
-This list shows which Hardware Accelerated Graphics APIs currently
-supported by Qt.
+    Qt for Embedded Linux includes its own windowing system, QWS. QWS was
+    designed in 1999, well before graphics acceleration was available for
+    embedded devices. It does a great job providing a lightweight window
+    manager including all the expected functionality such as arbitrary
+    windows that can be moved, resized, minimized, etc. Getting QWS to work
+    with GPUs is very challenging, particularly with OpenGL and OpenVG
+    because there is no standard way in Linux to share textures across
+    processes. Some silicon vendors provide private APIs to allow texture
+    sharing, others do not. These limitations are documented under the
+    sections describing each type of accelerated hardware APIs. The simplest
+    most generic support for accelerated graphics is a full screen single
+    process single window.
 
- \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 
+    \section2 General options
+    \list
+        \o QWS, not accelerated, allows arbitrary windowing with multiple
+        processes drawing on the screen.
+        \o X11 with an accelerated X11 driver provided by the silicon
+        vendor. Like QWS, this allows arbitrary windows with multiple
+        processes drawing on the screen. Our experience is that there is
+        some overhead from X11 which will adversely affect framerates.
+        Additionally, our experience is that the drivers from silicon
+        vendors are still maturing.
+        \o Full screen single process single window. This will always work.
+        Some additional capabilities are available and are documented in
+        the acceleration specific API sections.
+    \endlist
+
+    \section1 Supported Hardware Accelerated Graphics APIs
+
+    This table shows which Hardware Accelerated Graphics APIs currently
+    supported by Qt.
+
+     \table 
+     \header
+        \o Supported APIs
+		\o API Version
+     \row
+        \o \l {Qt for Embedded Linux and OpenGL}{OpenGL ES}
+		\o 1.x and 2.x
+     \row
+        \o \l {Qt for Embedded Linux and OpenVG}{OpenVG } 
+		\o 1.1
+     \row
+        \o \l {Qt for Embedded Linux and DirectFB}{DirectFB}
+		\o 2.0
+     \endtable 
 
 
 */
diff --git a/doc/src/platforms/emb-HwAcc-WinCE.qdoc b/doc/src/platforms/emb-HwAcc-WinCE.qdoc
index 0d8c78b..42047aa 100644
--- a/doc/src/platforms/emb-HwAcc-WinCE.qdoc
+++ b/doc/src/platforms/emb-HwAcc-WinCE.qdoc
@@ -47,7 +47,6 @@
     \title Qt for Windows CE Hardware Accelerated Graphics
     \ingroup qtce
 
-
     \input platforms/emb-hardwareacceleration.qdocinc
 
     \section1 Supported Hardware Accelerated Graphics APIs
diff --git a/doc/src/platforms/emb-hardwareacceleration.qdocinc b/doc/src/platforms/emb-hardwareacceleration.qdocinc
index 3851628..fb00e09 100644
--- a/doc/src/platforms/emb-hardwareacceleration.qdocinc
+++ b/doc/src/platforms/emb-hardwareacceleration.qdocinc
@@ -1,129 +1,140 @@
-
-\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.
+	\section1 Hardware Acceleration
+	
+	When designing applications for embedded devices there is often a
+	compromise between graphics effects and performance. On most
+	devices, you cannot have both simply because the hardware needed
+	for such operations just is not there. With a growing number of
+	devices that use hardware dedicated to graphics operations there is
+	less need to compromise.
+	
+	In addition to enabling dynamic graphics effects, there are two
+	other benefits to using graphics acceleration. One is that 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.
+	Typical \e {System-on-a-chip} (SoC) 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.
+	
+	Another reason to use a GPU is to offload the main CPU, either for
+	power saving or to perform other operations in parallel. Often
+	drawing speed with a GPU is not that much faster than a CPU but
+	the clear benefit of using the GPU is to free up the CPU to perform
+	other tasks which can be used to create a more responsive use
+	experience.
+	
+	The key to writing 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.