DIRECTFBRC(5)

📦
version 1.7.7 · 2 versions
, in alpine 3.24, debian bookworm, ubuntu jammy, ubuntu noble

🌸 directfbrc(5) — DirectFB Manual Pages 🌸

💖 NAME 💖

okay so directfbrc — the DirectFB configuration file. that's it, that's the whole vibe. 💅

✨ DESCRIPTION ✨

bestie. listen. the directfbrc file is a config file that every single DirectFB application reads on startup. no skipping, no exceptions, they all read it. 🫶

and there's not just one — there's two of them:

  • a system-wide one sitting in /etc/directfbrc
  • a per-user one at $HOME/.directfbrc which may override the system settings 👑

you want even more control? it's giving per-executable energy — you can customise based on the basename of argv[0]:

  • /etc/directfbrc.$0
  • a per-user $HOME/.directfbrc.$0

and after all the config files get read, the environment variable DFBARGS gets parsed. 🌈

the same parameters that work in the directfbrc file can be passed through that variable, or straight up on the command-line — just prefix them with --dfb: and separate each one with a comma. iconic honestly.

🎀 SYNTAX 🎀

the directfbrc file is one parameter per line. that's the whole rule. comments start with a hash sign (#) and keep going until the end of the line, and blank lines just get ignored like they don't even exist. 🙈

most parameters are switches that turn certain features on or off. these switches have a no- variant that disables the feature. this manpage describes the positive variant, and it will also note which setting is the compiled-in default. 💯

🔥 PARAMETERS 🔥

the following parameters may be specified in the directfbrc file:

  • system=<system> — picks the graphics system to use. default is the Linux frame buffer (fbdev), but you can also run DirectFB apps on SDL (sdl). other systems might get added in the future, no promises. 🔮
  • fbdev=<device> — opens the frame buffer device you name instead of /dev/fb0.
  • busid=<id> — specify the bus location of the card. this option only gets used if DirectFB doesn't have sysfs support, and if you leave it unspecified, 1:0:0 is assumed. use this if your driver fails to detect (or incorrectly detects) your card. the audacity of that driver. 😭
  • mode=<width>x<height> — sets the default screen resolution. if unspecified, DirectFB uses the first mode from /etc/fb.modes. heads up: some frame buffer devices (namely vesafb) don't support mode switches at all and can only be used in whatever resolution was set at boot time. 💀
  • scaled=<width>x<height> — scales the window to this size for 'force-windowed' apps.
  • depth=<pixeldepth> — sets the default pixel depth in bits per pixel. if unspecified, DirectFB uses 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 actually available depends on your frame buffer device. and again — some frame buffer devices (namely vesafb) don't support mode switches at all and can only be used in the pixel depth set at boot time. ✋
  • pixelformat=<pixelformat> — sets the default pixel format. this is similar to the depth parameter above but lets you be more fine-grained about it. possible values are LUT8, RGB332, RGB16, RGB24 and RGB32. some drivers may also support the more exotic ones: A8, ALUT44, ARGB, ARGB1555, I420, UYVY, YUY2 and YV12. fancy. 💅
  • session=<num> — selects the multi application world to join or create. starts at zero, and negative values force creation of a new world using the lowest unused session number. this will override the environment variable "DIRECTFB_SESSION". no cap.
  • force-slave — always enter as a slave, waiting for the master, if it's not there. loyalty. 🥺
  • remote=<host>[:<session>] — select the remote session to connect to.
  • tmpfs=<directory> — uses the given directory (a tmpfs mount point) for creation of the shared memory file in multi application mode. only useful if the automatic detection fails, or if you actually want non-tmpfs storage for some reason.
  • shmfile-group=<groupname> — the group that owns shared memory files.
  • memcpy=<method> — with this option, the probing of memcpy() routines can be skipped, which saves 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 one. check 'dfbinfo' for a list of layers supported by your hardware.
  • primary-only — tell the application only about the primary layer. gatekeeping, but make it config. 🚪
  • quiet — suppresses console output from DirectFB. only error messages will be displayed.
  • [no-]banner — enables the output of the DirectFB banner at startup. this one is on by default. 🎉
  • [no-]debug — enables debug output. 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. on by default, but you won't see any trace 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 lets you run applications that were written to do full-screen access inside a window. adorable, honestly. 🪟
  • 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 it, 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. slay, but slow. 🐌
  • [no-]software — this option allows you 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. useful if you're working with experimental device drivers and expect crashes. the default is not to sync. 🙏
  • [no-]mmx — the no-mmx option allows you to disable the use of MMX routines even if support for MMX was detected. by default, MMX is used if it's available and support for MMX was compiled in.
  • [no-]agp[=mode] — turns AGP memory support on. this option lets DirectFB use 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's the only format that ensures high quality, fast rendering and low memory consumption all at the same time. only use this option if your fonts look 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. with 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 lets you switch this feature on or off. mother behavior, honestly. 🧹
  • 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). main character energy, zero responsibilities. 👑
  • [no-]vt-switch — by default, DirectFB allocates a new virtual terminal and switches to it.
  • vt-num=<num> — use the given VT instead of the current/new one.
  • [no-]vt-switching — allow switching 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. the advantage here is that kernel messages won't show up on your screen while the DirectFB application is running. blessed silence. 🤫
  • [no-]vt — use VT handling code at all?
  • mouse-source=<device> — specify the serial mouse device.
  • [no-]mouse-gpm-source — enables using GPM as a mouse input repeater.
  • [no-]motion-compression — usually DirectFB compresses mouse motion events. this means subsequent mouse motions get delivered to the application as a single mouse motion event. the result is more responsive but less exact mouse handling. trade-offs, bestie. 🖱️
  • 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 — maps the CapsLock key to Meta. useful for users of the builtin WM without a Meta key on the keyboard (e.g. the 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 not to grab. 🙅‍♀️
  • [no-]cursor — by default, DirectFB shows a mouse cursor when an application makes use of windows. this option lets you switch the cursor off permanently. applications cannot enable it explicitly. sorry to them. 💀
  • wm=<wm> — tells DirectFB which window manager to use. Pick your fave and go 💅
  • bg-none — completely disables background handling. Honestly bestie, it doesn't make much sense, because the mouse and moving windows will leave ugly traces all over the background. 🙈
  • bg-color=AARRGGBB — controls the color of the background. It's specified in hexadecimal notation, and the alpha value defaults to full opacity, so you can just omit it. Wanna go bright magenta? You'd use bg-color=FF00FF. 💖
  • bg-image=<filename> — fills the background with the image from the given file. The image is stretched to fit the screen dimensions.
  • bg-tile=<filename> — same as bg-image, except it tiles the image to fit 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. Super handy if your graphics card doesn't support alpha-transparent blits.
  • [no-]decorations — enables window decorations if the window manager supports them. 🎀
  • videoram-limit=<amount> — limits how much Video RAM DirectFB uses. The amount of Video RAM is specified in Kilobytes.
  • agpmem-limit=<amount> — limits how much AGP memory DirectFB uses. The amount of AGP memory is specified in Kilobytes.
  • screenshot-dir=<directory> — if you specify this, DirectFB will dump the screen contents in PPM format into this directory whenever the <Print> key gets pressed. 📸
  • disable-module=<modulename> — suppresses loading of this module. The module name is the filename without the libdirectfb_ prefix and without extension — so for example keyboard to disable loading of the keyboard input module.
  • [no-]matrox-sgram — some older Matrox G400 cards have SGRAM, and a bunch of graphics operations are considerably faster on those cards if this feature is enabled.
Do not 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> — lets you control where window surfaces are stored. The 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> — lets you 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. It does this by blitting together the windows 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 isn't visible, since only the final result is copied into the front buffer. Without a back buffer, every step of the recomposition is visible. That causes noticeable flicker unless all windows are opaque.

The 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 recommended 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 demonstrate how the parameters described above are passed to a 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/. Over there you can find the FAQ, tutorials, mailing list archives, the CVS tree, and you can download the latest version of the DirectFB library as well as a number of applications. One-stop shop, fr fr. 🦋

📁 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)

And that's a wrap on the whole page, bestie — Version 1.7.7, dated 03 Mar 2007, and it still ate. 💜

📦 where this page comes from