Documentation: Embedded hardware acceleration

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

Task-number: QT-1109

Rev-by: Anders Bakken

Rev-by: Rhys Weatherley

Rev-by: Thomas Hartmann

1 files changed, 340 insertions, 0 deletions

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. 
+
+*/