Configuring DirectFB

 

From " http://www.directfb.eu/wiki/index.php/Configuring_DirectFB"

Configuring DirectFB

From DirectFBWiki

DirectFB has a lot of options that can be tuned run-time. Bit-depth, debug output, supported accelerator, disabling hardware acceleration, etcetera. This section aims at listing these options and how to apply them.

Table of contents [showhide]

1 Manual Page 2 Where to configure 3 What to configure 3.1 Syntax 3.2 Parameters 4 examples

Manual Page

The simplest source of information is the directfbrc manual mage.

man directfbrc                                                                                        

If this doesn't work, the content has been updated and summarised below. 

Where to configure

There are a number of locations where DirectFB will look for configuration information. The configuration information is read before any intialisation is done, to allow configuration to steer this process.

First, the following files are read (if they exist)

$(INSTALL_PATH)/etc/directfbrc                                                                

$(HOME)/.directfbrc                                                                                   

 $(INSTALL_PATH)/etc/directfb.$(PROGNAME)                                           

$(HOME)/.directfb.$(PROGNAME)                                                               

where $(PROGNAME) is the name of the program you want to run. In C-speak that's argc[0]. 

Second, it will check the following environment variables:

$(DFBARGS)
$(DIRECTFB_SESSION)

$(DIRECTFB_SESSION) is only used to obtain the session number. Finally it will parse command line options prepended with --dfb.

The last encountered entry takes precendence.

What to configure

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 page describes the positive variant and will also note which setting is the compiled-in default.

Parameters

system=<system>                                                                          

Specifies the graphics system to use. The default is to use the Linux frame buffer (fbdev). The following systems are recognised: fbdev, devmem, osx, sdl, vnc, x11. 

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.

For 'emulated' systems such as X11 this will specify the size of the DirectFB window.

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

[no-]force-slave                                                                            

Always enter as a slave, waiting for the master, if not there. By default the first app becomes master.

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 "memcpy=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.

[no-]banner                                                                               

Show DirectFB banner at startup.

[no-]quiet=<type>                                                                    

Suppresses console output from DirectFB. Only error messages will be displayed. type can be one or more of: info, warning, error, once, unimplemented. If you omit the type, supression affects all types.

[no-]debug=<domain>                                                              

Enables debug output. This is on by default but you won’t see any debug output unless you compiled DirectFB with debugging support by using --enable-debug. You can specify a debug domain to selectively enable or disable debug messages. If you omit the domain, this option will affect all domains.

[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 trace output unless you compiled DirectFB with trace support. This is a very processor heavy option and will instrument all function entry and exit points.

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 above, 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.

.BI [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 /fBlibdirectfb_/fP prefix and without extension (for example /fBkeyboard/fP 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.
• 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.

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.