Modernize the OpenGL examples

Change them to use QOpenGLWidget and QOpenGLTexture.
Advocate also the usage of VBOs.

Hopeless examples, that rely on the fixed pipeline and will
not compile or work in ES and dynamic builds, are moved to
a "legacy" directory. The documentation pages for these are
removed. This long due change avoids the confusion newcomers
experience when trying to get started with Qt 5 and OpenGL.

hellowindow's behavior is changed to open a single window only
by default. The old default behavior, that opened three windows
on platforms that supported both MultipleWindows & ThreadedOpenGL,
can be requested by passing --multiple. --single is removed since it
is the default now. This plays much nicer with drivers that have
issues with threading.

In addition, say hello to hellogl2.

This is the old hellogl example updated to use QOpenGLWidget and
OpenGL 2. It also has a mainwindow with multiple (un)dockable widgets
containing the OpenGL widgets. This helps testing the behavior when
the top-level of the QOpenGLWidget changes and provides a very
important example of how to do proper resource management in this case.
(must use aboutToBeDestroyed() of the context, since the context goes
away and is replaced by a new one on every dock/undock)

As a bonus, the logo is now real 3D, no more orthographic nonsense.

Launch with --multisample to request 4x MSAA.

Launch with --coreprofile to request 3.2 Core. In this particular example
the shaders are present in both versions and there is a VAO so the application
is functional with core profile contexts.

Change-Id: Id780a80cb0708ef164cc172450ed74050f065596
Reviewed-by: Gunnar Sletta <gunnar.sletta@jollamobile.com>

17 files changed, 16 insertions, 722 deletions

diff --git a/examples/opengl/doc/images/framebufferobject2-example.png b/examples/opengl/doc/images/framebufferobject2-example.png
deleted file mode 100644
index bafb05a08b..0000000000
--- a/examples/opengl/doc/images/framebufferobject2-example.png
+++ /dev/null
diff --git a/examples/opengl/doc/images/grabber-example.png b/examples/opengl/doc/images/grabber-example.png
deleted file mode 100644
index 6a05b94bec..0000000000
--- a/examples/opengl/doc/images/grabber-example.png
+++ /dev/null
diff --git a/examples/opengl/doc/images/hellogl-es-example.png b/examples/opengl/doc/images/hellogl-es-example.png
deleted file mode 100644
index 7e55f09a7a..0000000000
--- a/examples/opengl/doc/images/hellogl-es-example.png
+++ /dev/null
diff --git a/examples/opengl/doc/images/hellogl-example.png b/examples/opengl/doc/images/hellogl-example.png
deleted file mode 100644
index ecb3a3a7b0..0000000000
--- a/examples/opengl/doc/images/hellogl-example.png
+++ /dev/null
diff --git a/examples/opengl/doc/images/hellogl2-example.png b/examples/opengl/doc/images/hellogl2-example.png
new file mode 100644
index 0000000000..5bb702e71c
--- /dev/null
+++ b/examples/opengl/doc/images/hellogl2-example.png
diff --git a/examples/opengl/doc/images/overpainting-example.png b/examples/opengl/doc/images/overpainting-example.png
deleted file mode 100644
index 0368dcabc8..0000000000
--- a/examples/opengl/doc/images/overpainting-example.png
+++ /dev/null
diff --git a/examples/opengl/doc/images/pbuffers-example.png b/examples/opengl/doc/images/pbuffers-example.png
deleted file mode 100644
index c34a6fd02b..0000000000
--- a/examples/opengl/doc/images/pbuffers-example.png
+++ /dev/null
diff --git a/examples/opengl/doc/images/pbuffers2-example.png b/examples/opengl/doc/images/pbuffers2-example.png
deleted file mode 100644
index 4a9c7175a3..0000000000
--- a/examples/opengl/doc/images/pbuffers2-example.png
+++ /dev/null
diff --git a/examples/opengl/doc/images/samplebuffers-example.png b/examples/opengl/doc/images/samplebuffers-example.png
deleted file mode 100644
index b751c143b3..0000000000
--- a/examples/opengl/doc/images/samplebuffers-example.png
+++ /dev/null
diff --git a/examples/opengl/doc/src/cube.qdoc b/examples/opengl/doc/src/cube.qdoc
index e6b2548cd1..ed1390db1a 100644
--- a/examples/opengl/doc/src/cube.qdoc
+++ b/examples/opengl/doc/src/cube.qdoc
@@ -117,7 +117,9 @@
     aren't facing towards screen.
 
     Creating vertex buffer objects and transferring data to them is quite simple using
-    OpenGL provided functions.
+    QOpenGLBuffer. MainWidget makes sure the GeometryEngine instance is created and
+    destroyed with the OpenGL context current. This way we can use OpenGL resources
+    in the constructor and perform proper cleanup in the destructor.
 
     \snippet cube/geometryengine.cpp 0
 
diff --git a/examples/opengl/doc/src/framebufferobject2.qdoc b/examples/opengl/doc/src/framebufferobject2.qdoc
deleted file mode 100644
index 33d641be10..0000000000
--- a/examples/opengl/doc/src/framebufferobject2.qdoc
+++ /dev/null
@@ -1,38 +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 framebufferobject2
-    \title Framebuffer Object 2 Example
-
-    \ingroup examples-widgets-opengl
-    \brief The Framebuffer Object 2 example demonstrates how to use the
-    QGLFramebufferObject class to render into an off-screen buffer and
-    use the contents as a texture in a QGLWidget.
-
-    \image framebufferobject2-example.png
-*/
diff --git a/examples/opengl/doc/src/grabber.qdoc b/examples/opengl/doc/src/grabber.qdoc
deleted file mode 100644
index fd2a2cf748..0000000000
--- a/examples/opengl/doc/src/grabber.qdoc
+++ /dev/null
@@ -1,36 +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 grabber
-    \title Grabber Example
-    \ingroup examples-widgets-opengl
-
-    \brief The Grabber examples shows how to retrieve the contents of an OpenGL framebuffer.
-
-    \image grabber-example.png
-*/
diff --git a/examples/opengl/doc/src/hellogl.qdoc b/examples/opengl/doc/src/hellogl.qdoc
deleted file mode 100644
index 9740c91408..0000000000
--- a/examples/opengl/doc/src/hellogl.qdoc
+++ /dev/null
@@ -1,320 +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 an update is scheduled.
-
-    Note that the widget's \l{QGLWidget::updateGL()}{updateGL()} function is not
-    called directly from here. Triggering rendering and buffer swaps directly
-    from the input event handlers is not desirable. Such events may, depending
-    on the platform, occur at a high frequency, and calling a potentially
-    blocking function like \l{QOpenGLContext::swapBuffers()}{swapBuffers} may
-    lead to unexpected results due to the main thread not being able to process
-    the input events at a proper rate.
-
-    Instead, update() is used. This will eventually lead to a paint event, which
-    will in turn invoke paintGL(). Multiple calls to update() in a row will make
-    no difference while the event is still pending. This way the UI will perform
-    equally well with blocking swaps, that is, a a
-    \l{QGLFormat::swapInterval()}{swap interval} of 1, and non-vsynced
-    configurations.
-
-    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.
-*/
diff --git a/examples/opengl/doc/src/pbuffers.qdoc b/examples/opengl/doc/src/hellogl2.qdoc
index 8e79ebb17c..adaf9d4719 100644
--- a/examples/opengl/doc/src/pbuffers.qdoc
+++ b/examples/opengl/doc/src/hellogl2.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 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.
@@ -26,13 +26,18 @@
 ****************************************************************************/
 
 /*!
-    \example pbuffers
-    \title Pixel Buffers Example
-
+    \example hellogl2
+    \title Hello GL2 Example
     \ingroup examples-widgets-opengl
-    \brief The Pixel Buffers example demonstrates how to use the
-    QGLPixelBuffer class to render into an off-screen buffer and use
-    the contents as a dynamic texture in a QGLWidget.
 
-    \image pbuffers-example.png
+    \brief The Hello GL2 example demonstrates the basic use of the OpenGL-related classes
+    provided with Qt.
+
+    \image hellogl2-example.png
+
+    Qt provides the QOpenGLWidget 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.
 */
diff --git a/examples/opengl/doc/src/overpainting.qdoc b/examples/opengl/doc/src/overpainting.qdoc
deleted file mode 100644
index e9cbbab2c4..0000000000
--- a/examples/opengl/doc/src/overpainting.qdoc
+++ /dev/null
@@ -1,244 +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 overpainting
-    \title Overpainting Example
-
-    \ingroup examples-widgets-opengl
-    \brief 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 overpainting/glwidget.h 0
-    \dots
-    \snippet overpainting/glwidget.h 1
-    \dots
-    \snippet 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 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 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 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 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 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 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 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 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 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 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 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 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 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
-    \li 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.
-    \li Reimplement QGLWidget::resizeGL() as in the pure 3D case.
-    \li Reimplement QWidget::paintEvent() to draw both 2D and 3D graphics.
-    \endlist
-
-    The \l{QWidget::paintEvent()}{paintEvent()} implementation performs the
-    following tasks:
-
-    \list
-    \li Push the current OpenGL modelview matrix onto a stack.
-    \li Perform initialization tasks usually done in the
-       \l{QGLWidget::initializeGL()}{initializeGL()} function.
-    \li 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.
-    \li Render the scene using OpenGL calls.
-    \li Pop the OpenGL modelview matrix off the stack.
-    \li Construct a QPainter object.
-    \li Initialize it for use on the widget with the QPainter::begin() function.
-    \li Draw primitives using QPainter's member functions.
-    \li Call QPainter::end() to finish painting.
-    \endlist
-*/
diff --git a/examples/opengl/doc/src/pbuffers2.qdoc b/examples/opengl/doc/src/pbuffers2.qdoc
deleted file mode 100644
index 249b8fa25f..0000000000
--- a/examples/opengl/doc/src/pbuffers2.qdoc
+++ /dev/null
@@ -1,38 +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 pbuffers2
-    \title Pixel Buffers 2 Example
-
-    \ingroup examples-widgets-opengl
-    \brief The Pixel Buffers 2 example demonstrates how to use the
-    QGLPixelBuffer class to render into an off-screen buffer and use
-    the contents as a dynamic texture in a QGLWidget.
-
-    \image pbuffers2-example.png
-*/
diff --git a/examples/opengl/doc/src/samplebuffers.qdoc b/examples/opengl/doc/src/samplebuffers.qdoc
deleted file mode 100644
index 4d4d26450e..0000000000
--- a/examples/opengl/doc/src/samplebuffers.qdoc
+++ /dev/null
@@ -1,37 +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 samplebuffers
-    \title Sample Buffers Example
-
-    \ingroup examples-widgets-opengl
-    \brief The Sample Buffers example demonstrates how to use and enable
-    sample buffers in a QGLWidget.
-
-    \image samplebuffers-example.png
-*/