Overpainting Example

The Overpainting example shows how QPainter can be used to overpaint a scene rendered using OpenGL in a QGLWidget.

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 initializeGL() to initialize any required resources, resizeGL() to set up the projection and viewport, and 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 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 GLWidget class that enable overpainting, and provide more detailed discussion in the final section of this document.

GLWidget Class Definition

The GLWidget class is a subclass of QGLWidget, based on the one used in the 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:

As usual, the widget uses initializeGL() to set up objects for our scene and perform other OpenGL initialization tasks. The 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 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 animate() slot is called periodically by the animationTimer to update the widget; the createBubbles() function initializes the bubbles list with instances of a helper class used to draw the animation; the formatInstructions() function is responsible for a semi-transparent messages that is also overpainted onto the OpenGL scene.

GLWidget Class Implementation

Again, we only show the parts of the GLWidget implementation that are relevant to this example. In the constructor, we initialize a QTimer to control the animation:

For a small performance improvement, we set the widget's Qt::WA_NoSystemBackground attribute to instruct the underlying window system not to paint a background for the widget.

As in the Hello GL example, the destructor is responsible for freeing any OpenGL-related resources:

GLWidget::~GLWidget()
{
makeCurrent();
glDeleteLists(object, 1);
}

The initializeGL() function is fairly minimal, only setting up the display list used in the scene.

void GLWidget::initializeGL()
{
object = makeObject();
}

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 paintEvent() rather than 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 construct a QPainter for use on the widget before making any OpenGL calls.

After these calls, the OpenGL implementation is in the correct state for drawing 2D graphics. However, we first need to render a 3D scene by setting up model and projection transformations and other attributes. We use OpenGL stack operations to preserve the original state, allowing us to recover it later:

We call the setupViewport() private function to set up the projection used for the scene. This is unnecessary in OpenGL examples that implement the paintGL() function because the matrix stacks are usually unmodified between calls to resizeGL() and 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:

With the original state set by QPainter restored, we 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 QPainter::drawImage() to overlay some instructions:

Additionally, we take the opportunity to format the instructions to fit the width of the viewport.

Ideally, we want to arrange the 2D graphics to suit the widget's dimensions. To achieve this, we implement the showEvent() handler, creating new graphic elements (bubbles) if necessary at appropriate positions in the widget.

The instructions are painted onto a suitably-sized semi-transparent image that can be rendered using QPainter in the widget's paintEvent() handler function.

Резюме

When overpainting 2D content onto 3D content, we need to use a QPainterand 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:

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.