Home · All Namespaces · All Classes · Main Classes · Grouped Classes · Modules · Functions

[Previous: QtNetwork Module] [Qt's Modules] [Next: QtSql Module]

QtOpenGL Module

The QtOpenGL module offers classes that make it easy to use OpenGL in Qt applications. More...

Namespaces

Classes

Detailed Description

OpenGL is a standard API for rendering 3D graphics. OpenGL only deals with 3D rendering and provides little or no support for GUI programming issues. The user interface for an OpenGL application must be created with another toolkit, such as Motif on the X platform, Microsoft Foundation Classes (MFC) under Windows, or Qt on both platforms.

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

The Qt OpenGL module makes it easy to use OpenGL in Qt applications. It provides an OpenGL widget class that can be used just like any other Qt widget, except that it opens an OpenGL display buffer where you can use the OpenGL API to render the contents.

To include the definitions of the module's classes, use the following directive:

 #include <QtOpenGL>

To link against the module, add this line to your qmake .pro file:

 QT += opengl

The Qt OpenGL module is implemented as a platform-independent Qt/C++ wrapper around the platform-dependent GLX (version 1.3 or later), WGL, or AGL C APIs. Although the basic functionality provided is very similar to Mark Kilgard's GLUT library, applications using the Qt OpenGL module can take advantage of the whole Qt API for non-OpenGL-specific GUI functionality.

Warning: The QtOpenGL module is part of the Qt Full Framework Edition and the Qt Open Source Edition. It is available on Windows, X11, and Mac OS X. Qt for Embedded Linux supports OpenGL ES (OpenGL for Embedded Systems). To be able to use the OpenGL API in Qt for Embedded Linux, it must be integrated with the Q Window System (QWS). See the Qt for Embedded Linux and OpenGL documentation for details.

Installation

When you install Qt for X11, the configure script will autodetect if OpenGL headers and libraries are installed on your system, and if so, it will include the QtOpenGL module in the Qt library. (If your OpenGL headers or libraries are placed in a non-standard directory, you may need to change the QMAKE_INCDIR_OPENGL and/or QMAKE_LIBDIR_OPENGL in the config file for your system).

When you install Qt for Windows and Mac OS X, the QtOpenGL module is always included. X11 users might like to read the notes on overlays below.

The QGL documentation assumes that you are familiar with OpenGL programming. If you're new to the subject a good starting point is http://www.opengl.org/.

How to Use X11 Overlays with Qt

X11 overlays are a powerful mechanism for drawing annotations etc., on top of an image without destroying it, thus saving a great deal of image rendering time. For more information, see the highly recommended book OpenGL Programming for the X Window System (Mark Kilgard, Addison Wesley Developers Press 1996).

Warning: The Qt OpenGL Extension includes direct support for the use of OpenGL overlays. For many uses of overlays, this makes the technique described below redundant. The following is a discussion on how to use non-QGL widgets in overlay planes.

In the typical case, X11 overlays can easily be used together with the current version of Qt and the Qt OpenGL Extension. The following requirements apply:

1. Your X server and graphics card/hardware must support overlays. For many X servers, overlay support can be turned on with a configuration option; consult your X server installation documentation.
2. Your X server must (be configured to) use an overlay visual as the default visual. Most modern X servers do this, since this has the added advantage that pop-up menus, overlapping windows etc., will not affect underlying images in the main plane, thereby avoiding expensive redraws.
3. The best (deepest) visual for OpenGL rendering is in the main plane. This is the normal case. Typically, X servers that support overlays provide a 24-bit TrueColor visual in the main plane, and an 8-bit PseudoColor (default) visual in the overlay plane.

Assuming that the requirements mentioned above are met, a QGLWidget will default to using the main plane visual, while all other widgets will use the overlay visual. Thus, we can place a normal widget on top of the QGLWidget, and do drawing on it, without affecting the image in the OpenGL window. In other words, we can use all the drawing capabilities of QPainter to draw annotations, rubberbands, etc. For the typical use of overlays, this is much easier than using OpenGL for rendering annotations.

An overlay plane has a specific color called the transparent color. Pixels drawn in this color will not be visible; instead the underlying OpenGL image will show through.

To use this technique, you must not use the QApplication::ManyColor or QApplication::TrueColor color specification for QApplication, because this will force the normal Qt widgets to use a TrueColor visual, which will typically be in the main plane, not in the overlay plane as desired.

[Previous: QtNetwork Module] [Qt's Modules] [Next: QtSql Module]