Update copyright headers
[qt:qt.git] / doc / src / platforms / emb-displaymanagement.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \page qt-embedded-displaymanagement.html
30
31     \title Qt for Embedded Linux Display Management
32     \ingroup qt-embedded-linux
33
34     When rendering, the default behavior for each Qt for Embedded Linux
35     client is to render its widgets into memory, while the server is
36     responsible for putting the contents of the memory onto the
37     screen. The server uses the screen driver to copy the content of
38     the memory to the display.
39
40     The screen driver is loaded by the server application when it
41     starts running, using Qt's \l {How to Create Qt Plugins}{plugin
42     system}.
43
44     Contents:
45
46     \tableofcontents
47
48     \section1 Available Drivers
49
50     \l{Qt for Embedded Linux} provides drivers for the Linux framebuffer, the
51     virtual framebuffer, transformed screens, VNC servers and multi
52     screens. Run the \c configure script to list the available
53     drivers:
54
55     \if defined(QTOPIA_DOCS)
56     \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 0
57     \else
58     \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 1
59     \endif
60
61     \if defined(QTOPIA_DOCS)
62     In the default Qt Extended configuration, only an unaccelerated Linux
63     framebuffer driver (\c /dev/fb0) is enabled. The various drivers
64     can be enabled and disabled using the \c configure script. For
65     example:
66
67     \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 2
68     \else
69     In the default Qt configuration, only an unaccelerated Linux
70     framebuffer driver (\c /dev/fb0) is enabled. The various drivers
71     can be enabled and disabled using the \c configure script. For
72     example:
73
74     \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 3
75     \endif
76
77     Custom screen drivers can be implemented by subclassing the
78     QScreen class and creating a screen driver plugin (derived from
79     the QScreenDriverPlugin class). The default implementation
80     of the QScreenDriverFactory class will automatically detect the
81     plugin, loading the driver into the server application at run-time.
82
83     \section1 Specifying a Driver
84
85     To specify which driver to use, set the QWS_DISPLAY environment
86     variable. For example (if the current shell is bash, ksh, zsh or
87     sh):
88
89     \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 4
90
91     The valid values for the \c <driver> argument are \c LinuxFb, \c
92     QVFb, \c VNC, \c Transformed, \c Multi and \l
93     {QScreenDriverPlugin::keys()}{keys} identifying custom drivers,
94     and the \c {<display num>} argument is used to separate screens
95     that are using the same screen driver and to enable multiple
96     displays (see the \l {Running Qt for Embedded Linux Applications}
97     documentation for more details). The driver specific options are
98     described in the table below.
99
100     \table
101     \header
102         \o Driver Specific Option \o Available For  \o Description
103     \row
104         \o \c tty=<device>
105         \o LinuxFb
106         \o Passes the device file to the console the application is
107         running on.
108     \row
109         \o \c nographicsmodeswitch
110         \o LinuxFb
111         \o Ensures that the application is not in graphics mode.
112     \row
113         \o \c littleendian
114         \o LinuxFb
115         \o Tells the driver it must handle a little-endian frame 
116         buffer in a big-endian system.
117     \row
118         \o \c mmWidth=<value> \target mmWidth
119         \o LinuxFb, QVFb
120         \o The screen's physical width (used to calculate DPI).
121     \row
122         \o \c mmHeight=<value> \target mmHeight
123         \o LinuxFb, QVFb
124         \o The screen's physical height (used to calculate DPI).
125     \row
126         \o \c <device>
127         \o LinuxFb
128         \o
129     \row
130         \o \c <subdriver>
131         \o VNC, Transformed, Multi
132         \o Specifies a subdriver.
133     \row
134         \o \c <RotX>
135         \o Transformed
136         \o Specifies the rotation of the screen. The valid values of
137         \c X are 90, 180 and 270.
138     \row
139         \o \c offset=<x,y>
140         \o Multi
141         \o Specifies the coordinates of a subscreen's top-left corner
142         (by default 0,0).
143
144     \endtable
145
146     The QWS_DISPLAY environment variable can also be set using the \c
147     -display option when running an application. For example:
148
149     \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 5
150
151     \section1 Subdrivers and Multiple Drivers
152
153     The VNC, Transformed and Multi screen drivers depend on
154     subdrivers. The general syntax for specifying a driver is as
155     follows:
156
157     \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 6
158
159     In the case of subdrivers, it is important to add a space between
160     each subdriver and before the display number to separate the
161     various drivers and displays. Note that \c Multi screen drivers
162     can have several subdrivers. For example:
163
164     \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 7
165
166     Note also that the VNC screen driver defaults to a virtual screen
167     driver if no subdriver is specified. In this case the VNC driver accepts a
168     few additional (optional) arguments specifying the size and depth
169     of the default virtual screen:
170
171     \list
172         \o \c {size=<width x height>}
173         \o \c {depth=<value>}
174         \o \c {mmHeight=<physical height in millimeters>}
175         \o \c {mmWidth=<physical width in millimeters>}
176     \endlist
177
178     Example running the VNC screen driver with a virtual screen of size 
179     720x480 with 32 bits per pixel:
180
181     \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 8
182
183     Example running the VNC screen driver on top of the Linux framebuffer
184     driver:
185
186     \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 9
187
188     In this last example, Qt is using two screen drivers simultaneously,
189     displaying output on both the device's screen and across a network on
190     VNC client displays.
191 */