From d796c9dd933ab96ec83b9a634feedd5d32e1ba3f Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 8 Nov 2011 12:31:36 -0600 Subject: Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731 --- doc/html/opengl-x11-overlays.html | 115 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 doc/html/opengl-x11-overlays.html (limited to 'doc/html/opengl-x11-overlays.html') diff --git a/doc/html/opengl-x11-overlays.html b/doc/html/opengl-x11-overlays.html new file mode 100644 index 000000000..381582890 --- /dev/null +++ b/doc/html/opengl-x11-overlays.html @@ -0,0 +1,115 @@ + + + + + +How to use X11 overlays with the TQt OpenGL extension + + + + + + + +

How to use X11 overlays with the TQt 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 OpenGL Programming for the X Window System (Mark +Kilgard, Addison Wesley Developers Press 1996). +

Warning: From version 5.0 onwards, the TQt 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-TQGL widgets in overlay +planes. +

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

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. +
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, thereby +avoiding expensive redraws. +
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. +

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 +

Given the above, a TQGLWidget 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 TQGLWidget, and do drawing on +it, without destroying the image in the OpenGL window. In other words, +we can use all the drawing capabilities of TQPainter 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 +X11 overlay, the file +main.cpp contains a routine that returns a TQColor 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 TQApplication, because this will force +the normal TQt 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 X11 overlay example +program will output what visual is used for the normal TQt widgets, and +what visual is used by the TQGLWidget. +

+ +

Trademarks +

TQt 3.3.8

+ -- cgit v1.2.1