Update copyright headers
[qt:qt.git] / doc / src / platforms / emb-directfb-EmbLinux.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29 \page qt-embeddedLinux-directfb.html
30
31 \title Qt for Embedded Linux and DirectFB
32
33 \ingroup qt-embedded-linux
34
35 \section1 Introduction
36
37 DirectFB is an open source LGPL licensed project founded by Denis Oliver Kropp
38 and generally chip vendors start out with the official version and
39 implement their own plugins to optimize the operations their hardware
40 supports.
41
42 We recommend using Qt 4.6 or later with DirectFB. Support for DirectFB was
43 introduced into Qt for Embedded Linux as a labs project for Qt 4.3 and folded
44 into Qt as a screen driver for Qt 4.4, but not supported fully. In Qt 4.5,
45 major changes were made to make it work with the optimized raster paint
46 engine. These changes were further improved in Qt 4.6.
47
48 \tableofcontents
49
50 \section1 Using DirectFB with Qt
51 DirectFB is centered around \l{DirectFB - IDirectFBSurface}{Surfaces}
52 which is the equivalent of a QPaintDevice. In the Qt/DirectFB plugin,
53 DirectFB maps onto either a QPixmap or a QWindowSurface which essentially
54 means that drawing onto QPixmap or a QWidget can be accelerated and drawing
55 onto any other paint device (e.g. QImage) cannot.
56
57 \section2 Configure
58
59 When configuring Qt there are two options, from which you can choose:
60
61 \code
62     ./configure -plugin-gfx-directfb 
63     ./configure -qt-gfx-directfb 
64
65 \endcode
66
67 With either mode, Qt will try the following to look for the DirectFB
68 includes/libs.
69
70 \list
71     \o Use pkg-config
72     \o Use directfb-config
73     \o Check in your qmake.conf
74 \endlist
75
76 Often the values returned from pkg-config/directfb-config indicates the
77 locations of the libs/headers on the target rootfs, rather than their
78 location on your host. The safest option is usually to explicitly populate
79 these variables in your qmake.conf like this:
80
81 \code
82 QT_CFLAGS_DIRECTFB =
83 /opt/toolchain/gcc4.3_mipsel_linux/usr/include/directfb -D_REENTRANT
84 QT_LIBS_DIRECTFB = -L/opt/toolchain/gcc4.3_mipsel_linux/usr/lib/-ldirect
85 -ldirectfb -lfusion
86 \endcode
87
88 \note While DirectFB supports a multi-process setup through a
89 kernel-extension called Fusion this setup is not well tested with Qt.
90
91 \section2 Supported graphics operations
92
93 IDirectFBSurface supports blitting, filling, drawing lines rects etc, but
94 it does not support everything Qt allows you to do. E.g. painter paths,
95 polygons, complex transformations, antialiasing, gradients. Some of these
96 things are handled in newer versions of DirectFB and could be supported by
97 Qt. They are seemingly optional at the driver level, so you need to have
98 fall back code paths for older drivers and drivers on which this is not
99 implemented.
100
101 The QDirectFBPaintEngine is a subclass of the QRasterPaintEngine, thus
102 essentially supporting everything QRasterPaintEngine supports. This means
103 that it supports all graphical operations that Qt supports, but certain
104 operations will have to fall back to software rendering and that should be
105 avoided due to performance issues. Instead, these operations should be
106 rendered into a QPixmap once, and then reuse the pixmap.
107
108 Note: Fallbacks to software rendering should be avoided. If unsupported
109 operations are used, the paint engine must fallback to the
110 QRasterPaintEngine engine. A good debugging tip is to make Qt warn you when
111 such fall backs occur, and to disable the fall back and only return.
112 Debugging options are listed below.
113
114 \section2 DirectFB driver
115 DirectFB also provides an abstraction for keyboard and mouse drivers. This
116 simplifies the process of getting the target hardware up and running. It
117 also brings us to a feature fragmentation issue between different versions
118 of DirectFB.
119
120 The Qt DirectFB driver currently supports DirectFB versions >= 0.9. Still,
121 there are large differences in what each actual implementation handles
122 correctly. It is relatively common not to properly support
123 \l{DirectFB - IDirectFBWindow}{DirectFB windows}, so Qt needs to handle
124 this case with a different code path. In addition, certain drivers do not
125 properly support DirectFB's cursor handling. This means Qt has to have a
126 code path for rendering the cursor itself when this is the case.
127 Some drivers do not let us create
128 \l{DirectFB - DFBSurfaceDescription}{preallocated surfaces} which means we
129 have to have a conditional code path for that case. 
130
131 \section2 Optimize performance using define options
132
133 Qt/DirectFB comes with a number of defines that can be either
134 uncommented in directfb.pri or added to the QT_DEFINES_DIRECTFB variable in
135 your qmake.conf.
136
137 \note The defines have been moved from
138 \e{src/plugins/gfxdrivers/directfb/directfb.pro} to
139 \e{src/gui/embedded/directfb.pri}
140
141 \code
142 #DIRECTFB_DRAWINGOPERATIONS=DRAW_RECTS|DRAW_LINES|DRAW_IMAGE|DRAW_PIXMAP|
143     DRAW_TILED_PIXMAP|STROKE_PATH|DRAW_PATH|DRAW_POINTS|DRAW_ELLIPSE|DRAW_POLYGON|
144     DRAW_TEXT|FILL_PATH|FILL_RECT|DRAW_COLORSPANS|DRAW_ROUNDED_RECT
145
146  #DEFINES += \"QT_DIRECTFB_WARN_ON_RASTERFALLBACKS=$$DIRECTFB_DRAWINGOPERATIONS\"
147  #DEFINES += \"QT_DIRECTFB_DISABLE_RASTERFALLBACKS=$$DIRECTFB_DRAWINGOPERATIONS\"
148 \endcode
149
150 As demonstrated above, you need to tell Qt which drawing operations you want
151 to warn/disable. Since there are varying implementations of DirectFB from
152 manufacturer to manufacture, different operations will be optimized. This
153 require you to define the operations you want to warn about or disable.
154 These are listed above in the DIRECTFB_DRAWINGOPERATIONS variable.
155
156 You can also customize this with environment variables.
157
158 E.g. If you want to disable fallbacks for drawPixmap and fillRect and also get
159 a warning printed on stderr when a fallback would have happened.
160
161 \code
162 $ export QT_DIRECTFB_WARN_ON_RASTERFALLBACKS="FILL_RECT|DRAW_PIXMAP"
163 $ export QT_DIRECTFB_DISABLE_RASTERFALLBACKS="FILL_RECT|DRAW_PIXMAP"
164 $ ./app -qws -display directfb
165 \endcode
166
167 Following is a table showing which options you have.
168
169 \table
170     \header
171         \o Define option
172         \o Description
173     \row
174         \o QT_DIRECTFB_IMAGECACHE
175         \o Defining this means that Qt will cache an IDirectFBSurface per
176 QImage you draw based on its \l{QImage::}{cacheKey()}.
177 Use this define if your application draws many QImages that
178 remain the same. Note that if you in this situation draw an image and then
179 change it, by calling bits() or opening a QPainter on it, the cache will
180 not benefit you. You can control the cache size with the imageCacheSize
181 connect option.
182
183     \row
184         \o QT_NO_DIRECTFB_WM
185         \o If your DirectFB implementation does not support windows, you
186 have to define this to make Qt work properly. You can test this by checking
187 if the \l{DirectFB - df_window example}{df_window example} runs well.
188 This means that all drawing operations onto a QWidget involves
189 an extra blitting step since Qt essentially first has to draw into an
190 off-screen buffer and then blit this buffer to the back buffer of the
191 primary surface. Finally, Qt must flip the back buffer to the front buffer,
192 which usually involves another blit. Still, blits are usually very fast
193 with DirectFB.
194
195 To work around this you can make your widget paint on screen, \l
196 Qt::WA_PaintOnScreen but this comes with other limitations. This should be
197 avoided if you want more than one full-screen window in your application.
198 In addition, it will not work without proper DirectFB mouse support from the
199 layer. Also, see QT_NO_DIRECTFB_LAYER for more.
200
201     \row
202         \o QT_NO_DIRECTFB_LAYER
203         \o If your DirectFB display layer cannot be used for e.g. drawing
204 mouse cursor, creating windows you have to define this. Defining this also
205 requires defining QT_NO_DIRECTFB_WM and involves making Qt render the
206 cursor rather than letting DirectFB do it.
207
208     \row
209         \o QT_NO_DIRECTFB_PALETTE
210         \o Define this if your DirectFB driver does not support surfaces
211 with \l{DirectFB - IDirectFBPalette}{color tables}.
212 The effect of defining this is that Qt will have to convert
213 images with \l QImage::Format_Indexed8 format to another format before
214 rendering them.
215
216     \row
217         \o QT_NO_DIRECTFB_PREALLOCATED
218         \o Define this if your DirectFB driver does not support creating a
219 surface with preallocated data. This will make a more frequent use of
220 \l{C++ Reference - memcpy}{memcpy()}
221 when drawing images. If you define this, you might want to consider
222 defining QT_DIRECTFB_IMAGECACHE for better image rendering performance.
223
224     \row
225         \o QT_NO_DIRECTFB_MOUSE and QT_NO_DIRECTFB_KEYBOARD
226         \o Define this if your driver does not provide keyboard/mouse
227 events through \l{DirectFB - CreateInputEventBuffer}{CreateInputEventBuffer}.
228 This means that Qt cannot use DirectFB to receive keyboard/mouse events and
229 if you want such events in your application, you will have to provide
230 another driver. For more info see \l {Qt for Embedded Linux Pointer
231 Handling}{Qt for Embedded Linux Pointer Handling} and \l{Qt for Embedded
232 Linux Character Input}{Qt for Embedded Linux Character Input}
233
234     \row
235         \o QT_DIRECTFB_TIMING
236         \o Define this when debugging to get output on stderr about the
237 frames per second.
238
239     \row
240         \o QT_NO_DIRECTFB_OPAQUE_DETECTION
241         \o When blitting a surface Qt has to decide whether to set the
242 \l{DirectFB - DFBSurfaceBlittingFlags}{DSBLIT_BLEND_ALPHACHANNEL}
243 flag. If you load an image from file or network data that has a format that
244 includes an alpha channel, the image might still be completely opaque.
245 Normally Qt runs through every pixel to check if there really is an alpha
246 channel there. This involves some overhead but usually pays off in the end
247 because blitting is cheaper than blending. If you define this Qt will
248 assume that an image with a format that has alpha channel contains at least
249 one pixel with an alpha value != 255.
250
251  \row
252     \o QT_DIRECTFB_SUBSURFACE
253     \o Defining this enables a mode that tries to minimize overhead from
254 locking/unlocking surfaces. Note that this currently is experimental.
255
256  \row
257     \o QT_DIRECTFB_WINDOW_AS_CURSOR
258     \o Define this if your DirectFB implementation supports windows but
259 can not render the cursor properly. This involves creating a small top level
260 window and moving it around when the cursor moves. It does not always
261 perform well.
262
263  \row
264     \o QT_NO_DIRECTFB_IMAGEPROVIDER
265     \o By default Qt will use DirectFB to load QPixmaps from disk/memory. If
266 your DirectFB implementation does not support this it might make sense to
267 define this. If you see strange rendering issues with pixmaps that have an
268 alpha channel defining this could solve the problem.
269
270  \row
271     \o QT_DIRECTFB_IMAGEPROVIDER_KEEPALIVE
272     \o Define this to make sure Qt always keeps at least one
273 \l{DirectFB - IDirectFBImageProvider}{IDirectFBImageProvider}
274 object alive. This is to avoid considerable overhead when the first
275 IDirectFBImageProvider is created, the last IDirectFBImageProvider is
276 removed.
277
278 \endtable
279
280 \section2 Unsupported graphics operations
281
282 There are a number of unsupported operations causing fallbacks. DirectFB
283 does not support the following functions.
284
285
286
287 \table
288  \header
289   \o Functions
290  \row
291   \o QPainter::strokePath(const QPainterPath & path, const QPen & pen)
292  \row
293   \o QPainter::drawPath(const QPainterPath & path)
294  \row
295   \o QPainter::fillPath(const QPainterPath & path, const QBrush & brush)
296  \row
297   \o QPainter::drawPoints(const QPointF * points, int pointCount)
298  \row
299   \o QPainter::drawEllipse(const QRectF & rectangle)
300  \row
301   \o QPainter::drawPolygon(const QPointF * points, int pointCount,
302  Qt::FillRule fillRule = Qt::OddEvenFill)
303  \row
304   \o QPainter::drawText(const QPointF & position, const QString & text)
305  \row
306   \o QGradient
307  \endtable
308
309 \section2 Avoiding fallbacks
310 To avoid fallbacks make sure that the following points are true:
311
312 \list
313     \o QPen::isSolid() returns true and uses a color with a one pixel
314 width. (QPen::width() returns 1.
315     \o QTransform::TransformationType() <= QTransform::TxScale are not
316 supported.
317     \o Clipping must be a simple rectangle or a QRegion.
318 \endlist
319
320 \section2 When painting images
321 \note You should use QPixmap instead of QImage. QImages are drawn by
322 the QRasterPaintEngine. To get a warning for every fallback to the
323 QRasterPaintEngine, use QT_DIRECTFB_WARN_ON_RASTERFALLBACKS. If
324 QT_DIRECTFB_DISABLE_RASTERFALLBACKS is defined, DirectFB will only return
325 instead of falling back to QRasterPaintEngine. Please note that these
326 defines should only be used when optimizing the application. 
327
328 \section2 Top level transparency
329 \note DirectFB supports partially or fully transparent top level windows,
330 either through QWidget::setWindowOpacity or through setting a non-opaque
331 background brush. Note that for the latter it is not supported to change an
332 opaque window to be transparent at runtime.
333 */