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

**

** 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/overpainting

    \title Overpainting Example

    The Overpainting example shows how QPainter can be used

    to overpaint a scene rendered using OpenGL in a QGLWidget.

    \image overpainting-example.png

    QGLWidget provides a widget with integrated OpenGL graphics support

    that enables 3D graphics to be displayed using normal OpenGL calls,

    yet also behaves like any other standard Qt widget with support for

    signals and slots, properties, and Qt's action system.

    Usually, QGLWidget is subclassed to display a pure 3D scene.  The

    developer reimplements \l{QGLWidget::initializeGL()}{initializeGL()}

    to initialize any required resources, \l{QGLWidget::resizeGL()}{resizeGL()}

    to set up the projection and viewport, and

    \l{QGLWidget::paintGL()}{paintGL()} to perform the OpenGL calls needed

    to render the scene. However, it is possible to subclass QGLWidget

    differently to allow 2D graphics, drawn using QPainter, to be

    painted over a scene rendered using OpenGL.

    In this example, we demonstrate how this is done by reusing the code

    from the \l{Hello GL Example}{Hello GL} example to provide a 3D scene,

    and painting over it with some translucent 2D graphics. Instead of

    examining each class in detail, we only cover the parts of the

    \c GLWidget class that enable overpainting, and provide more detailed

    discussion in the final section of this document.

    \section1 GLWidget Class Definition

    The \c GLWidget class is a subclass of QGLWidget, based on the one used

    in the \l{Hello GL Example}{Hello GL} example. Rather than describe the

    class as a whole, we show the first few lines of the class and only

    discuss the changes we have made to the rest of it:

    \snippet examples/opengl/overpainting/glwidget.h 0

    \dots

    \snippet examples/opengl/overpainting/glwidget.h 1

    \dots

    \snippet examples/opengl/overpainting/glwidget.h 4

    As usual, the widget uses \l{QGLWidget::initializeGL()}{initializeGL()}

    to set up geometry for our scene and perform OpenGL initialization tasks.

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

    the 3D graphics in the scene are transformed correctly to the 2D viewport

    displayed in the widget.

    Instead of implementing \l{QGLWidget::paintGL()}{paintGL()} to handle updates

    to the widget, we implement a normal QWidget::paintEvent(). This

    allows us to mix OpenGL calls and QPainter operations in a controlled way.

    In this example, we also implement QWidget::showEvent() to help with the

    initialization of the 2D graphics used.

    The new private member functions and variables relate exclusively to the

    2D graphics and animation. The \c animate() slot is called periodically by the

    \c animationTimer to update the widget; the \c createBubbles() function

    initializes the \c bubbles list with instances of a helper class used to

    draw the animation; the \c drawInstructions() function is responsible for

    a semi-transparent message that is also overpainted onto the OpenGL scene.

    \section1 GLWidget Class Implementation

    Again, we only show the parts of the \c GLWidget implementation that are

    relevant to this example. In the constructor, we initialize a QTimer to

    control the animation:

    \snippet examples/opengl/overpainting/glwidget.cpp 0

    We turn off the widget's \l{QWidget::autoFillBackground}{autoFillBackground} property to

    instruct OpenGL not to paint a background for the widget when

    \l{QPainter::begin()}{QPainter::begin()} is called.

    As in the \l{Hello GL Example}{Hello GL} example, the destructor is responsible

    for freeing any OpenGL-related resources:

    \snippet examples/opengl/overpainting/glwidget.cpp 1

    The \c initializeGL() function is fairly minimal, only setting up the QtLogo

    object used in the scene.  See the \l{Hello GL Example}{Hello GL} example

    for details of the QtLogo class.

    \snippet examples/opengl/overpainting/glwidget.cpp 2

    To cooperate fully with QPainter, we defer matrix stack operations and attribute

    initialization until the widget needs to be updated.

    In this example, we implement \l{QWidget::paintEvent()}{paintEvent()} rather

    than \l{QGLWidget::paintGL()}{paintGL()} to render

    our scene. When drawing on a QGLWidget, the paint engine used by QPainter

    performs certain operations that change the states of the OpenGL

    implementation's matrix and property stacks. Therefore, it is necessary to

    make all the OpenGL calls to display the 3D graphics before we construct

    a QPainter to draw the 2D overlay.

    We render a 3D scene by setting up model and projection transformations

    and other attributes. We use an OpenGL stack operation to preserve the

    original matrix state, allowing us to recover it later:

    \snippet examples/opengl/overpainting/glwidget.cpp 4

    We define a color to use for the widget's background, and set up various

    attributes that define how the scene will be rendered.

    \snippet examples/opengl/overpainting/glwidget.cpp 6

    We call the \c setupViewport() private function to set up the

    projection used for the scene. This is unnecessary in OpenGL

    examples that implement the \l{QGLWidget::paintGL()}{paintGL()}

    function because the matrix stacks are usually unmodified between

    calls to \l{QGLWidget::resizeGL()}{resizeGL()} and

    \l{QGLWidget::paintGL()}{paintGL()}.

    Since the widget's background is not drawn by the system or by Qt, we use

    an OpenGL call to paint it before positioning the object defined earlier

    in the scene:

    \snippet examples/opengl/overpainting/glwidget.cpp 7

    Once the QtLogo object's draw method has been executed, the GL

    states we changed and the matrix stack needs to be restored to its

    original state at the start of this function before we can begin

    overpainting:

    \snippet examples/opengl/overpainting/glwidget.cpp 8

    With the 3D graphics done, we construct a QPainter for use on the widget

    and simply overpaint the widget with 2D graphics; in this case, using a

    helper class to draw a number of translucent bubbles onto the widget,

    and calling \c drawInstructions() to overlay some instructions:

    \snippet examples/opengl/overpainting/glwidget.cpp 10

    When QPainter::end() is called, suitable OpenGL-specific calls are made to

    write the scene, and its additional contents, onto the widget.

    With \l{QGLWidget::paintGL()}{paintGL()} the

    \l{QGLWidget::swapBuffers()}{swapBuffers()} call is done for us.  But an explicit

    call to swapBuffers() is still not required because in the

    \l{QWidget::paintEvent()}{paintEvent()} method the QPainter on the OpenGL

    widget takes care of this for us.

    The implementation of the \l{QGLWidget::resizeGL()}{resizeGL()} function

    sets up the dimensions of the viewport and defines a projection

    transformation:

    \snippet examples/opengl/overpainting/glwidget.cpp 11

    Ideally, we want to arrange the 2D graphics to suit the widget's dimensions.

    To achieve this, we implement the \l{QWidget::showEvent()}{showEvent()} handler,

    creating new graphic elements (bubbles) if necessary at appropriate positions

    in the widget.

    \snippet examples/opengl/overpainting/glwidget.cpp 12

    This function only has an effect if less than 20 bubbles have already been

    created.

    The \c animate() slot is called every time the widget's \c animationTimer emits

    the \l{QTimer::timeout()}{timeout()} signal. This keeps the bubbles moving

    around.

    \snippet examples/opengl/overpainting/glwidget.cpp 13

    We simply iterate over the bubbles in the \c bubbles list, updating the

    widget before and after each of them is moved.

    The \c setupViewport() function is called from \c paintEvent()

    and \c resizeGL().

    \snippet examples/opengl/overpainting/glwidget.cpp 14

    The \c drawInstructions() function is used to prepare some basic

    instructions that will be painted with the other 2D graphics over

    the 3D scene.

    \snippet examples/opengl/overpainting/glwidget.cpp 15

    \section1 Summary

    When overpainting 2D content onto 3D content, we need to use a QPainter

    \e and make OpenGL calls to achieve the desired effect. Since QPainter

    itself uses OpenGL calls when used on a QGLWidget subclass, we need to

    preserve the state of various OpenGL stacks when we perform our own

    calls, using the following approach:

    \list

    \o Reimplement QGLWidget::initializeGL(), but only perform minimal

       initialization. QPainter will perform its own initialization

       routines, modifying the matrix and property stacks, so it is better

       to defer certain initialization tasks until just before you render

       the 3D scene.

    \o Reimplement QGLWidget::resizeGL() as in the pure 3D case.

    \o Reimplement QWidget::paintEvent() to draw both 2D and 3D graphics.

    \endlist

    The \l{QWidget::paintEvent()}{paintEvent()} implementation performs the

    following tasks:

    \list

    \o Push the current OpenGL modelview matrix onto a stack.

    \o Perform initialization tasks usually done in the

       \l{QGLWidget::initializeGL()}{initializeGL()} function.

    \o Perform code that would normally be located in the widget's

       \l{QGLWidget::resizeGL()}{resizeGL()} function to set the correct

       perspective transformation and set up the viewport.

    \o Render the scene using OpenGL calls.

    \o Pop the OpenGL modelview matrix off the stack.

    \o Construct a QPainter object.

    \o Initialize it for use on the widget with the QPainter::begin() function.

    \o Draw primitives using QPainter's member functions.

    \o Call QPainter::end() to finish painting.

    \endlist

*/