    directfbrc \- DirectFB configuration file

    .SH DESCRIPTION

    The
    .B directfbrc
    file is a configuration file read by all DirectFB applications on startup.
    There are two of these: a system-wide one stored in
    .I /usr/local/etc/directfbrc
    and a per-user
    .I
    \fB$HOME\fP/.directfbrc
    which may override system settings.

    Further customization is available per executable (basename of argv[0]):
    .I /usr/local/etc/directfbrc.$0
    and a per-user
    .I
    \fB$HOME\fP/.directfbrc.$0

    After config files, the environment variable DFBARGS is parsed.

    The same parameters that can be used in the
    .B directfbrc
    file can be passed via this variable or on the command-line
    by prefixing them with
    .BR --dfb:
    separated each with a comma.

    .SH SYNTAX

    The
    .B 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.

    .SH PARAMETERS

    The following parameters may be specified in the
    .B directfbrc
    file:

    .TP
    .BI system=<system>
    .TP
    .BI mode=<width>x<height>
    Sets the default screen resolution. If unspecified DirectFB will use
    the first mode from
    .I /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.

    .TP
    .BI scaled=<width>x<height>
    Scale the window to this size for 'force-windowed' apps.

    .TP
    .BI depth=<pixeldepth>
    Sets the default pixel depth in bits per pixel. If unspecified
    DirectFB will use the depth specified in the first mode from
    .I /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.

    .TP
    .BI 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.

    .TP
    .BI 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".

    .TP
    .BI force-slave
    Always enter as a slave, waiting for the master, if not there.

    .TP
    .BI remote=<host>[:<session>]
    Select the remote session to connect to.

    .TP
    .BI 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.

    .TP
    .BI primary-only
    Tell application only about the primary layer.

    .TP
    .BI quiet
    Suppresses console output from DirectFB. Only error messages will be
    displayed.

    .TP
    .BI [no-]banner
    Enables the output of the DirectFB banner at startup. This is on by
    default.

    .TP
    .BI [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.

    .TP
    .BI [no-]debugmem
    Enable memory allocation tracking.

    .TP
    .BI [no-]debugshm
    Enable shared memory allocation tracking.

    .TP
    .BI [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.

    .TP
    .BI log-file=<name>
    Write all messages to the specified file.

    .TP
    .BI log-udp=<host>:<port>
    Send all messages via UDP to the specified host and port.

    .TP
    .BI fatal-level=<level>
    Abort on NONE, ASSERT (default) or ASSUME (incl. assert)

    .TP
    .BI 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.

    .TP
    .BI force-desktop
    .TP
    .BI [no-]dma
    Turns DMA acceleration on, if supported by the driver. By default
    DMA acceleration is off.

    .TP
    .BI [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.

    .TP
    .BI [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.

    .TP
    .BI [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.

    .TP
    .BI [no-]thrifty-surface-buffers
    Free sysmem instance on xfer to video memory.

    .TP
    .BI 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.

    .TP
    .BI [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.

    .TP
    .BI dont-catch=<num>[[,<num>]...]
    As described with the
    .B
    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.

    it.

    .TP
    .BI vt-num=<num>
    Use given VT instead of current/new one.

    .TP
    .BI [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.

    .TP
    .BI [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.

    .TP
    .BI [no-]vt
    Use VT handling code at all?

    .TP
    .BI mouse-source=<device>
    Specify the serial mouse device.

    .TP
    .BI [no-]mouse-gpm-source
    Enables using GPM as mouse input repeater.

    .TP
    .BI [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.

    .TP
    .BI mouse-protocol=<protocol>
    Specifies the mouse protocol to use. The following
    protocols are supported:

    .BI MS
    Two button mouse using the Microsoft mouse protocol.

    .BI MS3
    Three button mouse using an extended Microsoft mouse protocol.

    .BI MouseMan
    Three button mouse using a different extension to the Microsoft mouse
    protocol introduced by Logitech.

    .BI MouseSystems
    Swaps left and right mouse buttons. Useful for left-handers.

    .TP
    .BI [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).

    .TP
    .BI linux-input-ir-only
    Ignore all non-IR Linux Input devices.

    .TP
    .BI [no-]linux-input-grab
    Grab Linux Input devices. When a device is grabbed only DirectFB
    will receive events from it. The default is to not grab.

    .TP
    .BI [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.

    .TP
    .BI wm=<wm>
    Specify the window manager to use.

    .TP
    .BI bg-none
    Completely disables background handling. Doesn't make much sense since
    the mouse and moving windows will leave ugly traces on the background.

    .TP
    .BI 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.

    .TP
    .BI bg-image=<filename>
    Fills the background with the given image from file. The image is stretched
    to fit to the screen dimensions.

    .TP
    .BI bg-tile=<filename>
    Like
    .B bg-image
    but tiles the image to fit to the screen dimensions instead of
    stretching it.

    .TP
    .BI [no-]translucent-windows
    .TP
    .BI agpmem-limit=<amount>
    Limits the amount if AGP memory used by DirectFB. The amount of AGP
    memory is specified in Kilobytes.

    .TP
    .BI screenshot-dir=<directory>
    If specified DirectFB will dump the screen contents in PPM format
    into this directory when the <Print> key gets pressed.

    .TP
    .BI disable-module=<modulename>
    Suppress loading of this module. The module name is the filename
    without the \fBlibdirectfb_\fP prefix and without extension (for
    example \fBkeyboard\fP to disable loading of the keyboard input
    module).

    .TP
    .BI [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.

    .TP
    .BI [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.

    .TP
    .BI matrox-tv-standard=[pal|ntsc]
    Controls the signal produced by the TV output of Matrox cards.

    .TP
    .BI matrox-cable-type=(composite|scart-rgb|scart-composite)
    Matrox cable type (default=composite).

    .TP
    .BI h3600-device=<device>
    Use this device for the H3600 TS driver.

    .TP
    .BI mut-device=<device>
    Use this device for the MuTouch driver.

    .TP
    .BI penmount-device=<device>
    Use this device for the PenMount driver.

    .TP
    .BI linux-input-devices=<device>[[,<device>]...]
    Use these devices for the Linux Input driver.
    .BI window-surface-policy=<policy>
    Allows to control where window surfaces are stored. Supported values
    for <policy> are:

    .BI auto
    DirectFB decides depending on hardware capabilities. This is the
    default.

    .BI videohigh
    Swapping system/video with high priority.

    .BI videolow
    Swapping system/video with low priority.

    .BI systemonly
    Window surfaces are stored in system memory.

    .BI videoonly
    Window surfaces are stored in video memory.

    .TP
    .BI 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:

    .BI 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.

    .BI 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.

    .BI 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
    .BI vsync-after
    Wait for the vertical retrace after flipping. The default is to wait
    before doing the flip.

    .TP
    .BI vsync-none
    Disables polling for vertical retrace.

    .SH EXAMPLES

    Here are some examples that demonstrates how the parameters described
    above are passed to DirectFB application on the command-line.

    .TP
    .B df_neo --dfb:no-hardware
    Starts df_neo without hardware acceleration.
    .TP
    .B df_neo --dfb:help
    Lists the DirectFB options that can be passed to df_neo.

    .SH 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.

    .SH FILES

    .TP
    .I /usr/local/etc/directfbrc
    system-wide DirectFB configuration file
    .TP
    .I $HOME/.directfbrc
    per-user DirectFB configuration file
    .TP
    .I /etc/fb.modes
    frame buffer modes file

    .SH SEE ALSO
    .BR fb.modes (5),
    .BR fbset (8),
    .BR mouse (4),
    .BR ppm (5)