|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the documentation of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 /*! |
|
43 \example qws/dbscreen |
|
44 \title Double Buffered Graphics Driver Example |
|
45 |
|
46 The Double Buffered Graphics Driver example shows how to write your own |
|
47 double buffered graphics driver and add it to Qt for Embedded Linux. |
|
48 |
|
49 Similar to the \l{Accelerated Graphics Driver Example}, there are three steps |
|
50 to writing and implementing this graphics driver: |
|
51 |
|
52 \list 1 |
|
53 \o \l {Step 1: Creating a Custom Graphics Driver} |
|
54 {Creating a Custom Graphics Driver} |
|
55 |
|
56 \o \l {Step 2: Implementing the Back Buffer} |
|
57 {Implementing the Back Buffer} |
|
58 |
|
59 \o \l {Step 3: Creating the Driver Plugin} |
|
60 {Creating the Driver Plugin} |
|
61 |
|
62 \endlist |
|
63 |
|
64 After compiling the example code, install the graphics driver plugin with |
|
65 the command \c {make install}. To start an application using the graphics |
|
66 driver, you can either set the environment variable \l QWS_DISPLAY and |
|
67 then run the application, or you can just run the application using the |
|
68 \c -display switch. |
|
69 |
|
70 Note that this is a minimal example and this driver will not work well |
|
71 with widgets painting themself directly to the screen (e.g. widgets with |
|
72 the Qt::WA_PaintOnScreen window attribute set). Also, the example requires |
|
73 the Linux framebuffer to be set up correctly and with the correct device |
|
74 permissions. For further information, refer to |
|
75 \l{Testing the Linux Framebuffer}. |
|
76 |
|
77 \section1 Step 1: Creating a Custom Graphics Driver |
|
78 |
|
79 Usually, a custom graphics driver is created by subclassing the QScreen |
|
80 class, the base class for implementing screen or graphics drivers in |
|
81 Qt for Embedded Linux. In this example, however, we subclass the QLinuxFbScreen |
|
82 class instead, to ensure that our driver uses the Linux framebuffer. |
|
83 |
|
84 For our graphics driver, the \c DBScreen class, we reimplement five |
|
85 functions belonging to QScreen: |
|
86 |
|
87 \list |
|
88 \o \l{QScreen::initDevice()}{initDevice()}, |
|
89 \o \l{QScreen::shutdownDevice()}{shutdownDevice()}, |
|
90 \o \l{QScreen::blit()}{blit()}, |
|
91 \o \l{QScreen::solidFill()}{solidFill()}, and |
|
92 \o \l{QScreen::exposeRegion()}{exposeRegion()}. |
|
93 \endlist |
|
94 |
|
95 \snippet examples/qws/dbscreen/dbscreen.h 0 |
|
96 |
|
97 In addition to the abovementioned functions, there is a private instance |
|
98 of QPainter and QImage - \c painter, used for drawing operations on |
|
99 the back buffer, and \c image, the back buffer itself. |
|
100 |
|
101 \section1 Step 2: Implementing the Back Buffer |
|
102 |
|
103 The graphics driver must carry out three main functions: |
|
104 |
|
105 \list 1 |
|
106 \o Allocate the back buffer on startup and deallocate it on shutdown. |
|
107 \o Draw to the back buffer instead of directly to the screen |
|
108 (which is what QLinuxFbScreen does). |
|
109 \o Copy the back buffer to the screen whenever a screen update is |
|
110 done. |
|
111 \endlist |
|
112 |
|
113 \section2 Device initializing and shutdown |
|
114 |
|
115 We first reimplement \c initDevice() and \c shutdownDevice(). |
|
116 |
|
117 The \c initDevice() function initializes the framebuffer. We reimplement |
|
118 this function to enable accelerated drivers to set up the graphic card. |
|
119 For this example, we first call the super class' implementation to set up |
|
120 the Linux framebuffer. If this call returns \c false, we return \c false. |
|
121 Otherwise, we initialize the screen cursor with |
|
122 QScreenCursor::initSoftwareCursor() as well as instantiate \c image and |
|
123 \c painter. Then, we return \c true. |
|
124 |
|
125 \snippet examples/qws/dbscreen/dbscreen.cpp 0 |
|
126 |
|
127 The \c shutdownDevice() function's default implementation only hides the |
|
128 mouse cursor. Hence, we reimplement it to carry out the necessary cleanup |
|
129 before the Qt for Embedded Linux server exits. |
|
130 |
|
131 \snippet examples/qws/dbscreen/dbscreen.cpp 1 |
|
132 |
|
133 Again, we call the super class implementation to shutdown the Linux |
|
134 framebuffer prior to deleting \c image and \c painter. |
|
135 |
|
136 \section2 Drawing to the back buffer |
|
137 |
|
138 We move on to the drawing functions - \c solidFill() and \c blit(). In |
|
139 QLinuxFbScreen, these functions draw directly to the Linux framebuffer; |
|
140 but in our driver we reimplement them to draw to the back buffer instead. |
|
141 |
|
142 \snippet examples/qws/dbscreen/dbscreen.cpp 2 |
|
143 |
|
144 The \c solidFill() function is called from \c exposeRegion() to fill the |
|
145 given \c region of the screen with the specified \c color. In this |
|
146 example, we use \c painter to fill rectangles in \c image, the back |
|
147 buffer, according to the given region. |
|
148 |
|
149 \snippet examples/qws/dbscreen/dbscreen.cpp 3 |
|
150 |
|
151 The \c blit() function is also called from \c exposeRegion() to copy the |
|
152 given QRegion object, \c region, in the given QImage object, \c image, to |
|
153 the QPoint object specified by \c topLeft. Once again we use \c painter |
|
154 to draw in the back buffer, \c image. |
|
155 |
|
156 \section2 Displaying the buffer on the screen |
|
157 |
|
158 The \c exposeRegion() function is called by the Qt for Embedded Linux server |
|
159 whenever a screen update is required. The given \c region is the screen |
|
160 region that needs to be updated and \c changing is is the index into |
|
161 QWSServer::clientWindows() of the window that caused the update. |
|
162 |
|
163 \snippet examples/qws/dbscreen/dbscreen.cpp 4 |
|
164 |
|
165 In our implementation, we first call the super class implementation to |
|
166 ensure that \c solidFill() and \c blit() will be called correctly. This |
|
167 causes the changed areas to be updated in the back buffer. We then call |
|
168 the super class' implementation of \c blit() to copy the updated region |
|
169 from the back buffer into the Linux framebuffer. |
|
170 |
|
171 \section1 Step 3: Creating the Driver Plugin |
|
172 |
|
173 Qt provides a high level API for writing Qt extentions. One of the plugin |
|
174 base classes provided is QScreenDriverPlugin, which we use in this example |
|
175 to create our screen driver plugin. |
|
176 |
|
177 \snippet examples/qws/dbscreen/dbscreendriverplugin.cpp 0 |
|
178 |
|
179 There are only two functions to reimplement: |
|
180 |
|
181 \list |
|
182 \o \l{QScreenDriverPlugin::create()}{create()} - creates a driver |
|
183 matching the given key |
|
184 \o \l{QScreenDriverPlugin::create()}{keys()} - returns a list of |
|
185 valid keys representing the drivers supported by the plugin |
|
186 \endlist |
|
187 |
|
188 \snippet examples/qws/dbscreen/dbscreendriverplugin.cpp 1 |
|
189 \codeline |
|
190 \snippet examples/qws/dbscreen/dbscreendriverplugin.cpp 2 |
|
191 |
|
192 Our plugin will only support one driver, \c dbscreen. |
|
193 |
|
194 Lastly, we export the plugin. |
|
195 |
|
196 \snippet examples/qws/dbscreen/dbscreendriverplugin.cpp 3 |
|
197 |
|
198 For detailed information about the Qt plugin system see |
|
199 \l{How to Create Qt Plugins.} |
|
200 */ |