HOW TO USE X11 OVERLAYS WITH THE QT OPENGL EXTENSIONX11 overlays is a powerful mechanism that allows one to drawannotations etc. on top of an image without destroying it, thus savingsignificant image rendering time. For more information, consult thehighly recommended book "OpenGL Programming for the X Window System"(Mark Kilgard, Addison Wesley Developers Press 1996).-----------------------------------------------------------------------UPDATE: From version 5.0 onwards, the Qt OpenGL Extension includesdirect support for 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-QGLwidgets in overlay planes.-----------------------------------------------------------------------In the typical case, X11 overlays can easily be used together with thecurrent version of Qt and the Qt OpenGL Extension. The followingrequirements apply:1) Your X server and graphics card/hardware must support overlays (of   course). 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 destroy underlying images in the main plane, saving 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 deep TrueColor visuals in the main plane,   and an 8 bit PseudoColor (default) visual in the overlay plane.The provided example program "overlayrubber" will check for all thisand tell you what is wrong, if anything. See "About X11 Visuals" belowfor more information.How it works:-------------Given the above, a QGLWidget will by default use the main planevisual, while all other widgets will use the overlay visual. Thus, onecan place a normal widget on top of the QGLWidget, and do drawing init, without destroying the image in the OpenGL window. In other words,one can use all the drawing capabilities of QPainter to draw theannotations, rubberbands, whatever. For the typical use of overlays,this is much easier than using OpenGL for rendering the annotations.An overlay plane has a specific color called the transparentcolor. Pixels drawn in this color will not be visible, instead theunderlying OpenGL image will show through. In the example program"overlayrubber", the file main.cpp contains a routine that returns aQColor containing the transparent color. For the overlay widget, onewill typically want to set the background color to the transparentcolor, so that the OpenGL image shows through except where explicitlyoverpainted.Note: To use this technique, you must not use the "ManyColor" or"TrueColor" ColorSpec for the QApplication, because this will forcethe normal Qt widgets to use a TrueColor visual, which will typicallybe in the main plane, not in the overlay plane as desired.About X11 visuals:------------------The utilities directory contains two small programs that can help youdetermine the capabilities of your X server. These programs are fromthe OpenGL book mentioned above, see utilities/NOTICE for copyrightinformation. The full set of example programs from this book isavailable at ftp://ftp.sgi.com/pub/opengl/opengl_for_x/"glxvisuals" will list all the GL-capable visuals the X server provides,together with the depth and other GL-specific information foreach. Note especially the column "lvl"; a number in this column meansthe visual is in an overlay plane."sovinfo" will list all available visuals, and provides specialtransparency information for overlay visuals.The overlayrubber example program will output what visual is used forthe normal Qt widgets, and what visual is used by the QGLWidget.Comments are welcome at info@trolltech.com.