1QGLContext(3qt)                                                QGLContext(3qt)
2
3
4

NAME

6       QGLContext - Encapsulates an OpenGL rendering context
7

SYNOPSIS

9       #include <qgl.h>
10
11       Inherits QGL.
12
13   Public Members
14       QGLContext ( const QGLFormat & format, QPaintDevice * device )
15       virtual ~QGLContext ()
16       virtual bool create ( const QGLContext * shareContext = 0 )
17       bool isValid () const
18       bool isSharing () const
19       virtual void reset ()
20       QGLFormat format () const
21       QGLFormat requestedFormat () const
22       virtual void setFormat ( const QGLFormat & format )
23       virtual void makeCurrent ()
24       virtual void swapBuffers () const
25       QPaintDevice * device () const
26       QColor overlayTransparentColor () const
27
28   Static Public Members
29       const QGLContext * currentContext ()
30
31   Protected Members
32       virtual bool chooseContext ( const QGLContext * shareContext = 0 )
33       virtual void doneCurrent ()
34       virtual int choosePixelFormat ( void * dummyPfd, HDC pdc )
35       virtual void * chooseVisual ()
36       virtual void * chooseMacVisual ( GDHandle device )
37       bool deviceIsPixmap () const
38       bool windowCreated () const
39       void setWindowCreated ( bool on )
40       bool initialized () const
41       void setInitialized ( bool on )
42       void generateFontDisplayLists ( const QFont & font, int listBase )
43

DESCRIPTION

45       The QGLContext class encapsulates an OpenGL rendering context.
46
47       An OpenGL<sup>*</sup> rendering context is a complete set of OpenGL
48       state variables.
49
50       The context's format is set in the constructor or later with
51       setFormat(). The format options that are actually set are returned by
52       format(); the options you asked for are returned by requestedFormat().
53       Note that after a QGLContext object has been constructed, the actual
54       OpenGL context must be created by explicitly calling the create()
55       function. The makeCurrent() function makes this context the current
56       rendering context. You can make no context current using doneCurrent().
57       The reset() function will reset the context and make it invalid.
58
59       You can examine properties of the context with, e.g. isValid(),
60       isSharing(), initialized(), windowCreated() and
61       overlayTransparentColor().
62
63       If you're using double buffering you can swap the screen contents with
64       the off-screen buffer using swapBuffers().
65
66       Please note that QGLContext is not thread safe.
67
68       <sup>*</sup> OpenGL is a trademark of Silicon Graphics, Inc. in the
69       United States and other countries.
70
71       See also Graphics Classes and Image Processing Classes.
72

MEMBER FUNCTION DOCUMENTATION

QGLContext::QGLContext ( const QGLFormat & format, QPaintDevice * device )

75       Constructs an OpenGL context for the paint device device, which can be
76       a widget or a pixmap. The format specifies several display options for
77       the context.
78
79       If the underlying OpenGL/Window system cannot satisfy all the features
80       requested in format, the nearest subset of features will be used. After
81       creation, the format() method will return the actual format obtained.
82
83       Note that after a QGLContext object has been constructed, create() must
84       be called explicitly to create the actual OpenGL context. The context
85       will be invalid if it was not possible to obtain a GL context at all.
86
87       See also format() and isValid().
88

QGLContext::~QGLContext () [virtual]

90       Destroys the OpenGL context and frees its resources.
91

bool QGLContext::chooseContext ( const QGLContext * shareContext = 0 )

93       [virtual protected]
94       This semi-internal function is called by create(). It creates a system-
95       dependent OpenGL handle that matches the format() of shareContext as
96       closely as possible.
97
98       On Windows, it calls the virtual function choosePixelFormat(), which
99       finds a matching pixel format identifier. On X11, it calls the virtual
100       function chooseVisual() which finds an appropriate X visual. On other
101       platforms it may work differently.
102

void * QGLContext::chooseMacVisual ( GDHandle device ) [virtual protected]

104       Mac only: This virtual function tries to find a visual that matches the
105       format using the given device handle, reducing the demands if the
106       original request cannot be met.
107
108       The algorithm for reducing the demands of the format is quite simple-
109       minded, so override this method in your subclass if your application
110       has specific requirements on visual selection.
111
112       See also chooseContext().
113

int QGLContext::choosePixelFormat ( void * dummyPfd, HDC pdc ) [virtual

115       protected]
116       Win32 only This virtual function chooses a pixel format that matches
117       the OpenGL format. Reimplement this function in a subclass if you need
118       a custom context.
119
120       Warning: The dummyPfd pointer and pdc are used as a
121       PIXELFORMATDESCRIPTOR*. We use void to avoid using Windows-specific
122       types in our header files.
123
124       See also chooseContext().
125

void * QGLContext::chooseVisual () [virtual protected]

127       X11 only: This virtual function tries to find a visual that matches the
128       format, reducing the demands if the original request cannot be met.
129
130       The algorithm for reducing the demands of the format is quite simple-
131       minded, so override this method in your subclass if your application
132       has spcific requirements on visual selection.
133
134       See also chooseContext().
135

bool QGLContext::create ( const QGLContext * shareContext = 0 ) [virtual]

137       Creates the GL context. Returns TRUE if it was successful in creating a
138       valid GL rendering context on the paint device specified in the
139       constructor; otherwise returns FALSE (i.e. the context is invalid).
140
141       After successful creation, format() returns the set of features of the
142       created GL rendering context.
143
144       If shareContext points to a valid QGLContext, this method will try to
145       establish OpenGL display list sharing between this context and the
146       shareContext. Note that this may fail if the two contexts have
147       different formats. Use isSharing() to see if sharing succeeded.
148
149       Warning: Implementation note: initialization of C++ class members
150       usually takes place in the class constructor. QGLContext is an
151       exception because it must be simple to customize. The virtual functions
152       chooseContext() (and chooseVisual() for X11) can be reimplemented in a
153       subclass to select a particular context. The problem is that virtual
154       functions are not properly called during construction (even though this
155       is correct C++) because C++ constructs class hierarchies from the
156       bottom up. For this reason we need a create() function.
157
158       See also chooseContext(), format(), and isValid().
159

const QGLContext * QGLContext::currentContext () [static]

161       Returns the current context, i.e. the context to which any OpenGL
162       commands will currently be directed. Returns 0 if no context is
163       current.
164
165       See also makeCurrent().
166

QPaintDevice * QGLContext::device () const

168       Returns the paint device set for this context.
169
170       See also QGLContext::QGLContext().
171

bool QGLContext::deviceIsPixmap () const [protected]

173       Returns TRUE if the paint device of this context is a pixmap; otherwise
174       returns FALSE.
175

void QGLContext::doneCurrent () [virtual protected]

177       Makes no GL context the current context. Normally, you do not need to
178       call this function; QGLContext calls it as necessary.
179

QGLFormat QGLContext::format () const

181       Returns the frame buffer format that was obtained (this may be a subset
182       of what was requested).
183
184       See also requestedFormat().
185

void QGLContext::generateFontDisplayLists ( const QFont & font, int listBase )

187       [protected]
188       Generates a set of 256 display lists for the 256 first characters in
189       the font font. The first list will start at index listBase.
190
191       See also QGLWidget::renderText().
192

bool QGLContext::initialized () const [protected]

194       Returns TRUE if this context has been initialized, i.e. if
195       QGLWidget::initializeGL() has been performed on it; otherwise returns
196       FALSE.
197
198       See also setInitialized().
199

bool QGLContext::isSharing () const

201       Returns TRUE if display list sharing with another context was requested
202       in the create() call and the GL system was able to fulfill this
203       request; otherwise returns FALSE. Note that display list sharing might
204       not be supported between contexts with different formats.
205

bool QGLContext::isValid () const

207       Returns TRUE if a GL rendering context has been successfully created;
208       otherwise returns FALSE.
209

void QGLContext::makeCurrent () [virtual]

211       Makes this context the current OpenGL rendering context. All GL
212       functions you call operate on this context until another context is
213       made current.
214
215       In some very rare cases the underlying call may fail. If this occurs an
216       error message is output to stderr.
217

QColor QGLContext::overlayTransparentColor () const

219       If this context is a valid context in an overlay plane, returns the
220       plane's transparent color. Otherwise returns an invalid color.
221
222       The returned color's pixel value is the index of the transparent color
223       in the colormap of the overlay plane. (Naturally, the color's RGB
224       values are meaningless.)
225
226       The returned QColor object will generally work as expected only when
227       passed as the argument to QGLWidget::qglColor() or
228       QGLWidget::qglClearColor(). Under certain circumstances it can also be
229       used to draw transparent graphics with a QPainter. See the
230       examples/opengl/overlay_x11 example for details.
231

QGLFormat QGLContext::requestedFormat () const

233       Returns the frame buffer format that was originally requested in the
234       constructor or setFormat().
235
236       See also format().
237

void QGLContext::reset () [virtual]

239       Resets the context and makes it invalid.
240
241       See also create() and isValid().
242

void QGLContext::setFormat ( const QGLFormat & format ) [virtual]

244       Sets a format for this context. The context is reset.
245
246       Call create() to create a new GL context that tries to match the new
247       format.
248
249           QGLContext *cx;
250           //  ...
251           QGLFormat f;
252           f.setStereo( TRUE );
253           cx->setFormat( f );
254           if ( !cx->create() )
255               exit(); // no OpenGL support, or cannot render on the specified paintdevice
256           if ( !cx->format().stereo() )
257               exit(); // could not create stereo context
258
259       See also format(), reset(), and create().
260

void QGLContext::setInitialized ( bool on ) [protected]

262       If on is TRUE the context has been initialized, i.e.
263       QGLContext::setInitialized() has been called on it. If on is FALSE the
264       context has not been initialized.
265
266       See also initialized().
267

void QGLContext::setWindowCreated ( bool on ) [protected]

269       If on is TRUE the context has had a window created for it. If on is
270       FALSE no window has been created for the context.
271
272       See also windowCreated().
273

void QGLContext::swapBuffers () const [virtual]

275       Swaps the screen contents with an off-screen buffer. Only works if the
276       context is in double buffer mode.
277
278       See also QGLFormat::setDoubleBuffer().
279

bool QGLContext::windowCreated () const [protected]

281       Returns TRUE if a window has been created for this context; otherwise
282       returns FALSE.
283
284       See also setWindowCreated().
285
286

SEE ALSO

288       http://doc.trolltech.com/qglcontext.html
289       http://www.trolltech.com/faq/tech.html
290
292       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
293       license file included in the distribution for a complete license
294       statement.
295

AUTHOR

297       Generated automatically from the source code.
298

BUGS

300       If you find a bug in Qt, please report it as described in
301       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
302       help you. Thank you.
303
304       The definitive Qt documentation is provided in HTML format; it is
305       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
306       web browser. This man page is provided as a convenience for those users
307       who prefer man pages, although this format is not officially supported
308       by Trolltech.
309
310       If you find errors in this manual page, please report them to qt-
311       bugs@trolltech.com.  Please include the name of the manual page
312       (qglcontext.3qt) and the Qt version (3.3.8).
313
314
315
316Trolltech AS                    2 February 2007                QGLContext(3qt)
Impressum