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