diff options
| -rw-r--r-- | doc/src/images/platformHWAcc.png | bin | 0 -> 11068 bytes | |||
| -rw-r--r-- | doc/src/modules.qdoc | 5 | ||||
| -rw-r--r-- | doc/src/platforms/emb-HwAcc-LinuxEmbedded.qdoc | 71 | ||||
| -rw-r--r-- | doc/src/platforms/emb-HwAcc-WinCE.qdoc | 69 | ||||
| -rw-r--r-- | doc/src/platforms/emb-directfb-EmbLinux.qdoc | 340 | ||||
| -rw-r--r-- | doc/src/platforms/emb-hardwareacceleration.qdocinc | 129 | ||||
| -rw-r--r-- | doc/src/platforms/emb-opengl-EmbLinux.qdoc | 164 | ||||
| -rw-r--r-- | doc/src/platforms/emb-opengl.qdocinc | 85 | ||||
| -rw-r--r-- | doc/src/platforms/emb-openvg-EmbLinux.qdoc | 53 | ||||
| -rw-r--r-- | doc/src/platforms/emb-openvg.qdocinc | 288 | ||||
| -rw-r--r-- | doc/src/platforms/qt-embedded-linux.qdoc | 2 | ||||
| -rw-r--r-- | doc/src/platforms/wince-introduction.qdoc | 2 | ||||
| -rw-r--r-- | doc/src/platforms/wince-opengl.qdoc | 70 | ||||
| -rw-r--r-- | doc/src/platforms/wince-openvg.qdoc | 65 |
14 files changed, 1299 insertions, 44 deletions
diff --git a/doc/src/images/platformHWAcc.png b/doc/src/images/platformHWAcc.png Binary files differnew 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 + +*/ |
