summaryrefslogtreecommitdiffstats
path: root/doc/html/opengl-x11-overlays.html
blob: df139e84dd1957148e829ef03b129fd2c5151f6b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/opengl-x11-overlays.doc:36 -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>How to use X11 overlays with the TQt OpenGL extension</title>
<style type="text/css"><!--
fn { margin-left: 1cm; text-indent: -1cm; }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
body { background: #ffffff; color: black; }
--></style>
</head>
<body>

<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr bgcolor="#E5E5E5">
<td valign=center>
 <a href="index.html">
<font color="#004faf">Home</font></a>
 | <a href="classes.html">
<font color="#004faf">All&nbsp;Classes</font></a>
 | <a href="mainclasses.html">
<font color="#004faf">Main&nbsp;Classes</font></a>
 | <a href="annotated.html">
<font color="#004faf">Annotated</font></a>
 | <a href="groups.html">
<font color="#004faf">Grouped&nbsp;Classes</font></a>
 | <a href="functions.html">
<font color="#004faf">Functions</font></a>
</td>
<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>How to use X11 overlays with the TQt OpenGL extension</h1>



<p> 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 <em>OpenGL Programming for the X Window System</em> (Mark
Kilgard, Addison Wesley Developers Press 1996).
<p> <b>Warning:</b> 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
<a href="opengl-overlay-example.html">overlay</a> example program. The
following is a discussion on how to use non-TQGL widgets in overlay
planes.
<p> In the typical case, X11 overlays can easily be used together with the
current version of TQt and the TQt OpenGL Extension. The following
requirements apply:
<p> <ol type=1>
<li> 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.
<p> <li> 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
<em>not</em> destroy underlying images in the main plane, thereby
avoiding expensive redraws.
<p> <li> 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.
</ol>
<p> The provided example program <a href="opengl-overlay-example.html">X11
overlay</a> will check for these and report if anything is wrong. 
See <a href="#x11visuals">About X11 Visuals</a>, below for more
information.
<p> <h2> How it works
</h2>
<a name="1"></a><p> Given the above, a <a href="qglwidget.html">TQGLWidget</a> 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 <a href="qpainter.html">TQPainter</a> to draw the
annotations, rubberbands, etc. For the typical use of overlays,
this is much easier than using OpenGL for rendering the annotations.
<p> 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
<a href="opengl-overlay-example.html">X11 overlay</a>, the file
<tt>main.cpp</tt> contains a routine that returns a <a href="qcolor.html">TQColor</a> 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.
<p> Note: to use this technique, you must not use the "ManyColor" or
"TrueColor" ColorSpec for <a href="qapplication.html">TQApplication</a>, 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.
<p> <a name="x11visuals"></a>
<h2> About X11 visuals
</h2>
<a name="2"></a><p> 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 <a href="ftp://ftp.sgi.com/pub/opengl/opengl_for_x/">ftp://ftp.sgi.com/pub/opengl/opengl_for_x/</a>.
<p> <tt>glxvisuals</tt> 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.
<p> <tt>sovinfo</tt> will list all available visuals, and provides special
transparency information for overlay visuals.
<p> The <a href="opengl-overlay-example.html">X11 overlay</a> example
program will output what visual is used for the normal TQt widgets, and
what visual is used by the <a href="qglwidget.html">TQGLWidget</a>.
<p> 
<!-- eof -->
<p><address><hr><div align=center>
<table width=100% cellspacing=0 border=0><tr>
<td>Copyright &copy; 2007
<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
<td align=right><div align=right>TQt 3.3.8</div>
</table></div></address></body>
</html>