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
|
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information (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 either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** 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.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at qt-sales@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example opengl/hellogl
\title Hello GL Example
The Hello GL example demonstrates the basic use of the OpenGL-related classes
provided with Qt.
\image hellogl-example.png
Qt provides the QGLWidget class to enable OpenGL graphics to be rendered within
a standard application user interface. By subclassing this class, and providing
reimplementations of event handler functions, 3D scenes can be displayed on
widgets that can be placed in layouts, connected to other objects using signals
and slots, and manipulated like any other widget.
\tableofcontents
\section1 GLWidget Class Definition
The \c GLWidget class contains some standard public definitions for the
constructor, destructor, \l{QWidget::sizeHint()}{sizeHint()}, and
\l{QWidget::minimumSizeHint()}{minimumSizeHint()} functions:
\snippet examples/opengl/hellogl/glwidget.h 0
We use a destructor to ensure that any OpenGL-specific data structures
are deleted when the widget is no longer needed.
\snippet examples/opengl/hellogl/glwidget.h 1
The signals and slots are used to allow other objects to interact with the
3D scene.
\snippet examples/opengl/hellogl/glwidget.h 2
OpenGL initialization, viewport resizing, and painting are handled by
reimplementing the QGLWidget::initializeGL(), QGLWidget::resizeGL(), and
QGLWidget::paintGL() handler functions. To enable the user to interact
directly with the scene using the mouse, we reimplement
QWidget::mousePressEvent() and QWidget::mouseMoveEvent().
\snippet examples/opengl/hellogl/glwidget.h 3
The rest of the class contains utility functions and variables that are
used to construct and hold orientation information for the scene. The
\c object variable will be used to hold an identifier for an OpenGL
display list.
\section1 GLWidget Class Implementation
In this example, we split the class into groups of functions and describe
them separately. This helps to illustrate the differences between subclasses
of native widgets (such as QWidget and QFrame) and QGLWidget subclasses.
\section2 Widget Construction and Sizing
The constructor provides default rotation angles for the scene, initializes
the variable used for the display list, and sets up some colors for later use.
\snippet examples/opengl/hellogl/glwidget.cpp 0
We also implement a destructor to release OpenGL-related resources when the
widget is deleted:
\snippet examples/opengl/hellogl/glwidget.cpp 1
The destructor ensures that the display list is deleted properly.
We provide size hint functions to ensure that the widget is shown at a
reasonable size:
\snippet examples/opengl/hellogl/glwidget.cpp 2
\codeline
\snippet examples/opengl/hellogl/glwidget.cpp 3
\snippet examples/opengl/hellogl/glwidget.cpp 4
The widget provides three slots that enable other components in the
example to change the orientation of the scene:
\snippet examples/opengl/hellogl/glwidget.cpp 5
In the above slot, the \c xRot variable is updated only if the new angle
is different to the old one, the \c xRotationChanged() signal is emitted to
allow other components to be updated, and the widget's
\l{QGLWidget::updateGL()}{updateGL()} handler function is called.
The \c setYRotation() and \c setZRotation() slots perform the same task for
rotations measured by the \c yRot and \c zRot variables.
\section2 OpenGL Initialization
The \l{QGLWidget::initializeGL()}{initializeGL()} function is used to
perform useful initialization tasks that are needed to render the 3D scene.
These often involve defining colors and materials, enabling and disabling
certain rendering flags, and setting other properties used to customize the
rendering process.
\snippet examples/opengl/hellogl/glwidget.cpp 6
In this example, we reimplement the function to set the background color,
create a display list containing information about the object we want to
display, and set up the rendering process to use a particular shading model
and rendering flags:
\section2 Resizing the Viewport
The \l{QGLWidget::resizeGL()}{resizeGL()} function is used to ensure that
the OpenGL implementation renders the scene onto a viewport that matches the
size of the widget, using the correct transformation from 3D coordinates to
2D viewport coordinates.
The function is called whenever the widget's dimensions change, and is
supplied with the new width and height. Here, we define a square viewport
based on the length of the smallest side of the widget to ensure that
the scene is not distorted if the widget has sides of unequal length:
\snippet examples/opengl/hellogl/glwidget.cpp 8
A discussion of the projection transformation used is outside the scope of
this example. Please consult the OpenGL reference documentation for an
explanation of projection matrices.
\section2 Painting the Scene
The \l{QGLWidget::paintGL()}{paintGL()} function is used to paint the
contents of the scene onto the widget. For widgets that only need to be
decorated with pure OpenGL content, we reimplement QGLWidget::paintGL()
\e instead of reimplementing QWidget::paintEvent():
\snippet examples/opengl/hellogl/glwidget.cpp 7
In this example, we clear the widget using the background color that
we defined in the \l{QGLWidget::initializeGL()}{initializeGL()} function,
set up the frame of reference for the object we want to display, and call
the display list containing the rendering commands for the object.
\section2 Mouse Handling
Just as in subclasses of native widgets, mouse events are handled by
reimplementing functions such as QWidget::mousePressEvent() and
QWidget::mouseMoveEvent().
The \l{QWidget::mousePressEvent()}{mousePressEvent()} function simply
records the position of the mouse when a button is initially pressed:
\snippet examples/opengl/hellogl/glwidget.cpp 9
The \l{QWidget::mouseMoveEvent()}{mouseMoveEvent()} function uses the
previous location of the mouse cursor to determine how much the object
in the scene should be rotated, and in which direction:
\snippet examples/opengl/hellogl/glwidget.cpp 10
Since the user is expected to hold down the mouse button and drag the
cursor to rotate the object, the cursor's position is updated every time
a move event is received.
\section2 Utility Functions
We have omitted the utility functions, \c makeObject(), \c quad(),
\c extrude(), and \c normalizeAngle() from our discussion. These can be
viewed in the quoted source for \c glwidget.cpp via the link at the
start of this document.
\section1 Window Class Definition
The \c Window class is used as a container for the \c GLWidget used to
display the scene:
\snippet examples/opengl/hellogl/window.h 0
In addition, it contains sliders that are used to change the orientation
of the object in the scene.
\section1 Window Class Implementation
The constructor constructs an instance of the \c GLWidget class and some
sliders to manipulate its contents.
\snippet examples/opengl/hellogl/window.cpp 0
We connect the \l{QAbstractSlider::valueChanged()}{valueChanged()} signal
from each of the sliders to the appropriate slots in \c{glWidget}.
This allows the user to change the orientation of the object by dragging
the sliders.
We also connect the \c xRotationChanged(), \c yRotationChanged(), and
\c zRotationChanged() signals from \c glWidget to the
\l{QAbstractSlider::setValue()}{setValue()} slots in the
corresponding sliders.
\snippet examples/opengl/hellogl/window.cpp 1
The sliders are placed horizontally in a layout alongside the \c GLWidget,
and initialized with suitable default values.
The \c createSlider() utility function constructs a QSlider, and ensures
that it is set up with a suitable range, step value, tick interval, and
page step value before returning it to the calling function:
\snippet examples/opengl/hellogl/window.cpp 2
\section1 Summary
The \c GLWidget class implementation shows how to subclass QGLWidget for
the purposes of rendering a 3D scene using OpenGL calls. Since QGLWidget
is a subclass of QWidget, subclasses of QGLWidget can be placed in layouts
and provided with interactive features just like normal custom widgets.
We ensure that the widget is able to correctly render the scene using OpenGL
by reimplementing the following functions:
\list
\o QGLWidget::initializeGL() sets up resources needed by the OpenGL implementation
to render the scene.
\o QGLWidget::resizeGL() resizes the viewport so that the rendered scene fits onto
the widget, and sets up a projection matrix to map 3D coordinates to 2D viewport
coordinates.
\o QGLWidget::paintGL() performs painting operations using OpenGL calls.
\endlist
Since QGLWidget is a subclass of QWidget, it can also be used
as a normal paint device, allowing 2D graphics to be drawn with QPainter.
This use of QGLWidget is discussed in the \l{2D Painting Example}{2D Painting}
example.
More advanced users may want to paint over parts of a scene rendered using
OpenGL. QGLWidget allows pure OpenGL rendering to be mixed with QPainter
calls, but care must be taken to maintain the state of the OpenGL implementation.
See the \l{Overpainting Example}{Overpainting} example for more information.
*/
|
