|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
requirements 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 info@trolltech.com.
|
