Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions |

# How to use X11 overlays with the Qt OpenGL extension

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: From version 5.0 onwards, 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. See the overlay example program. 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.

The provided example program X11 overlay will check for these and report if anything is wrong. See About X11 Visuals, below for more information.

## How it works

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. In the example program X11 overlay, the file `main.cpp` contains a routine that returns a QColor containing the transparent color. For the overlay widget, you will typically want to set the background color to the transparent color, so that the OpenGL image shows through except where explicitly overpainted.

Note: to use this technique, you must not use the `ManyColor` or `TrueColor` `ColorSpec` 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.

## About X11 visuals

The utilities directory contains two small programs that can help you determine the capabilities of your X server. These programs are from the OpenGL book mentioned above, see `utilities/NOTICE` for copyright information. The full set of example programs from this book is available at ftp://ftp.sgi.com/pub/opengl/opengl_for_x/.

`glxvisuals` lists all the GL-capable visuals the X server provides, together with the depth and other GL-specific information for each. Note especially the column "lvl"; a number in this column means that the visual is in an overlay plane.

`sovinfo` lists all available visuals, and provides special transparency information for overlay visuals.

The X11 overlay example program will output what visual is used for the normal Qt widgets, and what visual is used by the QGLWidget.