--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/overpainting.qdoc Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,257 @@
+/****************************************************************************
+**
+** 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
+*/