1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 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 opengl/hellogl

    44     \title Hello GL Example

    45 

    46     The Hello GL example demonstrates the basic use of the OpenGL-related classes

    47     provided with Qt.

    48 

    49     \image hellogl-example.png

    50 

    51     Qt provides the QGLWidget class to enable OpenGL graphics to be rendered within

    52     a standard application user interface. By subclassing this class, and providing

    53     reimplementations of event handler functions, 3D scenes can be displayed on

    54     widgets that can be placed in layouts, connected to other objects using signals

    55     and slots, and manipulated like any other widget.

    56 

    57     \tableofcontents

    58 

    59     \section1 GLWidget Class Definition

    60 

    61     The \c GLWidget class contains some standard public definitions for the

    62     constructor, destructor, \l{QWidget::sizeHint()}{sizeHint()}, and

    63     \l{QWidget::minimumSizeHint()}{minimumSizeHint()} functions:

    64 

    65     \snippet examples/opengl/hellogl/glwidget.h 0

    66 

    67     We use a destructor to ensure that any OpenGL-specific data structures

    68     are deleted when the widget is no longer needed (although in this case nothing

    69     needs cleaning up).

    70 

    71     \snippet examples/opengl/hellogl/glwidget.h 1

    72 

    73     The signals and slots are used to allow other objects to interact with the

    74     3D scene.

    75 

    76     \snippet examples/opengl/hellogl/glwidget.h 2

    77 

    78     OpenGL initialization, viewport resizing, and painting are handled by

    79     reimplementing the QGLWidget::initializeGL(), QGLWidget::resizeGL(), and

    80     QGLWidget::paintGL() handler functions. To enable the user to interact

    81     directly with the scene using the mouse, we reimplement

    82     QWidget::mousePressEvent() and QWidget::mouseMoveEvent().

    83 

    84     \snippet examples/opengl/hellogl/glwidget.h 3

    85 

    86     The rest of the class contains utility functions and variables that are

    87     used to construct and hold orientation information for the scene. The

    88     \c logo variable will be used to hold a pointer to the QtLogo object which

    89     contains all the geometry.

    90 

    91     \section1 GLWidget Class Implementation

    92 

    93     In this example, we split the class into groups of functions and describe

    94     them separately. This helps to illustrate the differences between subclasses

    95     of native widgets (such as QWidget and QFrame) and QGLWidget subclasses.

    96 

    97     \section2 Widget Construction and Sizing

    98 

    99     The constructor provides default rotation angles for the scene, sets

   100     the pointer to the QtLogo object to null, and sets up some colors for

   101     later use.

   102 

   103     \snippet examples/opengl/hellogl/glwidget.cpp 0

   104 

   105     We also implement a destructor to release OpenGL-related resources when the

   106     widget is deleted:

   107 

   108     \snippet examples/opengl/hellogl/glwidget.cpp 1

   109 

   110     In this case nothing requires cleaning up.

   111 

   112     We provide size hint functions to ensure that the widget is shown at a

   113     reasonable size:

   114 

   115     \snippet examples/opengl/hellogl/glwidget.cpp 2

   116     \codeline

   117     \snippet examples/opengl/hellogl/glwidget.cpp 3

   118     \snippet examples/opengl/hellogl/glwidget.cpp 4

   119 

   120     The widget provides three slots that enable other components in the

   121     example to change the orientation of the scene:

   122 

   123     \snippet examples/opengl/hellogl/glwidget.cpp 5

   124 

   125     In the above slot, the \c xRot variable is updated only if the new angle

   126     is different to the old one, the \c xRotationChanged() signal is emitted to

   127     allow other components to be updated, and the widget's

   128     \l{QGLWidget::updateGL()}{updateGL()} handler function is called.

   129 

   130     The \c setYRotation() and \c setZRotation() slots perform the same task for

   131     rotations measured by the \c yRot and \c zRot variables.

   132 

   133     \section2 OpenGL Initialization

   134 

   135     The \l{QGLWidget::initializeGL()}{initializeGL()} function is used to

   136     perform useful initialization tasks that are needed to render the 3D scene.

   137     These often involve defining colors and materials, enabling and disabling

   138     certain rendering flags, and setting other properties used to customize the

   139     rendering process.

   140 

   141     \snippet examples/opengl/hellogl/glwidget.cpp 6

   142 

   143     In this example, we reimplement the function to set the background color,

   144     create a QtLogo object instance which will contain all the geometry to

   145     display, and set up the rendering process to use a particular shading model

   146     and rendering flags.

   147 

   148     \section2 Resizing the Viewport

   149 

   150     The \l{QGLWidget::resizeGL()}{resizeGL()} function is used to ensure that

   151     the OpenGL implementation renders the scene onto a viewport that matches the

   152     size of the widget, using the correct transformation from 3D coordinates to

   153     2D viewport coordinates.

   154 

   155     The function is called whenever the widget's dimensions change, and is

   156     supplied with the new width and height. Here, we define a square viewport

   157     based on the length of the smallest side of the widget to ensure that

   158     the scene is not distorted if the widget has sides of unequal length:

   159 

   160     \snippet examples/opengl/hellogl/glwidget.cpp 8

   161 

   162     A discussion of the projection transformation used is outside the scope of

   163     this example. Please consult the OpenGL reference documentation for an

   164     explanation of projection matrices.

   165 

   166     \section2 Painting the Scene

   167 

   168     The \l{QGLWidget::paintGL()}{paintGL()} function is used to paint the

   169     contents of the scene onto the widget. For widgets that only need to be

   170     decorated with pure OpenGL content, we reimplement QGLWidget::paintGL()

   171     \e instead of reimplementing QWidget::paintEvent():

   172 

   173     \snippet examples/opengl/hellogl/glwidget.cpp 7

   174 

   175     In this example, we clear the widget using the background color that

   176     we defined in the \l{QGLWidget::initializeGL()}{initializeGL()} function,

   177     set up the frame of reference for the geometry we want to display, and

   178     call the draw method of the QtLogo object to render the scene.

   179 

   180     \section2 Mouse Handling

   181 

   182     Just as in subclasses of native widgets, mouse events are handled by

   183     reimplementing functions such as QWidget::mousePressEvent() and

   184     QWidget::mouseMoveEvent().

   185 

   186     The \l{QWidget::mousePressEvent()}{mousePressEvent()} function simply

   187     records the position of the mouse when a button is initially pressed:

   188 

   189     \snippet examples/opengl/hellogl/glwidget.cpp 9

   190 

   191     The \l{QWidget::mouseMoveEvent()}{mouseMoveEvent()} function uses the

   192     previous location of the mouse cursor to determine how much the object

   193     in the scene should be rotated, and in which direction:

   194 

   195     \snippet examples/opengl/hellogl/glwidget.cpp 10

   196 

   197     Since the user is expected to hold down the mouse button and drag the

   198     cursor to rotate the object, the cursor's position is updated every time

   199     a move event is received.

   200 

   201     \section1 QtLogo Class

   202 

   203     This class encapsulates the OpenGL geometry data which will be rendered

   204     in the basic 3D scene.

   205 

   206     \snippet examples/opengl/shared/qtlogo.h 0

   207 

   208     The geometry is divided into a list of parts which may be rendered in

   209     different ways.  The data itself is contained in a Geometry structure that

   210     includes the vertices, their lighting normals and index values which

   211     point into the vertices, grouping them into faces.

   212 

   213     \snippet examples/opengl/shared/qtlogo.cpp 0

   214 

   215     The data in the Geometry class is stored in QVector<QVector3D> members

   216     which are convenient for use with OpenGL because they expose raw

   217     contiguous floating point values via the constData() method.  Methods

   218     are included for adding new vertex data, either with smooth normals, or

   219     facetted normals; and for enabling the geometry ready for rendering.

   220 

   221     \snippet examples/opengl/shared/qtlogo.cpp 1

   222 

   223     The higher level Patch class has methods for accumulating the geometry

   224     one face at a time, and treating collections of faces or "patches" with

   225     transformations, applying different colors or smoothing.  Although faces

   226     may be added as triangles or quads, at the OpenGL level all data is

   227     treated as triangles for compatibility with OpenGL/ES.

   228 

   229     \snippet examples/opengl/shared/qtlogo.cpp 2

   230 

   231     Drawing a Patch is simply acheived by applying any transformation,

   232     and material effect, then drawing the data using the index range for

   233     the patch.  The model-view matrix is saved and then restored so that

   234     any transformation does not affect other parts of the scene.

   235 

   236     \snippet examples/opengl/shared/qtlogo.cpp 3

   237 

   238     The geometry is built once on construction of the QtLogo, and it is

   239     paramaterized on a number of divisions - which controls how "chunky" the

   240     curved section of the logo looks - and on a scale, so larger and smaller

   241     QtLogo objects can be created without having to use OpenGL scaling

   242     (which would force normal recalculation).

   243 

   244     The building process is done by helper classes (read the source for full

   245     details) which only exist during the build phase, to assemble the parts

   246     of the scene.

   247 

   248     \snippet examples/opengl/shared/qtlogo.cpp 4

   249 

   250     Finally the complete QtLogo scene is simply drawn by enabling the data arrays

   251     and then iterating over the parts, calling draw() on each one.

   252 

   253     \section1 Window Class Definition

   254 

   255     The \c Window class is used as a container for the \c GLWidget used to

   256     display the scene:

   257 

   258     \snippet examples/opengl/hellogl/window.h 0

   259 

   260     In addition, it contains sliders that are used to change the orientation

   261     of the object in the scene.

   262 

   263     \section1 Window Class Implementation

   264 

   265     The constructor constructs an instance of the \c GLWidget class and some

   266     sliders to manipulate its contents.

   267 

   268     \snippet examples/opengl/hellogl/window.cpp 0

   269 

   270     We connect the \l{QAbstractSlider::valueChanged()}{valueChanged()} signal

   271     from each of the sliders to the appropriate slots in \c{glWidget}.

   272     This allows the user to change the orientation of the object by dragging

   273     the sliders.

   274 

   275     We also connect the \c xRotationChanged(), \c yRotationChanged(), and

   276     \c zRotationChanged() signals from \c glWidget to the

   277     \l{QAbstractSlider::setValue()}{setValue()} slots in the

   278     corresponding sliders.

   279 

   280     \snippet examples/opengl/hellogl/window.cpp 1

   281 

   282     The sliders are placed horizontally in a layout alongside the \c GLWidget,

   283     and initialized with suitable default values.

   284 

   285     The \c createSlider() utility function constructs a QSlider, and ensures

   286     that it is set up with a suitable range, step value, tick interval, and

   287     page step value before returning it to the calling function:

   288 

   289     \snippet examples/opengl/hellogl/window.cpp 2

   290 

   291     \section1 Summary

   292 

   293     The \c GLWidget class implementation shows how to subclass QGLWidget for

   294     the purposes of rendering a 3D scene using OpenGL calls. Since QGLWidget

   295     is a subclass of QWidget, subclasses of QGLWidget can be placed in layouts

   296     and provided with interactive features just like normal custom widgets.

   297 

   298     We ensure that the widget is able to correctly render the scene using OpenGL

   299     by reimplementing the following functions:

   300 

   301     \list

   302     \o QGLWidget::initializeGL() sets up resources needed by the OpenGL implementation

   303        to render the scene.

   304     \o QGLWidget::resizeGL() resizes the viewport so that the rendered scene fits onto

   305        the widget, and sets up a projection matrix to map 3D coordinates to 2D viewport

   306        coordinates.

   307     \o QGLWidget::paintGL() performs painting operations using OpenGL calls.

   308     \endlist

   309 

   310     Since QGLWidget is a subclass of QWidget, it can also be used

   311     as a normal paint device, allowing 2D graphics to be drawn with QPainter.

   312     This use of QGLWidget is discussed in the \l{2D Painting Example}{2D Painting}

   313     example.

   314 

   315     More advanced users may want to paint over parts of a scene rendered using

   316     OpenGL. QGLWidget allows pure OpenGL rendering to be mixed with QPainter

   317     calls, but care must be taken to maintain the state of the OpenGL implementation.

   318     See the \l{Overpainting Example}{Overpainting} example for more information.

   319 */