DirectFB README --------------- This is a developers release of DirectFB. 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 (tested on FreeBSD 4.7) - NetBSD (tested on NetBSD 1.6) - OpenBSD (tested on OpenBSD 3.2) (If you have problems, try ./configure --disable-mmx) Support for the following operating systems are in progress, but still have problems: - Mac OS X (tested on Mac OS X 10.2.1, problems with SDL input and windows) Please note that SDL support is experimental and incomplete. It is intended for developers to allow development of DirectFB applications in various environments. 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 version regularly, your help is greatly appreciated. Build Requirements ------------------ - Linux kernel 2.2.x or newer with working frame buffer device (check /proc/fb) for the fbdev system. - Optionally SDL (Simple Direct Media Layer) for the sdl system. - freetype (version >= 2.0.1) - libjpeg62 - libpng2 or libpng3 - zlib 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. To access the frame buffer device and the mouse you 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-rw---- 1 root tty 4, 0 /dev/tty0 Some applications from the DirectFB-examples package have additional requirements: - A video card supported by video4linux for df_video. - A joystick for df_joystick. 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 make make install (as superuser) Use 'configure --help' to get a list of possible configure options. 2) Make sure that /usr/local/lib is listed in your /etc/ld.so.conf. If you added it you have to run 'ldconfig' as superuser. 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 /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 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 try the vsync patch found in the patches directory that enables applications to "idle wait" for the vertical retrace. 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 for multiple DirectFB applications to run at the same time. Please note that this is still considered experimental. You have been warned! DirectFB applications communicate through a layer we called 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 leads to better performance and more stability. To install this kernel module (only available for Linux yet), check out the linux-fusion module from our CVS repository or use the patch provided by this release (in the patches directory). 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 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 repository). You can then start DirectFB applications from dfbterm. 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 (or Windows) key or alternatively you can do the following: - Drag your mouse to move the focused window. - Drag and press to resize the focused window. - Drag and press 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 S to raise the focused window to the top. - Press X to cycle the focus through the windows. - Press P to enable and show the mouse cursor. You might want to use the "capslock-meta" option (see directfbrc(5)) if you don't have a 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 Till Adam Joachim Steiger Felix von Leitner Johannes Stezenbach Michael Natterer Holger Waechtler Kim JeongHoe Jason Gaiser W. Michael Petullo Jiri Svoboda Hallvar Helleseth Topi Kanerva Daniel Mack Ara Hacopian Mike Haertel Enno Brehm Martin Mueller Sebastian Klemke Fredrik Hallenberg Antonino Daplas Scott A McConnell Alex SONG Ville Syrjala Brian J. Murrell Tim Janik Billy Biggs Andreas Oberritter Legal stuff ----------- (c) Copyright 2000-2002 convergence integrated media GmbH. (c) Copyright 2002 convergence GmbH. All rights reserved. Written by Denis Oliver Kropp and Andreas Hundt and Sven Neumann . 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. The complete text of the license is found in the file COPYING.