306 lines
12 KiB
Plaintext
306 lines
12 KiB
Plaintext
/****************************************************************************
|
|
**
|
|
** Copyright (C) 2011 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:FDL$
|
|
** GNU Free Documentation License
|
|
** Alternatively, this file may be used under the terms of the GNU Free
|
|
** Documentation License version 1.3 as published by the Free Software
|
|
** Foundation and appearing in the file included in the packaging of
|
|
** this file.
|
|
**
|
|
** Other Usage
|
|
** Alternatively, this file may be used in accordance with the terms
|
|
** and conditions contained in a signed written agreement between you
|
|
** and Nokia.
|
|
**
|
|
**
|
|
**
|
|
**
|
|
** $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 (although in this case nothing
|
|
needs cleaning up).
|
|
|
|
\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 logo variable will be used to hold a pointer to the QtLogo object which
|
|
contains all the geometry.
|
|
|
|
\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, sets
|
|
the pointer to the QtLogo object to null, 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
|
|
|
|
In this case nothing requires cleaning up.
|
|
|
|
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 QtLogo object instance which will contain all the geometry 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 geometry we want to display, and
|
|
call the draw method of the QtLogo object to render the scene.
|
|
|
|
\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.
|
|
|
|
\section1 QtLogo Class
|
|
|
|
This class encapsulates the OpenGL geometry data which will be rendered
|
|
in the basic 3D scene.
|
|
|
|
\snippet examples/opengl/shared/qtlogo.h 0
|
|
|
|
The geometry is divided into a list of parts which may be rendered in
|
|
different ways. The data itself is contained in a Geometry structure that
|
|
includes the vertices, their lighting normals and index values which
|
|
point into the vertices, grouping them into faces.
|
|
|
|
\snippet examples/opengl/shared/qtlogo.cpp 0
|
|
|
|
The data in the Geometry class is stored in QVector<QVector3D> members
|
|
which are convenient for use with OpenGL because they expose raw
|
|
contiguous floating point values via the constData() method. Methods
|
|
are included for adding new vertex data, either with smooth normals, or
|
|
facetted normals; and for enabling the geometry ready for rendering.
|
|
|
|
\snippet examples/opengl/shared/qtlogo.cpp 1
|
|
|
|
The higher level Patch class has methods for accumulating the geometry
|
|
one face at a time, and treating collections of faces or "patches" with
|
|
transformations, applying different colors or smoothing. Although faces
|
|
may be added as triangles or quads, at the OpenGL level all data is
|
|
treated as triangles for compatibility with OpenGL/ES.
|
|
|
|
\snippet examples/opengl/shared/qtlogo.cpp 2
|
|
|
|
Drawing a Patch is simply acheived by applying any transformation,
|
|
and material effect, then drawing the data using the index range for
|
|
the patch. The model-view matrix is saved and then restored so that
|
|
any transformation does not affect other parts of the scene.
|
|
|
|
\snippet examples/opengl/shared/qtlogo.cpp 3
|
|
|
|
The geometry is built once on construction of the QtLogo, and it is
|
|
paramaterized on a number of divisions - which controls how "chunky" the
|
|
curved section of the logo looks - and on a scale, so larger and smaller
|
|
QtLogo objects can be created without having to use OpenGL scaling
|
|
(which would force normal recalculation).
|
|
|
|
The building process is done by helper classes (read the source for full
|
|
details) which only exist during the build phase, to assemble the parts
|
|
of the scene.
|
|
|
|
\snippet examples/opengl/shared/qtlogo.cpp 4
|
|
|
|
Finally the complete QtLogo scene is simply drawn by enabling the data arrays
|
|
and then iterating over the parts, calling draw() on each one.
|
|
|
|
\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.
|
|
*/
|