source: trunk/doc/html/qglcontext.html

Last change on this file was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 18.0 KB
RevLine 
[190]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/opengl/qgl.cpp:733 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QGLContext Class</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QGLContext Class Reference<br><small>[<a href="opengl.html">OpenGL module</a>]</small></h1>
33
34<p>The QGLContext class encapsulates an OpenGL rendering context.
35<a href="#details">More...</a>
36<p><tt>#include &lt;<a href="qgl-h.html">qgl.h</a>&gt;</tt>
37<p>Inherits <a href="qgl.html">QGL</a>.
38<p><a href="qglcontext-members.html">List of all member functions.</a>
39<h2>Public Members</h2>
40<ul>
41<li class=fn><a href="#QGLContext"><b>QGLContext</b></a> ( const&nbsp;QGLFormat&nbsp;&amp;&nbsp;format, QPaintDevice&nbsp;*&nbsp;device )</li>
42<li class=fn>virtual <a href="#~QGLContext"><b>~QGLContext</b></a> ()</li>
43<li class=fn>virtual bool <a href="#create"><b>create</b></a> ( const&nbsp;QGLContext&nbsp;*&nbsp;shareContext = 0 )</li>
44<li class=fn>bool <a href="#isValid"><b>isValid</b></a> () const</li>
45<li class=fn>bool <a href="#isSharing"><b>isSharing</b></a> () const</li>
46<li class=fn>virtual void <a href="#reset"><b>reset</b></a> ()</li>
47<li class=fn>QGLFormat <a href="#format"><b>format</b></a> () const</li>
48<li class=fn>QGLFormat <a href="#requestedFormat"><b>requestedFormat</b></a> () const</li>
49<li class=fn>virtual void <a href="#setFormat"><b>setFormat</b></a> ( const&nbsp;QGLFormat&nbsp;&amp;&nbsp;format )</li>
50<li class=fn>virtual void <a href="#makeCurrent"><b>makeCurrent</b></a> ()</li>
51<li class=fn>virtual void <a href="#swapBuffers"><b>swapBuffers</b></a> () const</li>
52<li class=fn>QPaintDevice * <a href="#device"><b>device</b></a> () const</li>
53<li class=fn>QColor <a href="#overlayTransparentColor"><b>overlayTransparentColor</b></a> () const</li>
54</ul>
55<h2>Static Public Members</h2>
56<ul>
57<li class=fn>const QGLContext * <a href="#currentContext"><b>currentContext</b></a> ()</li>
58</ul>
59<h2>Protected Members</h2>
60<ul>
61<li class=fn>virtual bool <a href="#chooseContext"><b>chooseContext</b></a> ( const&nbsp;QGLContext&nbsp;*&nbsp;shareContext = 0 )</li>
62<li class=fn>virtual void <a href="#doneCurrent"><b>doneCurrent</b></a> ()</li>
63<li class=fn>virtual int <a href="#choosePixelFormat"><b>choosePixelFormat</b></a> ( void&nbsp;*&nbsp;dummyPfd, HDC&nbsp;pdc )</li>
64<li class=fn>virtual void * <a href="#chooseVisual"><b>chooseVisual</b></a> ()</li>
65<li class=fn>virtual void * <a href="#chooseMacVisual"><b>chooseMacVisual</b></a> ( GDHandle&nbsp;device )</li>
66<li class=fn>bool <a href="#deviceIsPixmap"><b>deviceIsPixmap</b></a> () const</li>
67<li class=fn>bool <a href="#windowCreated"><b>windowCreated</b></a> () const</li>
68<li class=fn>void <a href="#setWindowCreated"><b>setWindowCreated</b></a> ( bool&nbsp;on )</li>
69<li class=fn>bool <a href="#initialized"><b>initialized</b></a> () const</li>
70<li class=fn>void <a href="#setInitialized"><b>setInitialized</b></a> ( bool&nbsp;on )</li>
71<li class=fn>void <a href="#generateFontDisplayLists"><b>generateFontDisplayLists</b></a> ( const&nbsp;QFont&nbsp;&amp;&nbsp;font, int&nbsp;listBase )</li>
72</ul>
73<hr><a name="details"></a><h2>Detailed Description</h2>
74
75
76The QGLContext class encapsulates an OpenGL rendering context.
77
78<p>
79
80
81<p> An OpenGL<sup>*</sup> rendering context is a complete set of
82OpenGL state variables.
83<p> The context's <a href="qgl.html#FormatOption-enum">format</a> is set in the
84constructor or later with <a href="#setFormat">setFormat</a>(). The format options that are
85actually set are returned by <a href="#format">format</a>(); the options you asked for
86are returned by <a href="#requestedFormat">requestedFormat</a>(). Note that after a QGLContext
87object has been constructed, the actual OpenGL context must be
88created by explicitly calling the <a href="#create">create()</a>
89function. The <a href="#makeCurrent">makeCurrent</a>() function makes this context the
90current rendering context. You can make <em>no</em> context current
91using <a href="#doneCurrent">doneCurrent</a>(). The <a href="#reset">reset</a>() function will reset the context
92and make it invalid.
93<p> You can examine properties of the context with, e.g. <a href="#isValid">isValid</a>(),
94<a href="#isSharing">isSharing</a>(), <a href="#initialized">initialized</a>(), <a href="#windowCreated">windowCreated</a>() and
95<a href="#overlayTransparentColor">overlayTransparentColor</a>().
96<p> If you're using double buffering you can swap the screen contents
97with the off-screen buffer using <a href="#swapBuffers">swapBuffers</a>().
98<p> Please note that QGLContext is not thread safe.
99<p> <sup>*</sup> OpenGL is a trademark of Silicon Graphics, Inc. in the
100United States and other countries.
101<p> <p>See also <a href="graphics.html">Graphics Classes</a> and <a href="images.html">Image Processing Classes</a>.
102
103<hr><h2>Member Function Documentation</h2>
104<h3 class=fn><a name="QGLContext"></a>QGLContext::QGLContext ( const&nbsp;<a href="qglformat.html">QGLFormat</a>&nbsp;&amp;&nbsp;format, <a href="qpaintdevice.html">QPaintDevice</a>&nbsp;*&nbsp;device )
105</h3>
106Constructs an OpenGL context for the paint device <em>device</em>, which
107can be a widget or a pixmap. The <em>format</em> specifies several
108display options for the context.
109<p> If the underlying OpenGL/Window system cannot satisfy all the
110features requested in <em>format</em>, the nearest subset of features
111will be used. After creation, the <a href="#format">format</a>() method will return the
112actual format obtained.
113<p> Note that after a QGLContext object has been constructed, <a href="#create">create()</a> must be called explicitly to create
114the actual OpenGL context. The context will be <a href="#isValid">invalid</a> if it was not possible to obtain a GL context at
115all.
116<p> <p>See also <a href="#format">format</a>() and <a href="#isValid">isValid</a>().
117
118<h3 class=fn><a name="~QGLContext"></a>QGLContext::~QGLContext ()<tt> [virtual]</tt>
119</h3>
120Destroys the OpenGL context and frees its resources.
121
122<h3 class=fn>bool <a name="chooseContext"></a>QGLContext::chooseContext ( const&nbsp;<a href="qglcontext.html">QGLContext</a>&nbsp;*&nbsp;shareContext = 0 )<tt> [virtual protected]</tt>
123</h3>
124
125<p> This semi-internal function is called by <a href="#create">create</a>(). It creates a
126system-dependent OpenGL handle that matches the <a href="#format">format</a>() of <em>shareContext</em> as closely as possible.
127<p> On Windows, it calls the virtual function <a href="#choosePixelFormat">choosePixelFormat</a>(),
128which finds a matching pixel format identifier. On X11, it calls
129the virtual function <a href="#chooseVisual">chooseVisual</a>() which finds an appropriate X
130visual. On other platforms it may work differently.
131
132<h3 class=fn>void * <a name="chooseMacVisual"></a>QGLContext::chooseMacVisual ( GDHandle&nbsp;device )<tt> [virtual protected]</tt>
133</h3>
134
135<p> <strong>Mac only</strong>: This virtual function tries to find a
136visual that matches the format using the given <em>device</em> handle,
137reducing the demands if the original request cannot be met.
138<p> The algorithm for reducing the demands of the format is quite
139simple-minded, so override this method in your subclass if your
140application has specific requirements on visual selection.
141<p> <p>See also <a href="#chooseContext">chooseContext</a>().
142
143<h3 class=fn>int <a name="choosePixelFormat"></a>QGLContext::choosePixelFormat ( void&nbsp;*&nbsp;dummyPfd, HDC&nbsp;pdc )<tt> [virtual protected]</tt>
144</h3>
145<strong>Win32 only</strong> This virtual function chooses a pixel
146format that matches the OpenGL <a href="#setFormat">format</a>.
147Reimplement this function in a subclass if you need a custom
148context.
149<p> <b>Warning:</b> The <em>dummyPfd</em> pointer and <em>pdc</em> are used as a <tt>PIXELFORMATDESCRIPTOR*</tt>. We use <tt>void</tt> to avoid using
150Windows-specific types in our header files.
151<p> <p>See also <a href="#chooseContext">chooseContext</a>().
152
153<h3 class=fn>void * <a name="chooseVisual"></a>QGLContext::chooseVisual ()<tt> [virtual protected]</tt>
154</h3>
155<strong>X11 only</strong>: This virtual function tries to find a
156visual that matches the format, reducing the demands if the original
157request cannot be met.
158<p> The algorithm for reducing the demands of the format is quite
159simple-minded, so override this method in your subclass if your
160application has spcific requirements on visual selection.
161<p> <p>See also <a href="#chooseContext">chooseContext</a>().
162
163<h3 class=fn>bool <a name="create"></a>QGLContext::create ( const&nbsp;<a href="qglcontext.html">QGLContext</a>&nbsp;*&nbsp;shareContext = 0 )<tt> [virtual]</tt>
164</h3>
165Creates the GL context. Returns TRUE if it was successful in
166creating a valid GL rendering context on the paint device
167specified in the constructor; otherwise returns FALSE (i.e. the
168context is invalid).
169<p> After successful creation, <a href="#format">format</a>() returns the set of features of
170the created GL rendering context.
171<p> If <em>shareContext</em> points to a valid QGLContext, this method will
172try to establish OpenGL display list sharing between this context
173and the <em>shareContext</em>. Note that this may fail if the two
174contexts have different formats. Use <a href="#isSharing">isSharing</a>() to see if sharing
175succeeded.
176<p> <b>Warning:</b> Implementation note: initialization of C++ class
177members usually takes place in the class constructor. QGLContext
178is an exception because it must be simple to customize. The
179virtual functions <a href="#chooseContext">chooseContext</a>() (and <a href="#chooseVisual">chooseVisual</a>() for X11) can
180be reimplemented in a subclass to select a particular context. The
181problem is that virtual functions are not properly called during
182construction (even though this is correct C++) because C++
183constructs class hierarchies from the bottom up. For this reason
184we need a <a href="#create">create</a>() function.
185<p> <p>See also <a href="#chooseContext">chooseContext</a>(), <a href="#format">format</a>(), and <a href="#isValid">isValid</a>().
186
187<h3 class=fn>const&nbsp;<a href="qglcontext.html">QGLContext</a>&nbsp;* <a name="currentContext"></a>QGLContext::currentContext ()<tt> [static]</tt>
188</h3>
189
190<p> Returns the current context, i.e. the context to which any OpenGL
191commands will currently be directed. Returns 0 if no context is
192current.
193<p> <p>See also <a href="#makeCurrent">makeCurrent</a>().
194
195<h3 class=fn><a href="qpaintdevice.html">QPaintDevice</a>&nbsp;* <a name="device"></a>QGLContext::device () const
196</h3>
197
198<p> Returns the paint device set for this context.
199<p> <p>See also <a href="#QGLContext">QGLContext::QGLContext</a>().
200
201<h3 class=fn>bool <a name="deviceIsPixmap"></a>QGLContext::deviceIsPixmap () const<tt> [protected]</tt>
202</h3>
203
204<p> Returns TRUE if the paint device of this context is a pixmap;
205otherwise returns FALSE.
206
207<h3 class=fn>void <a name="doneCurrent"></a>QGLContext::doneCurrent ()<tt> [virtual protected]</tt>
208</h3>
209
210<p> Makes no GL context the current context. Normally, you do not need
211to call this function; QGLContext calls it as necessary.
212
213<h3 class=fn><a href="qglformat.html">QGLFormat</a> <a name="format"></a>QGLContext::format () const
214</h3>
215
216<p> Returns the frame buffer format that was obtained (this may be a
217subset of what was requested).
218<p> <p>See also <a href="#requestedFormat">requestedFormat</a>().
219
220<h3 class=fn>void <a name="generateFontDisplayLists"></a>QGLContext::generateFontDisplayLists ( const&nbsp;<a href="qfont.html">QFont</a>&nbsp;&amp;&nbsp;font, int&nbsp;listBase )<tt> [protected]</tt>
221</h3>
222
223<p> Generates a set of 256 display lists for the 256 first characters
224in the font <em>font</em>. The first list will start at index <em>listBase</em>.
225<p> <p>See also <a href="qglwidget.html#renderText">QGLWidget::renderText</a>().
226
227<h3 class=fn>bool <a name="initialized"></a>QGLContext::initialized () const<tt> [protected]</tt>
228</h3>
229
230<p> Returns TRUE if this context has been initialized, i.e. if
231<a href="qglwidget.html#initializeGL">QGLWidget::initializeGL</a>() has been performed on it; otherwise
232returns FALSE.
233<p> <p>See also <a href="#setInitialized">setInitialized</a>().
234
235<h3 class=fn>bool <a name="isSharing"></a>QGLContext::isSharing () const
236</h3>
237
238<p> Returns TRUE if display list sharing with another context was
239requested in the <a href="#create">create</a>() call and the GL system was able to
240fulfill this request; otherwise returns FALSE. Note that display
241list sharing might not be supported between contexts with
242different formats.
243
244<h3 class=fn>bool <a name="isValid"></a>QGLContext::isValid () const
245</h3>
246
247<p> Returns TRUE if a GL rendering context has been successfully
248created; otherwise returns FALSE.
249
250<h3 class=fn>void <a name="makeCurrent"></a>QGLContext::makeCurrent ()<tt> [virtual]</tt>
251</h3>
252
253<p> Makes this context the current OpenGL rendering context. All GL
254functions you call operate on this context until another context
255is made current.
256<p> In some very rare cases the underlying call may fail. If this
257occurs an error message is output to stderr.
258
259<h3 class=fn><a href="qcolor.html">QColor</a> <a name="overlayTransparentColor"></a>QGLContext::overlayTransparentColor () const
260</h3>
261
262<p> If this context is a valid context in an overlay plane, returns
263the plane's transparent color. Otherwise returns an <a href="qcolor.html#isValid">invalid</a> color.
264<p> The returned color's <a href="qcolor.html#pixel">pixel</a> value is
265the index of the transparent color in the colormap of the overlay
266plane. (Naturally, the color's RGB values are meaningless.)
267<p> The returned <a href="qcolor.html">QColor</a> object will generally work as expected only
268when passed as the argument to <a href="qglwidget.html#qglColor">QGLWidget::qglColor</a>() or
269<a href="qglwidget.html#qglClearColor">QGLWidget::qglClearColor</a>(). Under certain circumstances it can
270also be used to draw transparent graphics with a <a href="qpainter.html">QPainter</a>. See the
271examples/opengl/overlay_x11 example for details.
272
273<h3 class=fn><a href="qglformat.html">QGLFormat</a> <a name="requestedFormat"></a>QGLContext::requestedFormat () const
274</h3>
275
276<p> Returns the frame buffer format that was originally requested in
277the constructor or <a href="#setFormat">setFormat</a>().
278<p> <p>See also <a href="#format">format</a>().
279
280<h3 class=fn>void <a name="reset"></a>QGLContext::reset ()<tt> [virtual]</tt>
281</h3>
282
283<p> Resets the context and makes it invalid.
284<p> <p>See also <a href="#create">create</a>() and <a href="#isValid">isValid</a>().
285
286<h3 class=fn>void <a name="setFormat"></a>QGLContext::setFormat ( const&nbsp;<a href="qglformat.html">QGLFormat</a>&nbsp;&amp;&nbsp;format )<tt> [virtual]</tt>
287</h3>
288Sets a <em>format</em> for this context. The context is <a href="#reset">reset</a>.
289<p> Call <a href="#create">create</a>() to create a new GL context that tries to match the
290new format.
291<p> <pre>
292 QGLContext *cx;
293 // ...
294 <a href="qglformat.html">QGLFormat</a> f;
295 f.<a href="qglformat.html#setStereo">setStereo</a>( TRUE );
296 cx-&gt;<a href="#setFormat">setFormat</a>( f );
297 if ( !cx-&gt;<a href="#create">create</a>() )
298 exit(); // no OpenGL support, or cannot render on the specified paintdevice
299 if ( !cx-&gt;<a href="#format">format</a>().stereo() )
300 exit(); // could not create stereo context
301 </pre>
302
303<p> <p>See also <a href="#format">format</a>(), <a href="#reset">reset</a>(), and <a href="#create">create</a>().
304
305<h3 class=fn>void <a name="setInitialized"></a>QGLContext::setInitialized ( bool&nbsp;on )<tt> [protected]</tt>
306</h3>
307
308<p> If <em>on</em> is TRUE the context has been initialized, i.e.
309<a href="#setInitialized">QGLContext::setInitialized</a>() has been called on it. If <em>on</em> is
310FALSE the context has not been initialized.
311<p> <p>See also <a href="#initialized">initialized</a>().
312
313<h3 class=fn>void <a name="setWindowCreated"></a>QGLContext::setWindowCreated ( bool&nbsp;on )<tt> [protected]</tt>
314</h3>
315
316<p> If <em>on</em> is TRUE the context has had a window created for it. If
317<em>on</em> is FALSE no window has been created for the context.
318<p> <p>See also <a href="#windowCreated">windowCreated</a>().
319
320<h3 class=fn>void <a name="swapBuffers"></a>QGLContext::swapBuffers () const<tt> [virtual]</tt>
321</h3>
322
323<p> Swaps the screen contents with an off-screen buffer. Only works if
324the context is in double buffer mode.
325<p> <p>See also <a href="qglformat.html#setDoubleBuffer">QGLFormat::setDoubleBuffer</a>().
326
327<h3 class=fn>bool <a name="windowCreated"></a>QGLContext::windowCreated () const<tt> [protected]</tt>
328</h3>
329
330<p> Returns TRUE if a window has been created for this context;
331otherwise returns FALSE.
332<p> <p>See also <a href="#setWindowCreated">setWindowCreated</a>().
333
334<!-- eof -->
335<hr><p>
336This file is part of the <a href="index.html">Qt toolkit</a>.
337Copyright &copy; 1995-2007
338<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
339<table width=100% cellspacing=0 border=0><tr>
340<td>Copyright &copy; 2007
341<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
342<td align=right><div align=right>Qt 3.3.8</div>
343</table></div></address></body>
344</html>
Note: See TracBrowser for help on using the repository browser.