The Qt Virtual Framebuffer

Qt comes with a handy tool that lives a rather anonymous life in the tools/qvfb directory. This tool does wonders when it comes to demoing, training users and creating documentation.

The QVFb, or Qt Virtual Framebuffer, is a tool that makes it possible to run Qt applications on a virtual system with a limited screen resolution, limited bit-depth, and with limited input abilities. All of this on your desktop (or laptop) PC, saving you the hazzles of cross-platform debugging, cross-compiling, transfering files to the target, etc.

The trick with the QVFb is not really how to use it, but rather, how to build it. It is interesting enough that I've actually given a number of speeches on it. The problem is not that it is difficult to build, rather, that you have to build Qt two times to get a working environment.

When building Qt, the result of the configure script is a binary: qmake. This binary processes *.pro files and builds target specific Makefiles. The qmake tool carries your configuration, so if you are targetting two systems with your Qt project, you will have to run "make distclean" followed by "qmake-target" to aim your project at a specific target (where "qmake-target" can be "qmake-x11", "qmake-osx", "qmake-arm-fb", etc).

With this knowledge, and some careful thought when configuring Qt (do not forget to use the -prefix option to avoid having three Qt installs in one directory), building QVFb is quite easy.

I usually build three instances of Qt when targeting an embedded system - all with roughly the same configuration. This is to make sure that what I test on my PC also works on my target. The Qt builds are:

  • Qt for host/X11 - used to build the Qt tools for the host machine.
  • Qt for target/fb - used to build the actual target files.
  • Qt for host/qvfb - used to build binaries for QVFb.

Qt for host/X11 is simple, just build Qt as you usually do. However, when you have built it, cd into tools/qvfb and do "make && make install" for QVFb as well.

Qt for target/fb can be a completely different story. It's usually dead simple to build Qt for your target. However, as we all know, the devil lives in the details. This build can be tuned in so many ways that this is one of the things I do for a living.

Qt for host/qvfb is basically Qt for target/fb, but for the host machine. I also make sure to include graphics and input drivers for QVFb. This means adding -qt-gfx-qvfb, -qt-kbd-qvfb and -qt-mouse-qvfb to the configure command line.

Having built and installed all these versions of Qt (where Qt for target/fb is optional when experimenting), you can start QVFb, setup a screen size, bit depth and input limitations. You can also add a skin, e.g. if your hardware includes a frame with buttons on it. QVFb can translate mouse clicks on these off-screen buttons into keyboard events. Having setup QVFb, simply compile your application with Qt for host/qvfb and start it with the -qws switch as an argument. Now you're running your application inside the virtual framebuffer on your host machine.


Johan Thelin is a consultant working with Qt, embedded and free
software. On-line, he is known as e8johan.

Geek Guide
The DevOps Toolbox

Tools and Technologies for Scale and Reliability
by Linux Journal Editor Bill Childers

Get your free copy today

Sponsored by IBM

Upcoming Webinar
8 Signs You're Beyond Cron

Scheduling Crontabs With an Enterprise Scheduler
11am CDT, April 29th
Moderated by Linux Journal Contributor Mike Diehl

Sign up now

Sponsored by Skybot