NAME¶
directfbrc - DirectFB configuration file
DESCRIPTION¶
The
directfbrc file is a configuration file read by all DirectFB
applications on startup. There are two of these: a system-wide one stored in
/etc/directfbrc and a per-user
$HOME/.directfbrc which
may override system settings.
Further customization is available per executable (basename of argv[0]):
/etc/directfbrc.$0 and a per-user
$HOME/.directfbrc.$0
After config files, the environment variable DFBARGS is parsed.
The same parameters that can be used in the
directfbrc file can be passed
via this variable or on the command-line by prefixing them with
--dfb:
separated each with a comma.
SYNTAX¶
The
directfbrc file contains one parameter per line. Comments are
introduced by a hash sign (#), and continue until the end of the line. Blank
lines are ignored.
Most parameters are switches that turn certain features on or off. These
switches have a no- variant that disables the feature. This man-page describes
the positive variant and will also note which setting is the compiled-in
default.
PARAMETERS¶
The following parameters may be specified in the
directfbrc file:
- system=<system>
- Specifies the graphics system to use. The default is to use
the Linux frame buffer (fbdev) but you can also run DirectFB applications
on SDL (sdl). Other systems might be added in the future.
- fbdev=<device>
- Opens the given frame buffer device instead of /dev/fb0.
- busid=<id>
- Specify the bus location of the card. The option is only
used if DirectFB doesn't have sysfs support and if unspecified 1:0:0 will
be assumed. Use this option if the driver fails to detect (or incorrectly
detects) your card.
- mode=<width>x<height>
- Sets the default screen resolution. If unspecified DirectFB
will use the first mode from /etc/fb.modes Some frame buffer
devices (namely vesafb) don't support mode switches and can only be used
in the resolution that is set on boot time.
- scaled=<width>x<height>
- Scale the window to this size for 'force-windowed' apps.
- depth=<pixeldepth>
- Sets the default pixel depth in bits per pixel. If
unspecified DirectFB will use the depth specified in the first mode from
/etc/fb.modes DirectFB supports color depths of 8, 15, 16, 24 and
32. Which values are available depends on the frame buffer device you are
using. Some frame buffer devices (namely vesafb) don't support mode
switches at all and can only be used in the pixel depth that is set at
boot time.
- pixelformat=<pixelformat>
- Sets the default pixel format. This is similar to the depth
parameter described above but allows more fine-grained control. Possible
values for pixelformat are LUT8, RGB332, RGB16, RGB24 and RGB32. Some
drivers may also support the more exotic pixel formats A8, ALUT44, ARGB,
ARGB1555, I420, UYVY, YUY2 and YV12.
- session=<num>
- Selects the multi application world which is joined or
created. Starting with zero, negative values force creation of a new world
using the lowest unused session number. This will override the environment
variable "DIRECTFB_SESSION".
- force-slave
- Always enter as a slave, waiting for the master, if not
there.
- remote=<host>[:<session>]
- Select the remote session to connect to.
- tmpfs=<directory>
- Uses the given directory (tmpfs mount point) for creation
of the shared memory file in multi application mode. This option is only
useful if the automatic detection fails or if non-tmpfs storage is
desired.
- shmfile-group=<groupname>
- Group that owns shared memory files.
- memcpy=<method>
- With this option the probing of memcpy() routines can be
skipped, saving a lot of startup time. Pass "help" for a list of
possible values.
- primary-layer=<id>
- Selects which layer is the "primary layer",
default is the first. Check 'dfbinfo' for a list of layers supported by
your hardware.
- primary-only
- Tell application only about the primary layer.
- quiet
- Suppresses console output from DirectFB. Only error
messages will be displayed.
- [no-]banner
- Enables the output of the DirectFB banner at startup. This
is on by default.
- [no-]debug
- Enables debug output. This is on by default but you won't
see any debug output unless you compiled DirectFB with debugging support.
- [no-]debugmem
- Enable memory allocation tracking.
- [no-]debugshm
- Enable shared memory allocation tracking.
- [no-]trace
- Enable stack trace support. This is on by default but you
won't see any trcae output unless you compiled DirectFB with trace
support.
- log-file=<name>
- Write all messages to the specified file.
- log-udp=<host>:<port>
- Send all messages via UDP to the specified host and port.
- fatal-level=<level>
- Abort on NONE, ASSERT (default) or ASSUME (incl. assert)
- force-windowed
- Forces the primary surface to be a window. This allows to
run applications that were written to do full-screen access in a window.
- force-desktop
- Forces the primary surface to be the background surface of
the desktop.
- [no-]hardware
- Turns hardware acceleration on. By default hardware
acceleration is auto-detected. If you disable hardware acceleration, the
driver for your graphics card will still be loaded and used to access
additional display layers (if there are any), but all graphics operations
will be performed by the software renderer.
- [no-]software
- This option allows to disable software fallbacks.
- [no-]dma
- Turns DMA acceleration on, if supported by the driver. By
default DMA acceleration is off.
- [no-]sync
- Flushes all disk buffers before initializing DirectFB. This
can be useful if you working with experimental device drivers and expect
crashes. The default is not to sync.
- [no-]mmx
- The no-mmx options allows to disable the use of MMX
routines even if support for MMX was detected. By default MMX is used if
is available and support for MMX was compiled in.
- [no-]agp[=mode]
- Turns AGP memory support on. The option enables DirectFB
using the AGP memory to extend the amount of video memory available. You
can specify the AGP mode to use (e.g. 1, 2, 4, 8 or 0 to disable agp). By
default AGP memory support is off.
- [no-]thrifty-surface-buffers
- Free sysmem instance on xfer to video memory.
- font-format=<format>
- Specify the font format to use. Possible values are A1, A8,
ARGB, ARGB1555, ARGB2554, ARGB4444, AiRGB. The default font format is A8
because it is the only format that ensures high quality, fast rendering
and low memory consumption at the same time. Use this option only if your
fonts looks strange or if font rendering is too slow.
- [no-]sighandler
- By default DirectFB installs a signal handler for a number
of signals that cause an application to exit. This signal handler tries to
deinitialize the DirectFB engine before quitting the application. Use this
option to enable/disable this feature.
- dont-catch=<num>[[,<num>]...]
- As described with the sighandler option, DirectFB
installs a signal handler for a number of signals. By using this option
you may specify a list of signals that shouldn't be handled this way.
- [no-]deinit-check
- By default DirectFB checks if the application has released
all allocated resources on exit. If it didn't, it will clean up after the
application. This option allows to switch this feature on or off.
- block-all-signals
- This option activates blocking of all signals, useful for
DirectFB daemons (a DirectFB master application that does nothing except
being the master).
- [no-]vt-switch
- By default DirectFB allocates a new virtual terminal and
switches to it.
- vt-num=<num>
- Use given VT instead of current/new one.
- [no-]vt-switching
- Allow to switch virtual terminals using
<Ctrl>+<Alt>+<F?>. This is an experimental feature that
is usually disabled; use at your own risk.
- [no-]graphics-vt
- Puts the virtual terminal into graphics mode. This has the
advantage that kernel messages won't show up on your screen while the
DirectFB application is running.
- [no-]vt
- Use VT handling code at all?
- mouse-source=<device>
- Specify the serial mouse device.
- [no-]mouse-gpm-source
- Enables using GPM as mouse input repeater.
- [no-]motion-compression
- Usually DirectFB compresses mouse motion events. This means
that subsequent mouse motions are delivered to the application as a single
mouse motion event. This leads to a more responsive but less exact mouse
handling.
- mouse-protocol=<protocol>
- Specifies the mouse protocol to use. The following
protocols are supported:
MS Two button mouse using the Microsoft mouse protocol.
MS3 Three button mouse using an extended Microsoft mouse protocol.
MouseMan Three button mouse using a different extension to the
Microsoft mouse protocol introduced by Logitech.
MouseSystems The most commonly used protocol for three button mice.
PS/2 Two/three button mice of the PS/2 series.
IMPS/2 Two/three button USB mice with scrolling wheel using the
Microsoft Intellimouse protocol.
The different protocols for serial mice are described in more detail in
mouse(4).
- [no-]lefty
- Swaps left and right mouse buttons. Useful for
left-handers.
- [no-]capslock-meta
- Map the CapsLock key to Meta. Useful for users of the
builtin WM without a Meta key on the keyboard (e.g. Window key).
- linux-input-ir-only
- Ignore all non-IR Linux Input devices.
- [no-]linux-input-grab
- Grab Linux Input devices. When a device is grabbed only
DirectFB will receive events from it. The default is to grab.
- [no-]cursor
- By default DirectFB shows a mouse cursor when an
application makes use of windows. This option allows to switch the cursor
off permanently. Applications cannot enable it explicitly.
- wm=<wm>
- Specify the window manager to use.
- bg-none
- Completely disables background handling. Doesn't make much
sense since the mouse and moving windows will leave ugly traces on the
background.
- bg-color=AARRGGBB
- Controls the color of the background. The color is
specified in hexadecimal notation. The alpha value defaults to full
opacity and may be omitted. For example to choose a bright magenta
background, you'd use bg-color=FF00FF.
- bg-image=<filename>
- Fills the background with the given image from file. The
image is stretched to fit to the screen dimensions.
- bg-tile=<filename>
- Like bg-image but tiles the image to fit to the
screen dimensions instead of stretching it.
- [no-]translucent-windows
- By default DirectFB windows may be translucent. If you
disable this feature, windows are forced to be either fully opaque or
fully transparent. This is useful if your graphics card doesn't support
alpha-transparent blits.
- [no-]decorations
- Enables window decorations if supported by the window
manager.
- videoram-limit=<amount>
- Limits the amount of Video RAM used by DirectFB. The amount
of Video RAM is specified in Kilobytes.
- agpmem-limit=<amount>
- Limits the amount if AGP memory used by DirectFB. The
amount of AGP memory is specified in Kilobytes.
- screenshot-dir=<directory>
- If specified DirectFB will dump the screen contents in PPM
format into this directory when the <Print> key gets pressed.
- disable-module=<modulename>
- Suppress loading of this module. The module name is the
filename without the libdirectfb_ prefix and without extension (for
example keyboard to disable loading of the keyboard input module).
- [no-]matrox-sgram
- Some older Matrox G400 cards have SGRAM and a number of
graphics operations are considerably faster on these cards if this feature
is enabled. Don't try to enable it if your card doesn't have SGRAM!
Otherwise you'd have to reboot.
- [no-]matrox-crtc2
- If you have a dual head G400/G450/G550 you can use this
option to enable additional layers using the second head.
- matrox-tv-standard=[pal|ntsc]
- Controls the signal produced by the TV output of Matrox
cards.
- matrox-cable-type=(composite|scart-rgb|scart-composite)
- Matrox cable type (default=composite).
- h3600-device=<device>
- Use this device for the H3600 TS driver.
- mut-device=<device>
- Use this device for the MuTouch driver.
- penmount-device=<device>
- Use this device for the PenMount driver.
- linux-input-devices=<device>[[,<device>]...]
- Use these devices for the Linux Input driver.
- tslib-devices=<device>[[,<device>]...]
- Use these devices for the tslib driver.
- unichrome-revision=<revision>
- Override the hardware revision number used by the Unichrome
driver.
- i8xx_overlay_pipe_b
- Redirect videolayer to pixelpipe B.
- window-surface-policy=<policy>
- Allows to control where window surfaces are stored.
Supported values for <policy> are:
auto DirectFB decides depending on hardware capabilities. This is the
default.
videohigh Swapping system/video with high priority.
videolow Swapping system/video with low priority.
systemonly Window surfaces are stored in system memory.
videoonly Window surfaces are stored in video memory.
- desktop-buffer-mode=<mode>
- Allows to control the desktop buffer mode. Whenever a
window is moved, opened, closed, resized or its contents change DirectFB
recomposites the window stack at the affected region. This is done by
blitting the windows together that are visible within that region. Opaque
windows are blitted directly while translucent windows are blitted using
alpha blending or color keying. If there's a back buffer the recomposition
is not visible since only the final result is copied into the front
buffer. Without a back buffer each step of the recomposition is visible.
This causes noticeable flicker unless all windows are opaque.
Supported values for <mode> are:
auto DirectFB decides depending on hardware capabilities. This is the
default. DirectFB chooses a back buffer in video memory if the hardware
supports simple blitting (copying from back to front buffer). If there's
no acceleration at all the back buffer is allocated in system memory since
that gives much better performance for alpha blended recomposition in
software and avoids reading from the video memory when the result is
copied to the front buffer.
backsystem The back buffer is allocated in system memory. This is the
recommend choice if your hardware supports simple blitting but no alpha
blending and you are going to have many alpha blended windows.
backvideo Front and back buffer are allocated in video memory. It's
not required to set this mode explicitly because the 'auto' mode chooses
it if blits are accelerated. Without accelerated blits this mode is not
recommended.
triple Like backvideo except the surface is triple buffered.
frontonly There is no back buffer. This is the best choice if you are
using opaque windows only and don't use any color keying.
windows Special mode with window buffers directly displayed. This
mode requires special hardware support.
- vsync-after
- Wait for the vertical retrace after flipping. The default
is to wait before doing the flip.
- vsync-none
- Disables polling for vertical retrace.
EXAMPLES¶
Here are some examples that demonstrates how the parameters described above are
passed to DirectFB application on the command-line.
- df_neo --dfb:no-hardware
- Starts df_neo without hardware acceleration.
- df_neo --dfb:help
- Lists the DirectFB options that can be passed to df_neo.
OTHER INFO¶
The canonical place to find informations about DirectFB is at
http://www.directfb.org/. Here you can find the FAQ, tutorials, mailing list
archives, the CVS tree and can download the latest version of the DirectFB
library as well as a number of applications.
FILES¶
- /etc/directfbrc
- system-wide DirectFB configuration file
- $HOME/.directfbrc
- per-user DirectFB configuration file
- /etc/fb.modes
- frame buffer modes file
SEE ALSO¶
fb.modes(5),
fbset(8),
mouse(4),
ppm(5)