1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
|
/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights. These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qvfb.html
\title The Virtual Framebuffer
\ingroup qt-embedded-linux
\l{Qt for Embedded Linux} 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 \l{Qt for Embedded Linux}
programs to be developed on a desktop machine, without switching
between consoles and X11.
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 \l{Installing Qt on X11 Platforms}{configure and
install Qt on X11 platforms} appropriately. Further requirements
can be found in the \l{Qt for Embedded Linux Requirements}
document.
\image qt-embedded-virtualframebuffer.png
The virtual framebuffer emulates a framebuffer using a shared
memory region and the \c qvfb tool to display the framebuffer in a
window. The \c qvfb 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 \c tools/qvfb directory, and provides
several additional features accessible through its \gui File and
\gui View menus.
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
\c -qvfb option.
\tableofcontents
\section1 Displaying the Virtual Framebuffer
To run the \c qvfb tool displaying the virtual framebuffer, the
\l{Qt for Embedded Linux} library must be configured and compiled
with the \c -qvfb option:
\snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 0
Ensure that you have all the
\l{Qt for Embedded Linux Requirements#Additional X11 Libraries for QVFb}
{necessary libraries} needed to build the tool, then compile and run the
\c qvfb tool as a normal Qt for X11 application (i.e., do \e not compile
it as a \l{Qt for Embedded Linux} application):
\snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 1
The \c qvfb application supports the following command line
options:
\table
\header \o Option \o Description
\row
\o \c {-width <value>}
\o The width of the virtual framebuffer (default: 240).
\row
\o \c {-height <value>}
\o The height of the virtual framebuffer (default: 320).
\row
\o \c {-depth <value>}
\o The depth of the virtual framebuffer (1, 8 or 32; default: 8).
\row
\o \c -nocursor
\o Do not display the X11 cursor in the framebuffer window.
\row
\o \c {-qwsdisplay <:id>}
\o The \l{Qt for Embedded Linux} display ID (default: 0).
\row
\o \c {-skin <name>.skin}
\o The preferred skin. Note that the skin must be located in Qt's
\c /tools/qvfb/ directory.
\row
\o \c {-zoom <factor>}
\o Scales the application view with the given factor.
\endtable
\section2 Skins
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 \c qvfb tool's
menus when a skin is activated, right-click over the display.
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.
\table 100%
\row
\o
\bold {Target Device Environment}
The \c qvfb 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:
\list
\o ClamshellPhone
\o PortableMedia
\o S60-nHD-Touchscreen
\o S60-QVGA-Candybar
\o SmartPhone
\o SmartPhone2
\o SmartPhoneWithButtons
\o TouchscreenPhone
\endlist
In addition, it is possible to create custom skins.
\o \image qt-embedded-phone.png
\o \image qt-embedded-pda.png
\endtable
\bold {Creating Custom Skins}
The XML and pixmap files specifying a custom skin must be located
in subdirectory of the Qt's \c /tools/qvfb directory, called \c
/customskin.skin. See the ClamshellPhone skin for an example of the
file structure:
\snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 2
The \c /ClamshellPhone.skin directory contains the following files:
\list
\o \c ClamshellPhone.skin
\o \c ClamshellPhone1-5.png
\o \c ClamshellPhone1-5-pressed.png
\o \c ClamshellPhone1-5-closed.png
\o \c defaultbuttons.conf (only necessary for \l Qt Extended)
\endlist
Note that the \c defaultbuttons.conf file is only necessary if the
skin is supposed to be used with \l Qt Extended (The file customizes
the launch screen applications, orders the soft keys and provides
input method hints). See the \l Qt Extended documentation for more
information.
\table 100%
\header
\o {3,1} The ClamshellPhone Skin
\row
\o {3,1}
\snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 3
The \c ClamShellPhone.skin file quoted above, specifies three
pixmaps: One for the normal skin (\c Up), one for the activated
skin (\c Down) and one for the closed skin (\c Closed). In
addition, it is possible to specify a pixmap for the cursor (using
a \c Cursor variable).
The file also specifies the screen size (\c Screen) and the number
of available buttons (\c Areas). Then it describes the buttons
themselves; each button is specified by its name, keycode and
coordinates.
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.
\row
\row
\o
\image qt-embedded-clamshellphone-closed.png The ClamshellPhone Skin (closed)
\o
\image qt-embedded-clamshellphone.png The ClamshellPhone Skin
\o
\image qt-embedded-clamshellphone-pressed.png The ClamshellPhone Skin (pressed)
\row
\o \c ClamshellPhone1-5-closed.png
\o \c ClamshellPhone1-5.png
\o \c ClamshellPhone1-5-pressed.png
\endtable
\section2 The File Menu
\image qt-embedded-qvfbfilemenu.png
The \gui File menu allows the user to configure the virtual
framebuffer display (\gui File|Configure...), save a snapshot of
the framebuffer contents (\gui {File|Save Image...}) and record
the movements in the framebuffer (\gui File|Animation...).
When choosing the \gui File|Configure menu item, the \c qvfb 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.
Note that when configuring (except when changing the Gamma values
only), any applications using the virtual framebuffer will be
terminated.
\section2 The View Menu
\image qt-embedded-qvfbviewmenu.png
The \gui View menu allows the user to modify the target's refresh
rate (\gui {View|Refresh Rate...}), making \c qvfb check for
updated regions more or less frequently.
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
\c qvfb will compete for processor time.
The \gui View menu also allows the user to zoom the view of the
application (\gui {View|Zoom *}).
\section1 Running Applications Using the Virtual Framebuffer
Once the virtual framebuffer (the \c qvfb application) is running,
it is ready for use: Start a server application (i.e. construct a
QApplication object with the QApplication::GuiServer flag or use
the \c -qws command line parameter. See the
\l {Running Qt for Embedded Linux Applications}{running applications}
documentation for details). For example:
\snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 4
Note that as long as the virtual framebuffer is running and the
current \l{Qt for Embedded Linux} configuration supports \c qvfb,
\l{Qt for Embedded Linux} will automatically detect it and use it by
default. Alternatively, the \c -display option can be used to
specify the virtual framebuffer driver. For example:
\snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 5
\warning If \c qvfb is not running (or the current
\l{Qt for Embedded Linux} configuration doesn't support it) and the
driver is not explicitly specified, \l{Qt for Embedded Linux} will
write to the real framebuffer and the X11 display will be corrupted.
*/
|
