1 files changed, 92 insertions, 0 deletions
diff --git a/examples/opengl/overlay_x11/README.X11-OVERLAYS b/examples/opengl/overlay_x11/README.X11-OVERLAYS
new file mode 100644
index 000000000..6029ca3eb
--- /dev/null
+++ b/examples/opengl/overlay_x11/README.X11-OVERLAYS
@@ -0,0 +1,92 @@
+
+	 HOW TO USE X11 OVERLAYS WITH THE QT OPENGL EXTENSION
+
+X11 overlays is a powerful mechanism that allows one to draw
+annotations etc. on top of an image without destroying it, thus saving
+significant image rendering time. For more information, consult the
+highly 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 includes
+direct 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-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
+retquirements 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 this
+and tell you what is wrong, if anything. See "About X11 Visuals" below
+for more information.
+
+
+How it works:
+-------------
+
+Given the above, a QGLWidget will by default use the main plane
+visual, while all other widgets will use the overlay visual. Thus, one
+can place a normal widget on top of the QGLWidget, and do drawing in
+it, without destroying the image in the OpenGL window. In other words,
+one can use all the drawing capabilities of QPainter to draw the
+annotations, 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 transparent
+color. Pixels drawn in this color will not be visible, instead the
+underlying OpenGL image will show through. In the example program
+"overlayrubber", the file main.cpp contains a routine that returns a
+QColor containing the transparent color. For the overlay widget, one
+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 the 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" will list 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
+the visual is in an overlay plane.
+
+"sovinfo" will list all available visuals, and provides special
+transparency information for overlay visuals.
+
+The overlayrubber example program will output what visual is used for
+the normal Qt widgets, and what visual is used by the QGLWidget.
+
+
+
+Comments are welcome at [email protected].