summaryrefslogtreecommitdiffstats
path: root/doc/src/platforms
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/platforms')
-rw-r--r--doc/src/platforms/emb-HwAcc-LinuxEmbedded.qdoc71
-rw-r--r--doc/src/platforms/emb-HwAcc-WinCE.qdoc69
-rw-r--r--doc/src/platforms/emb-directfb-EmbLinux.qdoc330
-rw-r--r--doc/src/platforms/emb-hardwareacceleration.qdocinc129
-rw-r--r--doc/src/platforms/emb-opengl-EmbLinux.qdoc (renamed from doc/src/platforms/emb-opengl.qdoc)112
-rw-r--r--doc/src/platforms/emb-opengl.qdocinc85
-rw-r--r--doc/src/platforms/emb-openvg-EmbLinux.qdoc53
-rw-r--r--doc/src/platforms/emb-openvg.qdocinc288
-rw-r--r--doc/src/platforms/qt-embedded-linux.qdoc2
-rw-r--r--doc/src/platforms/qt-embedded.qdoc2
-rw-r--r--doc/src/platforms/s60-introduction.qdoc10
-rw-r--r--doc/src/platforms/wince-introduction.qdoc2
-rw-r--r--doc/src/platforms/wince-opengl.qdoc70
-rw-r--r--doc/src/platforms/wince-openvg.qdoc65
-rw-r--r--doc/src/platforms/winsystem.qdoc12
15 files changed, 1163 insertions, 137 deletions
diff --git a/doc/src/platforms/emb-HwAcc-LinuxEmbedded.qdoc b/doc/src/platforms/emb-HwAcc-LinuxEmbedded.qdoc
new file mode 100644
index 0000000000..9c18d873c9
--- /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 0000000000..66b6948d78
--- /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 0000000000..38782be412
--- /dev/null
+++ b/doc/src/platforms/emb-directfb-EmbLinux.qdoc
@@ -0,0 +1,330 @@
+/****************************************************************************
+**
+** 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{DirectFB - IDirectFBSurface}{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
+\endcode
+
+\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{DirectFB - 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{DirectFB - 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
+\e{src/plugins/gfxdrivers/directfb/directfb.pro} to
+\e{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{QImage::}{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{DirectFB - df_window example}{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{DirectFB - IDirectFBPalette}{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{C++ Reference - 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{DirectFB - CreateInputEventBuffer}{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{DirectFB - 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{DirectFB - IDirectFBImageProvider}{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 0000000000..3851628155
--- /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.qdoc b/doc/src/platforms/emb-opengl-EmbLinux.qdoc
index 2ed5d041e9..bede2ca460 100644
--- a/doc/src/platforms/emb-opengl.qdoc
+++ b/doc/src/platforms/emb-opengl-EmbLinux.qdoc
@@ -40,31 +40,24 @@
****************************************************************************/
/*!
-\page qt-embedded-opengl.html
+\page qt-embeddedLinux-opengl.html
\title Qt for Embedded Linux and OpenGL
-\ingroup qt-embedded-linux
-\section1 Introduction
+\ingroup qt-embedded-linux
-\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.
+\input platforms/emb-opengl.qdocinc
-\l {http://www.khronos.org/opengles}{OpenGL ES} is a subset
-of the \l {http://www.opengl.org}{OpenGL} standard.
-Because it is meant for use in embedded systems, it has a smaller,
-more constrained API.
+\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.
-For reference, Nokia provides support for integrating \l
-{http://www.khronos.org/opengles}{OpenGL ES} with Qt for Embedded Linux
-for drawing into a QGLWidget.
+\note OpenGL rendering only works with QGLWidget under QWS. Regular
+widgets cannot currently support it.
-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. These issues
-will be addressed in future versions of Qt.
+\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
@@ -72,58 +65,11 @@ 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 3D Graphics in Applications
-
-The \l {QtOpenGL module} offers classes that make it easy to draw 3D
-graphics in GUI applications. The module API is cross-platform, so it
-is also available on Windows, X11, and Mac OS X.
-
-To use OpenGL-enabled widgets in a Qt for Embedded Linux application,
-all that is required is to subclass the QGLWidget and draw into instances of
-the subclass with standard OpenGL functions.
-
-Note that 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.
-
-\section2 Using OpenGL to Accelerate Normal 2D Painting
-
-Qt provides a subclass of QPaintEngine that translates QPainter operations
-into OpenGL calls (there are actually two subclasses, one for OpenGL/ES 1.1
-and another for OpenGL/ES 2.0). 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.
-
-As mentioned above, 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.setViewportUpdateMode(QGraphicsView::FullViewportUpdate);
-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.
-
\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.
+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.
@@ -135,23 +81,20 @@ 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.
+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
+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 a \c EGLNativeWindowType value in some underlying window system
+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.
@@ -159,7 +102,7 @@ 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
+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.
@@ -218,13 +161,4 @@ 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.
-\section1 OpenVG Support
-
-\l {http://www.khronos.org/openvg} {OpenVG} 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. Acceleration of
-regular widgets is supported with OpenVG, unlike with OpenGL/ES.
-See \l{OpenVG Rendering in Qt} for more information on the
-OpenVG support in Qt.
-
*/
diff --git a/doc/src/platforms/emb-opengl.qdocinc b/doc/src/platforms/emb-opengl.qdocinc
new file mode 100644
index 0000000000..dac537946e
--- /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 0000000000..abdb6174c1
--- /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 0000000000..37ccb9c1de
--- /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 21cbf3be5d..a6524d77c6 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/qt-embedded.qdoc b/doc/src/platforms/qt-embedded.qdoc
index e0c35cc8ba..b38c94f5ec 100644
--- a/doc/src/platforms/qt-embedded.qdoc
+++ b/doc/src/platforms/qt-embedded.qdoc
@@ -67,7 +67,7 @@
Applications use the appropriate style for the embedded
environment and use native features, such as menus, to conform
to the native style guidelines.
- \o \l{Symbian platform - Introduction to using Qt}{Qt for the Symbian
+ \o \l{Symbian Platform - Introduction to Qt}{Qt for the Symbian
platform} is used to create applications running in existing Symbian
platform environments. Applications use the appropriate style for the
embedded environment and use native features, such as menus, to conform
diff --git a/doc/src/platforms/s60-introduction.qdoc b/doc/src/platforms/s60-introduction.qdoc
index 5fd0cbe2bd..058198238b 100644
--- a/doc/src/platforms/s60-introduction.qdoc
+++ b/doc/src/platforms/s60-introduction.qdoc
@@ -42,7 +42,7 @@
/*!
\page symbian-with-qt-introduction.html
- \title Symbian platform - Introduction to using Qt
+ \title Symbian Platform - Introduction to Qt
\brief An introduction to Qt for Symbian platform developers.
\ingroup howto
\ingroup qts60
@@ -51,15 +51,15 @@
\section1 Required tools
- See \l{Qt for Symbian platform Requirements} to see what tools are
+ See \l{Qt for Symbian Platform Requirements} to see what tools are
required to use Qt for Symbian platform.
\section1 Installing Qt and running demos
- Follow the instructions found in \l{Installing Qt on the Symbian platform using binary package} to learn how
- to install Qt using binary package and how to build and run Qt demos.
+ Follow the instructions found in \l{Installing Qt on the Symbian platform from a Binary Package}
+ to learn how to install Qt using a binary package and how to build and run Qt demos.
- Follow the instructions found in \l{Installing Qt on the Symbian platform} to learn how to install Qt using
+ Follow the instructions found in \l{Installing Qt on the Symbian Platform} to learn how to install Qt using
using source package and how to build and run the Qt demos.
\section1 Building your own applications
diff --git a/doc/src/platforms/wince-introduction.qdoc b/doc/src/platforms/wince-introduction.qdoc
index 46ecbf666a..886b0840ba 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 4fc4d7be64..0ea2ec65e5 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 0000000000..047c6553a0
--- /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
+
+*/
diff --git a/doc/src/platforms/winsystem.qdoc b/doc/src/platforms/winsystem.qdoc
index f427d6e99f..72e7da60b5 100644
--- a/doc/src/platforms/winsystem.qdoc
+++ b/doc/src/platforms/winsystem.qdoc
@@ -43,6 +43,7 @@
\page winsystem.html
\title Window System Specific Notes
\ingroup platform-specific
+ \brief Collections of notes about Qt implementations on different window systems.
Qt is a cross-platform GUI toolkit, so almost the entire API is the
same on all platforms and window systems. If you wish to use
@@ -95,4 +96,15 @@
When compiling for this platform, the macro \c{Q_WS_QWS} is
defined (the window system is literally the Qt Window System). See
the \l{Qt for Embedded Linux} documentation for more information.
+
+ \section1 Qt for Windows CE
+
+ When compiling for this platform, the macro \c{Q_WS_WINCE} is defined.
+ See the \l{Qt for Windows CE} documentation for more information.
+
+ \section1 Qt for Symbian Platform
+
+ When compiling for this platform, the macro \c{Q_WS_S60} is defined.
+ See the \l{Symbian Platform - Introduction to Qt} documentation for
+ more information.
*/
generated by cgit v1.2.3 (git 2.25.1) at 2024-05-04 16:13:58 +0000