/****************************************************************************

**

** Copyright (C) 2009 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: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 Technology Preview License Agreement accompanying

** this package.

**

** 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.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@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 (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.

*/