diff options
Diffstat (limited to 'examples/opengl/doc/src/hellogl.qdoc')
| -rw-r--r-- | examples/opengl/doc/src/hellogl.qdoc | 306 |
1 files changed, 0 insertions, 306 deletions
diff --git a/examples/opengl/doc/src/hellogl.qdoc b/examples/opengl/doc/src/hellogl.qdoc deleted file mode 100644 index b4aef0ae02..0000000000 --- a/examples/opengl/doc/src/hellogl.qdoc +++ /dev/null @@ -1,306 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/legal -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example hellogl - \title Hello GL Example - \ingroup examples-widgets-opengl - - \brief 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 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 hellogl/glwidget.h 1 - - The signals and slots are used to allow other objects to interact with the - 3D scene. - - \snippet 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 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 hellogl/glwidget.cpp 0 - - We also implement a destructor to release OpenGL-related resources when the - widget is deleted: - - \snippet 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 hellogl/glwidget.cpp 2 - \codeline - \snippet hellogl/glwidget.cpp 3 - \snippet hellogl/glwidget.cpp 4 - - The widget provides three slots that enable other components in the - example to change the orientation of the scene: - - \snippet 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 - \li QGLWidget::initializeGL() sets up resources needed by the OpenGL implementation - to render the scene. - \li 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. - \li 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. -*/ |