<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- emb-qvfb.qdoc -->
<title>Qt 4.8: The Virtual Framebuffer</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>The Virtual Framebuffer</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#displaying-the-virtual-framebuffer">Displaying the Virtual Framebuffer</a></li>
<li class="level2"><a href="#skins">Skins</a></li>
<li class="level2"><a href="#the-file-menu">The File Menu</a></li>
<li class="level2"><a href="#the-view-menu">The View Menu</a></li>
<li class="level1"><a href="#running-applications-using-the-virtual-framebuffer">Running Applications Using the Virtual Framebuffer</a></li>
</ul>
</div>
<h1 class="title">The Virtual Framebuffer</h1>
<span class="subtitle"></span>
<!-- $$$qvfb.html-description -->
<div class="descr"> <a name="details"></a>
<p><a href="qt-embedded-linux.html">Qt for Embedded Linux</a> applications write directly to the framebuffer, eliminating the need for the X Window System and saving memory. For development and debugging purposes, a virtual framebuffer can be used, allowing <a href="qt-embedded-linux.html">Qt for Embedded Linux</a> programs to be developed on a desktop machine, without switching between consoles and X11.</p>
<p>QVFb is an X11 application supplied with Qt for X11 that provides a virtual framebuffer for Qt for Embedded Linux to use. To use it, you need to <a href="install-x11.html">configure and install Qt for X11 platforms</a> appropriately. Further requirements can be found in the <a href="requirements-embedded-linux.html">Qt for Embedded Linux Requirements</a> document.</p>
<p class="centerAlign"><img src="images/qt-embedded-virtualframebuffer.png" alt="" /></p><p>The virtual framebuffer emulates a framebuffer using a shared memory region and the <tt>qvfb</tt> tool to display the framebuffer in a window. The <tt>qvfb</tt> tool also supports a feature known as a skin which can be used to change the look and feel of the display. The tool is located in Qt's <tt>tools/qvfb</tt> directory, and provides several additional features accessible through its <b>File</b> and <b>View</b> menus.</p>
<p>Please note that the virtual framebuffer is a development tool only. No security issues have been considered in the virtual framebuffer design. It should be avoided in a production environment; i.e. do not configure production libraries with the <tt>-qvfb</tt> option.</p>
<a name="displaying-the-virtual-framebuffer"></a>
<h2>Displaying the Virtual Framebuffer</h2>
<p>To run the <tt>qvfb</tt> tool displaying the virtual framebuffer, the <a href="qt-embedded-linux.html">Qt for Embedded Linux</a> library must be configured and compiled with the <tt>-qvfb</tt> option:</p>
<pre class="cpp"> cd path/to/QtEmbedded
./configure -qvfb
make</pre>
<p>Ensure that you have all the <a href="requirements-embedded-linux.html#additional-x11-libraries-for-qvfb">necessary libraries</a> needed to build the tool, then compile and run the <tt>qvfb</tt> tool as a normal Qt for X11 application (i.e., do <i>not</i> compile it as a <a href="qt-embedded-linux.html">Qt for Embedded Linux</a> application):</p>
<pre class="cpp"> cd path/to/Qt/tools/qvfb
make
./qvfb</pre>
<p>The <tt>qvfb</tt> application supports the following command line options:</p>
<table class="generic">
<thead><tr class="qt-style"><th >Option</th><th >Description</th></tr></thead>
<tr valign="top" class="odd"><td ><tt>-width <value></tt></td><td >The width of the virtual framebuffer (default: 240).</td></tr>
<tr valign="top" class="even"><td ><tt>-height <value></tt></td><td >The height of the virtual framebuffer (default: 320).</td></tr>
<tr valign="top" class="odd"><td ><tt>-depth <value></tt></td><td >The depth of the virtual framebuffer (1, 8 or 32; default: 8).</td></tr>
<tr valign="top" class="even"><td ><tt>-nocursor</tt></td><td >Do not display the X11 cursor in the framebuffer window.</td></tr>
<tr valign="top" class="odd"><td ><tt>-qwsdisplay <:id></tt></td><td >The <a href="qt-embedded-linux.html">Qt for Embedded Linux</a> display ID (default: 0).</td></tr>
<tr valign="top" class="even"><td ><tt>-skin <name>.skin</tt></td><td >The preferred skin. Note that the skin must be located in Qt's <tt>/tools/qvfb/</tt> directory.</td></tr>
<tr valign="top" class="odd"><td ><tt>-zoom <factor></tt></td><td >Scales the application view with the given factor.</td></tr>
</table>
<a name="skins"></a>
<h3>Skins</h3>
<p>A skin is a set of XML and pixmap files that tells the vitual framebuffer what it should look like and how it should behave; a skin can change the unrealistic default display into a display that is similar to the target device. To access the <tt>qvfb</tt> tool's menus when a skin is activated, right-click over the display.</p>
<p>Note that a skin can have buttons which (when clicked) send signals to the Qt Extended application running inside the virtual framebuffer, just as would happen on a real device.</p>
<table class="generic" width="100%">
<tr valign="top" class="odd"><td ><b>Target Device Environment</b><p>The <tt>qvfb</tt> tool provides various skins by default, allowing the user to view their application in an environment similar to their target device. The provided skins are:</p>
<ul>
<li>ClamshellPhone</li>
<li>PortableMedia</li>
<li>S60-nHD-Touchscreen</li>
<li>S60-QVGA-Candybar</li>
<li>SmartPhone</li>
<li>SmartPhone2</li>
<li>SmartPhoneWithButtons</li>
<li>TouchscreenPhone</li>
</ul>
<p>In addition, it is possible to create custom skins.</p>
</td><td ><p class="centerAlign"><img src="images/qt-embedded-phone.png" alt="" /></p></td><td ><p class="centerAlign"><img src="images/qt-embedded-pda.png" alt="" /></p></td></tr>
</table>
<p><b>Creating Custom Skins</b></p>
<p>The XML and pixmap files specifying a custom skin must be located in subdirectory of the Qt's <tt>/tools/qvfb</tt> directory, called <tt>/customskin.skin</tt>. See the ClamshellPhone skin for an example of the file structure:</p>
<pre class="cpp"> cd path/to/Qt/tools/qvfb/ClamshellPhone.skin/</pre>
<p>The <tt>/ClamshellPhone.skin</tt> directory contains the following files:</p>
<ul>
<li><tt>ClamshellPhone.skin</tt></li>
<li><tt>ClamshellPhone1-5.png</tt></li>
<li><tt>ClamshellPhone1-5-pressed.png</tt></li>
<li><tt>ClamshellPhone1-5-closed.png</tt></li>
<li><tt>defaultbuttons.conf</tt> (only necessary for <a href="qt.html">Qt</a> Extended)</li>
</ul>
<p>Note that the <tt>defaultbuttons.conf</tt> file is only necessary if the skin is supposed to be used with <a href="qt.html">Qt</a> Extended (The file customizes the launch screen applications, orders the soft keys and provides input method hints). See the <a href="qt.html">Qt</a> Extended documentation for more information.</p>
<table class="generic" width="100%">
<thead><tr class="qt-style"><th colspan="3">The ClamshellPhone Skin</th></tr></thead>
<tr valign="top" class="odd"><td colspan="3"><pre class="cpp"> [SkinFile]
Up=ClamshellPhone1-5.png
Down=ClamshellPhone1-5-pressed.png
Closed=ClamshellPhone1-5-closed.png
Screen=72 84 176 208
Areas=22
"Power" 0x0100000a 205 563 249 586
"1" 0x0031 62 414 119 438
"2" 0x0032 130 414 189 438
"3" 0x0033 198 413 257 438
"4" 0x0034 54 444 117 470
"5" 0x0035 128 444 189 471
"6" 0x0036 202 444 264 471
"7" 0x0037 47 477 113 507
"8" 0x0038 126 477 190 507
"9" 0x0039 205 478 270 509
"*" 0x002a 39 515 110 552
"0" 0x0030 122 515 195 553
"#" 0x0023 207 516 280 553
"Context1" 0x01100000 137 360 108 383 123 410 90 409 60 387 63 378
100 362
"Back" 0x01000061 184 361 206 376 213 387 197 410 226 410 256 392
258 381 244 369
"Backspace" 0x01000003 68 563 113 587
"Select" 0x01010000 160 391 172 390 181 386 184 381 180 377 173
373 165 372 155 372 145 375 138 378 136
382 138 387 147 390
"Left" 0x1000012 141 390 136 385 136 381 143 375 132 371 120
380 121 393 129 401
"Down" 0x1000015 143 389 130 402 162 412 191 404 175 390
"Right" 0x1000014 186 370 176 375 184 382 182 387 175 390 190 404
201 396 202 375
"Up" 0x1000013 133 370 143 374 176 374 185 370 169 362 149 362
"Flip" 0x01100006 98 325 225 353</pre>
<p>The <tt>ClamShellPhone.skin</tt> file quoted above, specifies three pixmaps: One for the normal skin (<tt>Up</tt>), one for the activated skin (<tt>Down</tt>) and one for the closed skin (<tt>Closed</tt>). In addition, it is possible to specify a pixmap for the cursor (using a <tt>Cursor</tt> variable).</p>
<p>The file also specifies the screen size (<tt>Screen</tt>) and the number of available buttons (<tt>Areas</tt>). Then it describes the buttons themselves; each button is specified by its name, keycode and coordinates.</p>
<p>The coordinates are a list of at least 2 points in clockwise order that define a shape for the button; a click inside this shape will be treated as a click on that button. While pressed, the pixels for the button are redrawn from the activated skin.</p>
</td></tr>
<tr valign="top" class="even"><td ><p class="centerAlign"><img src="images/qt-embedded-clamshellphone-closed.png" alt="The ClamshellPhone Skin (closed)" /></p></td><td ><p class="centerAlign"><img src="images/qt-embedded-clamshellphone.png" alt="The ClamshellPhone Skin" /></p></td><td ><p class="centerAlign"><img src="images/qt-embedded-clamshellphone-pressed.png" alt="The ClamshellPhone Skin (pressed)" /></p></td></tr>
<tr valign="top" class="odd"><td ><tt>ClamshellPhone1-5-closed.png</tt></td><td ><tt>ClamshellPhone1-5.png</tt></td><td ><tt>ClamshellPhone1-5-pressed.png</tt></td></tr>
</table>
<a name="the-file-menu"></a>
<h3>The File Menu</h3>
<p class="centerAlign"><img src="images/qt-embedded-qvfbfilemenu.png" alt="" /></p><p>The <b>File</b> menu allows the user to configure the virtual framebuffer display (<b>File|Configure...</b>), save a snapshot of the framebuffer contents (<b>File|Save Image...</b>) and record the movements in the framebuffer (<b>File|Animation...</b>).</p>
<p>When choosing the <b>File|Configure</b> menu item, the <tt>qvfb</tt> tool provides a configuration dialog allowing the user to customize the display of the virtual framebuffer. The user can modify the size and depth as well as the Gamma values, and also select the preferred skin (i.e. making the virtual framebuffer simulate the target device environment). In addition, it is possible to emulate a touch screen and a LCD screen.</p>
<p>Note that when configuring (except when changing the Gamma values only), any applications using the virtual framebuffer will be terminated.</p>
<a name="the-view-menu"></a>
<h3>The View Menu</h3>
<p class="centerAlign"><img src="images/qt-embedded-qvfbviewmenu.png" alt="" /></p><p>The <b>View</b> menu allows the user to modify the target's refresh rate (<b>View|Refresh Rate...</b>), making <tt>qvfb</tt> check for updated regions more or less frequently.</p>
<p>The regions of the display that have changed are updated periodically, i.e. the virtual framebuffer is displaying discrete snapshots of the framebuffer rather than each individual drawing operation. For this reason drawing problems such as flickering may not be apparent until the program is run using a real framebuffer. 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 <tt>qvfb</tt> will compete for processor time.</p>
<p>The <b>View</b> menu also allows the user to zoom the view of the application (<b>View|Zoom *</b>).</p>
<a name="running-applications-using-the-virtual-framebuffer"></a>
<h2>Running Applications Using the Virtual Framebuffer</h2>
<p>Once the virtual framebuffer (the <tt>qvfb</tt> application) is running, it is ready for use: Start a server application (i.e. construct a <a href="qapplication.html">QApplication</a> object with the <a href="qapplication.html#Type-enum">QApplication::GuiServer</a> flag or use the <tt>-qws</tt> command line parameter. See the <a href="qt-embedded-running.html">running applications</a> documentation for details). For example:</p>
<pre class="cpp"> cd path/to/QtEmbedded/examples/widgets/analogclock
make
./analogclock -qws</pre>
<p>Note that as long as the virtual framebuffer is running and the current <a href="qt-embedded-linux.html">Qt for Embedded Linux</a> configuration supports <tt>qvfb</tt>, <a href="qt-embedded-linux.html">Qt for Embedded Linux</a> will automatically detect it and use it by default. Alternatively, the <tt>-display</tt> option can be used to specify the virtual framebuffer driver. For example:</p>
<pre class="cpp"> cd path/to/QtEmbedded/examples/widgets/analogclock
make
./analogclock -qws -display QVFb:0</pre>
<p><b>Warning:</b> If <tt>qvfb</tt> is not running (or the current <a href="qt-embedded-linux.html">Qt for Embedded Linux</a> configuration doesn't support it) and the driver is not explicitly specified, <a href="qt-embedded-linux.html">Qt for Embedded Linux</a> will write to the real framebuffer and the X11 display will be corrupted.</p>
</div>
<!-- @@@qvfb.html -->
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Digia, Qt and their respective logos are trademarks of Digia Plc
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
