|  | Home · Overviews · Examples |

# QGLWidget Class Reference
[com.trolltech.qt.opengl module]

The `QGLWidget` class is a widget for rendering OpenGL graphics. More...

Inherits `QWidget`.

## Detailed Description

The `QGLWidget` class is a widget for rendering OpenGL graphics.

`QGLWidget` provides functionality for displaying OpenGL graphics integrated into a Qt application. It is very simple to use. You inherit from it and use the subclass like any other `QWidget`, except that you have the choice between using `QPainter` and standard OpenGL rendering commands.

`QGLWidget` provides three convenient virtual functions that you can reimplement in your subclass to perform the typical OpenGL tasks:

- `paintGL` - Renders the OpenGL scene. Gets called whenever the widget needs to be updated.
- `resizeGL` - Sets up the OpenGL viewport, projection, etc. Gets called whenever the the widget has been resized (and also when it is shown for the first time because all newly created widgets get a resize event automatically).
- `initializeGL` - Sets up the OpenGL rendering context, defines display lists, etc. Gets called once before the first time `resizeGL` or `paintGL` is called.

Here is a rough outline of how a `QGLWidget` subclass might look:

        class MyGLDrawer : public QGLWidget
        {
            Q_OBJECT        // must include this if you use Qt signals/slots

        public:
            MyGLDrawer(QWidget *parent)
                : QGLWidget(parent) {}

        protected:

            void initializeGL()
            {
                // Set up the rendering context, define display lists etc.:
                ...
                glClearColor(0.0, 0.0, 0.0, 0.0);
                glEnable(GL_DEPTH_TEST);
                ...
            }

            void resizeGL(int w, int h)
            {
                // setup viewport, projection etc.:
                glViewport(0, 0, (GLint)w, (GLint)h);
                ...
                glFrustum(...);
                ...
            }

            void paintGL()
            {
                // draw the scene:
                ...
                glRotatef(...);
                glMaterialfv(...);
                glBegin(GL_QUADS);
                glVertex3f(...);
                glVertex3f(...);
                ...
                glEnd();
                ...
            }

        };

If you need to trigger a repaint from places other than `paintGL` (a typical example is when using timers to animate scenes), you should call the widget's `updateGL` function.

Your widget's OpenGL rendering context is made current when `paintGL`, `resizeGL`, or `initializeGL` is called. If you need to call the standard OpenGL API functions from other places (e.g. in your widget's constructor or in your own paint functions), you must call `makeCurrent` first.

`QGLWidget` provides functions for requesting a new display format and you can also create widgets with customized rendering contexts.

You can also share OpenGL display lists between QGLWidgets (see the documentation of the `QGLWidget` constructors for details).

### Overlays

The `QGLWidget` creates a GL overlay context in addition to the normal context if overlays are supported by the underlying system.

If you want to use overlays, you specify it in the format. (Note: Overlay must be requested in the format passed to the `QGLWidget` constructor.) Your GL widget should also implement some or all of these virtual methods:

- `paintOverlayGL`
- `resizeOverlayGL`
- `initializeOverlayGL`

These methods work in the same way as the normal `paintGL` etc. functions, except that they will be called when the overlay context is made current. You can explicitly make the overlay context current by using `makeOverlayCurrent`, and you can access the overlay context directly (e.g. to ask for its transparent color) by calling `overlayContext`.

On X servers in which the default visual is in an overlay plane, non-GL Qt windows can also be used for overlays.

### Painting Techniques

As described above, subclass `QGLWidget` to render pure 3D content in the following way:

- Reimplement the QGLWidget::initializeGL() and QGLWidget::resizeGL() to set up the OpenGL state and provide a perspective transformation.
- Reimplement QGLWidget::paintGL() to paint the 3D scene, calling only OpenGL functions to draw on the widget.

It is also possible to draw 2D graphics onto a `QGLWidget` subclass, it is necessary to reimplement QGLWidget::paintEvent() and do the following:

- Construct a `QPainter` object.
- Initialize it for use on the widget with the QPainter::begin() function.
- Draw primitives using `QPainter`'s member functions.
- Call QPainter::end() to finish painting.

Overpainting 2D content on top of 3D content takes a little more effort. One approach to doing this is shown in the Overpainting example.

OpenGL is a trademark of Silicon Graphics, Inc. in the United States and other countries.

See also `QGLPixelBuffer`, Hello GL Example, 2D Painting Example, Overpainting Example, and Grabber Example.