1 files changed, 132 insertions, 0 deletions
diff --git a/doc/opengl-x11-overlays.doc b/doc/opengl-x11-overlays.doc
new file mode 100644
index 0000000..9c31002
--- /dev/null
+++ b/doc/opengl-x11-overlays.doc
@@ -0,0 +1,132 @@
+/****************************************************************************
+**
+** ...
+**
+** Copyright (C) 2005-2008 Trolltech ASA.  All rights reserved.
+**
+** This file is part of the Qt GUI Toolkit.
+**
+** This file may be used under the terms of the GNU General
+** Public License versions 2.0 or 3.0 as published by the Free
+** Software Foundation and appearing in the files LICENSE.GPL2
+** and LICENSE.GPL3 included in the packaging of this file.
+** Alternatively you may (at your option) use any later version
+** of the GNU General Public License if such license has been
+** publicly approved by Trolltech ASA (or its successors, if any)
+** and the KDE Free Qt Foundation.
+**
+** Please review the following information to ensure GNU General
+** Public Licensing requirements will be met:
+** http://trolltech.com/products/qt/licenses/licensing/opensource/.
+** If you are unsure which license is appropriate for your use, please
+** review the following information:
+** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
+** or contact the sales department at sales@trolltech.com.
+**
+** This file may be used under the terms of the Q Public License as
+** defined by Trolltech ASA and appearing in the file LICENSE.QPL
+** included in the packaging of this file.  Licensees holding valid Qt
+** Commercial licenses may use this file in accordance with the Qt
+** Commercial License Agreement provided with the Software.
+**
+** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
+** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
+** herein.
+**
+**********************************************************************/
+
+/*!
+    \page opengl-x11-overlays.html
+
+    \title 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, consult the highly
+recommended book \e{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
+\link opengl-overlay-example.html overlay\endlink 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:
+
+\list 1
+\i 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.
+
+\i 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
+   \e not destroy underlying images in the main plane, thereby
+   avoiding expensive redraws.
+
+\i 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 visual in the main plane,
+   and an 8 bit PseudoColor (default) visual in the overlay plane.
+\endlist
+
+The provided example program \link opengl-overlay-example.html X11
+overlay\endlink will check for these and report if anything is wrong. 
+See \link #x11visuals About X11 Visuals\endlink, below for more
+information.
+
+
+\section1 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, we
+can place a normal widget on top of the QGLWidget, and do drawing on
+it, without destroying the image in the OpenGL window. In other words,
+we can use all the drawing capabilities of QPainter to draw the
+annotations, rubberbands, etc. 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
+\link opengl-overlay-example.html X11 overlay\endlink, the file
+\c 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.
+
+
+
+\target x11visuals
+\section1 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 \l{ftp://ftp.sgi.com/pub/opengl/opengl_for_x/}.
+
+\c 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.
+
+\c sovinfo will list all available visuals, and provides special
+transparency information for overlay visuals.
+
+The \link opengl-overlay-example.html X11 overlay\endlink example
+program will output what visual is used for the normal Qt widgets, and
+what visual is used by the QGLWidget.
+
+*/