-
-
Notifications
You must be signed in to change notification settings - Fork 62
/
Copy pathREADME
446 lines (345 loc) · 16.7 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
DirectFB README
---------------
DirectFB is a graphics library which was designed with embedded
systems in mind. It offers maximum hardware accelerated performance
at a minimum of resource usage and overhead.
Check http://www.directfb.org/ for more and up to date infos.
Supported Operating Systems
---------------------------
- GNU/Linux
Using SDL (without acceleration support), DirectFB also supports
the following operating systems:
- FreeBSD (last tested: DirectFB 0.9.21 on FreeBSD 5.2)
- NetBSD (tested on NetBSD 1.6)
- OpenBSD (tested on OpenBSD 3.2)
(If you have problems, try ./configure --disable-mmx)
Please note that SDL support is experimental and incomplete. It is
intended for developers to allow development of DirectFB applications
in various environments.
Native (non SDL) support for the following operating systems is in progress:
- Mac OS X (tested on Mac OS X 10.3.5)
We do not have the resources to ensure that every release of
DirectFB works on all supported platforms. If you are a user of one
of the operating system listed above, and have the time to test the
CVS or GIT version regularly, your help is greatly appreciated.
Build Requirements
------------------
Mandatory are
- libc
- libpthread
- libm
- libdl
For regenerating autofoo (./autogen.sh or autoreconf)
- autoconf
- automake
- libtool
- pkg-config
Optionally, depending on the configuration you want:
FBDev
- Linux kernel 2.2.x or newer with working frame buffer device
(check /proc/fb) for the fbdev system.
SDL
- libSDL (Simple Direct Media Layer) for the sdl system.
X11
- libX11 (X11 client library) for the X11 system (libx11-dev and libxext-dev packages).
The following libraries are optional, but important (Debian package names):
Fonts
- libfreetype6-dev for TrueType and other fonts
Images
- libjpeg-dev for Joint Picture Expert Group images
- libpng-dev for Portable Network Graphics
Extra
- zlib1g-dev for compressed screenshot support (also needed by libpng)
The multi application core also requires <linux/fusion.h>, see the
section "Running multiple DirectFB applications" for more details.
The build of the image and font providers can be disabled but we
strongly suggest that you don't do this since the code examples and
a lot of DirectFB applications depend on the functionality provided
by them.
The libmpeg3 video provider requires the libmpeg3 library which is
not commonly installed. We provide this package on our web-site at
http://www.directfb.org/download/contrib/.
The avifile and flash video providers that used to be shipped with
DirectFB have been moved to the DirectFB-extra package.
We suggest you also install pkg-config available from
http://www.freedesktop.org/software/pkgconfig/. It will help you
to compile applications based on DirectFB.
Usage Requirements
------------------
Depending on the DirectFB application you want to run, you need some
or all of these:
- A working frame buffer device (check the output of 'fbset -i').
- A keyboard (if it works on the console, everything should be fine).
- A PS/2 or serial mouse for windowing. USB and ADB mice do also work
via PS/2 emulation.
Using the single application core you always need access to /dev/tty0,
/dev/fb0 and the mouse device (/dev/psaux, /dev/mouse).
You can either run all DirectFB applications as root or allow users
to access these devices. A reasonable way to do this is to add users
to the group tty (or some other group) and allow this group to read
and write the files in /dev:
crw-rw---- 1 root tty 29, 0 /dev/fb0
crw-rw---- 1 root tty 10, 1 /dev/psaux
crw-r----- 1 root tty 4, 0 /dev/tty0
If you are using the multi application core, only the master process needs
access to all of these devices. Additional processes (slaves) just need
access to /dev/fb0 and:
crw-rw---- 1 root fusion 29, 0 /dev/fusion/0
Note that the master creates a shared memory file, probably
in '/dev/shm/fusion.0'. It's read/writeable for anyone matching
the master process' user or group.
Some applications from the DirectFB-examples package have additional
requirements:
- A video card supported by video4linux for df_video.
- A joystick for df_joystick.
Running multiple DirectFB applications at the same time
-------------------------------------------------------
With the default build of the DirectFB library, only one DirectFB
application may be running. However you have the option to use the
multi application core of DirectFB which allows multiple DirectFB
applications to run at the same time within a session.
DirectFB applications communicate through a layer we call "Fusion".
This layer was previously implemented completely in user space using
semaphores and message queues. But since 0.9.15 the Fusion Kernel
Device is required which implements critical parts of Fusion and thus
lead to better performance and decent stability. To install this kernel
module (only available for Linux yet), find the linux-fusion
module in our CVS or GIT repository or on the DirectFB website.
For DirectFB 1.4.x releases you should use linux-fusion 8.1.1 or newer.
Compile DirectFB with multi-application core enabled:
./configure --enable-multi
Make sure your Linux kernel supports tmpfs. This is explained in
the kernel sources in Documentation/filesystems/tmpfs.txt.
Mount a tmpfs filesystem as /dev/shm:
mount tmpfs /dev/shm -ttmpfs
Optionally a mount point can be specified via the "tmpfs" option,
see directfbrc(5). The option has to be the same for all processes.
A good way to test the multi-application core is to install the lite
toolkit and DFBTerm, a DirectFB terminal (both available in the
DirectFB CVS/GIT repository). You can then start DirectFB applications
from dfbterm.
Recommendations
---------------
To take full advantage of hardware acceleration,
a Matrox G200/G400/G450/G550 graphics card is recommend for this
version of DirectFB. The drivers for ATI128, Voodoo 3/4/5/Banshee,
NeoMagic and S3 Savage cards included with this release are work in
progress and only yet support a subset of the possible accelerations.
Installation
------------
1) In the DirectFB directory type:
./configure <options>
make
make install (as superuser)
Use './configure --help' to get a list of possible configure options.
Imported options include:
--enable-multi Enables the Multi Application Core
--enable-debug Enables many debug messages and assertions
--enable-trace Enables run time stack trace information
Debugging and especially stack trace support are a performance
impact. It may be noticably slower in some areas, e.g. text drawing.
You may use the options "no-debug" and "no-trace" by default, e.g.
in '<prefix>/etc/directfbrc', and use "--dfb:debug,trace" on the command
line if needed.
2) Make sure that "<prefix>/lib" is listed in your /etc/ld.so.conf.
The default prefix is "/usr/local". After adding it you have to
run 'ldconfig' as superuser.
Alternatively, you can add the path to the environment
variable LD_LIBRARY_PATH. This is useful for temporarily
switching to another installed version.
3) You might want to copy fb.modes to /etc or merge it with your
existing /etc/fb.modes file. The first entry will be used by
default - copy other entries you may need.
4) If you want to use a serial mouse, create a link called /dev/mouse
that points to serial device (e.g. /dev/ttyS0). Then add a line
describing your mouse-protocol to /etc/directfbrc or ~/.directfbrc:
"mouse-protocol=[ms|ms3|mouseman|mousesystems]".
5) If you are cross compiling and have installed the required libraries
someplace other than /usr/local/lib be sure to add the bin directory
for those libraries to the front of your 'PATH'.
For instance if you configured using:
--prefix=/dfb/usr/local
then be sure to
export PATH=/dfb/usr/local/bin:$PATH
before compiling and installing.
Configuring DirectFB
--------------------
There are lots of things that can be configured. We try to ship DirectFB
with reasonable defaults but you might have to tweak things. There are
several ways to do this. You may edit the system-wide configuration
file <prefix>/etc/directfbrc or the user-specific $HOME/.directfbrc.
There's a manual page called directfbrc(5) that documents all the settings.
The same manual page also explains how DirectFB application can be
configured via the command-line.
Configuring the Linux frame buffer device
-----------------------------------------
DirectFB's prefered way-of-working needs a Linux kernel
with frame buffer support. Check the documentation in the kernel tree
(/usr/src/linux/Documentation/fb/) on how to enable the frame buffer device
for your graphics card.
The generic VESA frame buffer device does not support mode switching
and you will not get hardware acceleration. To make DirectFB work with
veasfb, you should add the following lines to /etc/lilo.conf:
append="video=vesa:ywrap,mtrr"
'ywrap' enables panning with wraparound.
'mtrr' enables setting caching type for the frame buffer to write-combining.
vga=791
This sets the mode on startup. 791 means 1024x768@16, 788 means 800x600@16.
All VESA Video Modes:
Bits 640x480 800x600 1024x768 1280x1024 1600x1200
8 769 771 773 775 796
16 785 788 791 794 798
32 786 789 792 795 799
Other frame buffer devices support mode switching. DirectFB will only
support modes listed in your /etc/fb.modes file. By default the first
entry found is used.
If you have a Matrox card you may want to try the vsync patch found in
the patches directory that enables applications to "idle wait" for the
vertical retrace.
Using the builtin "window manager"
----------------------------------
Since DirectFB lacks a real window manager, we added a hack to the
window stack to allow for basic window management. While pressing
the <Meta> (or Windows) key or alternatively <Caps-Lock> you can do
the following:
- Drag your mouse to move the focused window.
- Drag and press <Ctrl> to resize the focused window.
- Drag and press <Alt> to change the opacity of the focused window.
- Press C to close the focused window.
- Press A to lower the focused window to the bottom.
- Press X to cycle the focus through the windows.
- Press S to raise the lowest window to the top.
- Press P to enable and show the mouse cursor.
- Press R to rotate the focused window by 90 degree.
- Press E to focus the window currently under the mouse cursor,
useful in conjunction with 'X'.
- Press Escape to return from fullscreen mode to the desktop.
(currently not advisable if the fullscreen app is still flipping)
- Press F12 to redraw the whole window stack.
You might want to use the "capslock-meta" option (see directfbrc(5))
if you don't have a <Meta> key.
Documentation
-------------
A complete API reference documentation in HTML format is created during
the build in the docs directory. You may also access the API reference
as well as a concepts overview, tutorials and the FAQ online at
http://www.directfb.org/documentation/.
Thanks to
---------
Johannes Zellner <[email protected]>
Till Adam <[email protected]>
Joachim Steiger <[email protected]>
Felix von Leitner <[email protected]>
Johannes Stezenbach <[email protected]>
Michael Natterer <[email protected]>
Holger Waechtler <[email protected]>
Kim JeongHoe <[email protected]>
Jason Gaiser <[email protected]>
W. Michael Petullo <[email protected]>
Jiri Svoboda <[email protected]>
Hallvar Helleseth <[email protected]>
Topi Kanerva <[email protected]>
Daniel Mack <[email protected]>
Ara Hacopian <[email protected]>
Mike Haertel <[email protected]>
Enno Brehm <[email protected]>
Martin Mueller <[email protected]>
Sebastian Klemke <[email protected]>
Fredrik Hallenberg <[email protected]>
Antonino Daplas <[email protected]>
Scott A McConnell <[email protected]>
Alex SONG <[email protected]>
Ville Syrjälä <[email protected]>
Brian J. Murrell <[email protected]>
Tim Janik <[email protected]>
Billy Biggs <[email protected]>
Andreas Oberritter <[email protected]>
Simon Ueng <[email protected]>
Scott Brumbaugh <[email protected]>
Sebastian Ley <[email protected]>
James Su <[email protected]>
Sarma Kolluru <[email protected]>
Oliver Schwartz <[email protected]>
Florian <[email protected]>
J.P. Delport <[email protected]>
Michel Dänzer <[email protected]>
Maurizio Monge <[email protected]>
Tim Wright <[email protected]>
Liam Girdwood <[email protected]>
Andreas Robinson <andro134 at student.liu.se>
Michael Hunold <[email protected]>
Brandon M. Reynolds <[email protected]>
Micha Nelissen <[email protected]>
Vadim Catana <[email protected]>
Henning Glawe <[email protected]>
Ed Millard <[email protected]>
Claudio Ciccani <[email protected]>
Tom Bridgwater <[email protected]>
Oskar Liljeblad <[email protected]>
Bryce Nichols <[email protected]>
Stefan Lucke <[email protected]>
Mws <[email protected]>
Ivan Daniluk <[email protected]>
Mark Salter <[email protected]>
Martin Lütken <[email protected]>
Sylvain Meyer <[email protected]>
Mark Adams <[email protected]>
Damian Kowalewski <[email protected]>
Jakub Bogusz <[email protected]>
Nathanael D. Noblet <[email protected]>
Ryan Burns <[email protected]>
Colin Watson <[email protected]>
Guillem Jover <[email protected]>
Jeff Bailey <[email protected]>
Andreas Jochens <[email protected]>
Daniel J Laird <[email protected]>
Marko Mäkelä <[email protected]>
Nils Magnus Larsgard <[email protected]>
Pär Degerman <[email protected]>
Michel van Noorloos <[email protected]>
Gery <[email protected]>
Shane <[email protected]>
Paul Mackerras <[email protected]>
Attilio Fiandrotti <[email protected]>
Vaclav Slavik <[email protected]>
Philip Jägenstedt <[email protected]>
sridewa <[email protected]>
Eugene Everson <[email protected]>
Mike Crowe <[email protected]>
Kieran Bingham <[email protected]>
Luis Mondesi +lemsx1 +gmail,com
Keith Mok <[email protected]>
GARDET Guillaume <[email protected]>
Phil Endecott <[email protected]>
Brian Austin <[email protected]>
Keith Mok <[email protected]>
Young Hoon <[email protected]>
Special thanks to Ville Syrjala for his great work on the
Matrox TV-Out support and for his several patches including
fixes and enhancements for the whole library. He also did
several ports like UAE or mplayer for DirectFB. Check out his
site at 'http://www.sci.fi/~syrjala/'.
Legal stuff
-----------
(c) Copyright 2012-2013 DirectFB integrated media GmbH
(c) Copyright 2001-2013 The world wide DirectFB Open Source Community (directfb.org)
(c) Copyright 2000-2004 Convergence (integrated media) GmbH
All rights reserved.
Written by Denis Oliver Kropp <[email protected]>,
Andreas Shimokawa <[email protected]>,
Marek Pikarski <[email protected]>,
Sven Neumann <[email protected]>,
Ville Syrjälä <[email protected]> and
Claudio Ciccani <[email protected]>.
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the
Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.