diff options
Diffstat (limited to 'doc/src/examples/hellogl.qdoc')
| -rw-r--r-- | doc/src/examples/hellogl.qdoc | 305 |
1 files changed, 305 insertions, 0 deletions
diff --git a/doc/src/examples/hellogl.qdoc b/doc/src/examples/hellogl.qdoc new file mode 100644 index 0000000000..b66eae97d3 --- /dev/null +++ b/doc/src/examples/hellogl.qdoc @@ -0,0 +1,305 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** 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. +*/ |