qt3/doc/qvfb.doc

/****************************************************************************
**
** Qt/Embedded Virtual Framebuffer
**
** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
**
** This file is part of the Qt GUI Toolkit.
**
** This file may be used under the terms of the GNU General
** Public License versions 2.0 or 3.0 as published by the Free
** Software Foundation and appearing in the files LICENSE.GPL2
** and LICENSE.GPL3 included in the packaging of this file.
** Alternatively you may (at your option) use any later version
** of the GNU General Public License if such license has been
** publicly approved by Trolltech ASA (or its successors, if any)
** and the KDE Free Qt Foundation.
**
** Please review the following information to ensure GNU General
** Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/.
** If you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** This file may be used under the terms of the Q Public License as
** defined by Trolltech ASA and appearing in the file LICENSE.QPL
** included in the packaging of this file.  Licensees holding valid Qt
** Commercial licenses may use this file in accordance with the Qt
** Commercial License Agreement provided with the Software.
**
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
** herein.
**
**********************************************************************/
 
/*! \page emb-qvfb.html

\title Qt/Embedded Virtual Framebuffer

The virtual framebuffer allows Qt/Embedded programs to be developed on
a desktop machine, without switching between consoles and X11.

The virtual framebuffer is located in \c $QTDIR/tools/qvfb.

\section1 Using the Virtual Framebuffer

\list 1 
\i Configure Qt/Embedded with the \c -qvfb argument and compile the library:
    \code
    ./configure -qvfb
    make
    \endcode
\i Compile \c qvfb as a normal Qt/X11 application and run it. Do \e not
    compile it as a Qt/Embedded application.
\i Start a Qt/Embedded master application (i.e., construct
    QApplication with the QApplication::GuiServer flag or use the \c
    -qws command line parameter). You can specify to the server that
    you wish to use the virtual framebuffer driver, e.g.:
    \code
    masterapp -qws -display QVFb:0
    \endcode
\i Qt/Embedded will autodetect qvfb, so you can omit the \c -display
   command line parameter if you know that qvfb is running, and that
   the Qt/Embedded library supports qvfb. (If this is not the case,
   Qt/Embedded will write to the real framebuffer, and your X11
   display will be corrupted.)

\endlist

\c qvfb supports the following command line options:
 
\table
\header \i Option \i Meaning
\row
\i \c -width \e width 
\i the width of the virtual framebuffer (default: 240).
\row
\i \c -height \e height
\i the height of the virtual framebuffer (default: 320).
\row
\i \c -depth \e depth 
\i the depth of the virtual framebuffer (1, 8 or 32; default: 8).
\row
\i \c -nocursor 
\i do not display the X11 cursor in the framebuffer window.
\row
\i \c -qwsdisplay \e :id 
\i the Qt/Embedded display id to provide (default: :0).
\endtable

\section1 Virtual Framebuffer Design

The virtual framebuffer emulates a framebuffer using a shared memory region
(the virtual frame buffer) and a utility to display the framebuffer in a
window (\c qvfb). The regions of the display that have changed are updated
periodically, so you will see 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.

The target refresh rate can be set via the <b>View|Refresh Rate</b>
menu item. This will cause \c qvfb to check for updated regions more
frequently. The rate is a target only. 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, then the application and \c qvfb will compete for
processor time.

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

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; do not configure production libraries with \c -qvfb.

*/