Qtopia Home - Classes - Hierachy - Annotated - Functions - Licenses - Reference

Qt/Embedded Virtual Framebuffer

Introduction

QT Virtual Framebuffer (QVFb) is provided as part of a standard distribution package. QVFb allows Qt/Embedded programs to be developed on a desktop machine, without having to switch between consoles and X11. It runs as a normal X application on a desktop machine but provides a virtual framebuffer to Qt/Embedded applications. Linux devices write to the screen using a framebuffer and QVFb emulates this behavior.

When QVFb is started it creates files that the Qt/Embedded application detects and uses to connect to QVFb. This is the same behavior used if the files were on a real device connected to the framebuffer, so to the application running on QVFb there is no difference.

If an embedded application is run on the desktop without using QVFb the screen has spurious behavior. The display may appear as if it is being attacked by a virus and any information displayed will make no sense. If this occurs follow these steps:

  1. close Qtopia by using, for example, Ctrl-C
  2. start QVFb
  3. rerun the embedded application

QVFb is located in $QTDIR/tools/qvfb and is a development tool only. No security issues have been considered and it should not be used in a production environment. To safeguard the production environment the variable QT_NO_QWS_VFB should always be defined in production libraries.

Framebuffer Design and Refresh Rate

The virtual framebuffer emulates a framebuffer by using a shared memory region (the virtual frame buffer) and a utility to display the framebuffer in a window (QVFb). Any changed regions of the display are updated periodically, so discrete snapshots of the framebuffer are viewed rather than each individual drawing operation. For this reason drawing issues such as flickering may not be apparent until the program is run using a real framebuffer.

To check for updated regions more quickly the target refresh rate needs to be set via the View->Refresh Rate menu item. The rate is a target only and if little drawing is being done, the framebuffer will not show any updates between drawing events. If an application is displaying an animation the updates will be frequent, and the application and QVFb will compete for processor time.

Mouse and keyboard events are passed to the Qt/Embedded master process via named pipes.

Using QVFb

To use QVFb do the following:

Command Line Options

QVFb supports the following command line options:

Option Explanation
 -width width 
The width of the virtual framebuffer (default: 240).
 -height height
The height of the virtual framebuffer (default: 320).
 -depth depth
The depth of the virtual framebuffer (1, 4, 8 or 32, default: 8).
 -nocursor
Do not display the X11 cursor in the framebuffer window.
 -qwsdisplay :id
The Qt/Embedded display id to provide (default :0).

Modifying QVFb Using Skins

By default QVFb looks rather boring. A rectangular area with a border represents the screen of a device. It does not contain any buttons that are usually found on the device and does not look realistic.

QVFb supports a feature known as a skin which is used to change the look and feel of the display. A skin is a set of XML and pixmap files that tell the QVFb how it should look and how it should behave. So a skin can change the unrealistic display into a display that isidentical to the device being devolped. A skin can have buttons and when you click on the button a signal will be send to the Qtopia application running inside QVFb, just as would happen on a real device.

Understanding the .skin File

The .skin file comprises:

Co-ordinates

The co-ordinates are a list of at least 2 points in clockwise order that define a shape for the button. Two points are treated as opposite edges of a rectangle and a click inside the points will be treated as a click on that button. While pressed, the pixels for the button are redrawn from the activated skin.

For reference see: SmartPhone.skin and SmartPhone2.skin in $QTDIR/tools/QVFB.

Configuration File : defaultbuttons.conf

The configuration file defaultbuttons.conf provides the following functionality:

Specifying Screen Size Independent of Skin

QVFb allows the screen size to be specified independently of the skin. For example, you can use the SmartPhone.skin but specify a screen size of 240x320 pixels. The skin (if command-line arguments are used) or screen (if Configure is used) will be scaled accordingly. For example:

 QVFB -skin SmartPhone.skin -width 240 -height 320 -zoom 0.7 

The above example uses the SmartPhone.skin (screen area 176x208 skin pixels) but with a 240x320 pixel virtual framebuffer. The screen is scaled down by 0.7 resulting in a display that is a smooth-scaled 168x224 pixels.

Note: The SmartPhone.skin is 176x208, not 3:4 which means that 3:4 pixel screens are slightly distorted (but still pixel-correct).

Troubleshooting


Copyright © 2005 Trolltech Trademarks
Qtopia version 2.2.0