README 12.8 KB
Newer Older
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
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 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-rw----    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, but additionally /dev/fusion/0 and the shared memory,
   e.g. '/dev/shm/fusion.0'. You should start the master as a normal user,
   but have the binary suid root, i.e. 'chown root' and 'chmod u+s'. This way
   the shared memory file is created in the group of the user that started the
   master.

   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 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
   lead to better performance and decent 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). Note that you don't need to patch
   your kernel using the CVS version of Fusion.

   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 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
	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 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 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.
     - Press E to focus the window currently under the mouse cursor,
       useful in conjunction with 'X'.

   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 <johannes@zellner.org>
   Till Adam <till@adam-lilienthal.de>
   Joachim Steiger <roh@hyte.de>
   Felix von Leitner <leitner@fefe.de>
   Johannes Stezenbach <js@convergence.de>
   Michael Natterer <mitch@convergence.de>
   Holger Waechtler <holger@convergence.de>
   Kim JeongHoe <king@mizi.com>
   Jason Gaiser <jasno@san.rr.com>
   W. Michael Petullo <mike@flyn.org>
   Jiri Svoboda <Jiri.Svoboda@seznam.cz>
   Hallvar Helleseth <hallvar@ii.uib.no>
   Topi Kanerva <topi.kanerva@eke.fi>
   Daniel Mack <daniel@convergence.de>
   Ara Hacopian <ahacop@anthrotronix.com>
   Mike Haertel <mike@albert.ai.mit.edu>
   Enno Brehm <enno@convergence.de>
   Martin Mueller <mm@convergence.de>
   Sebastian Klemke <packet@convergence.de>
   Fredrik Hallenberg <hallon@lysator.liu.se>
   Antonino Daplas <adaplas@users.sourceforge.net>
   Scott A McConnell <samcconn@cotw.com>
   Alex SONG <zzaleson@uqconnect.net>
   Ville Syrjälä <syrjala@sci.fi>
   Brian J. Murrell <a40e8119bbddbe7b3d281db117f19b32@interlinx.bc.ca>
   Tim Janik <timj@gtk.org>
   Billy Biggs <vektor@dumbterm.net>
   Andreas Oberritter <obi@tuxbox.org>
   Simon Ueng <simon@ftech.com.tw>
   Scott Brumbaugh <scottb.lists@verizon.net>
   Sebastian Ley <sebastian.ley@mmweg.rwth-aachen.de>
   James Su <suzhe@turbolinux.com.cn>
   Sarma Kolluru <Sarma.Kolluru@nsc.com>
   Oliver Schwartz <Oliver.Schwartz@gmx.de>
   Florian <florian.fernandez2@wanadoo.fr>
   J.P. Delport <jpdelport@csir.co.za>
   Michel Dänzer <michel@daenzer.net>
   Maurizio Monge <monge@sns.it>
   Tim Wright <tim.wright@iosystems.co.uk>
   Liam Girdwood <liam.girdwood@wolfsonmicro.com>
   Andreas Robinson <andro134 at student.liu.se>
   Michael Hunold <hunold@convergence.de>

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 2000-2002  convergence integrated media GmbH.
   (c) Copyright 2002-2003  convergence GmbH.
   All rights reserved.

   Written by Denis Oliver Kropp <dok@directfb.org> and
              Andreas Hundt <andi@fischlustig.de> and
              Sven Neumann <neo@directfb.org>.

   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.