diff options
Diffstat (limited to 'doc/src/platforms/emb-directfb-EmbLinux.qdoc')
| -rw-r--r-- | doc/src/platforms/emb-directfb-EmbLinux.qdoc | 340 |
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 0000000000..b863951dd5 --- /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. + +*/ |