1QGLFormat(3qt) QGLFormat(3qt)
2
6 QGLFormat - The display format of an OpenGL rendering context
7
9 #include <qgl.h>
10 Inherits QGL.
12 Public Members
14 QGLFormat ()
15 QGLFormat ( int options, int plane = 0 )
16 bool doubleBuffer () const
17 void setDoubleBuffer ( bool enable )
18 bool depth () const
19 void setDepth ( bool enable )
20 bool rgba () const
21 void setRgba ( bool enable )
22 bool alpha () const
23 void setAlpha ( bool enable )
24 bool accum () const
25 void setAccum ( bool enable )
26 bool stencil () const
27 void setStencil ( bool enable )
28 bool stereo () const
29 void setStereo ( bool enable )
30 bool directRendering () const
31 void setDirectRendering ( bool enable )
32 bool hasOverlay () const
33 void setOverlay ( bool enable )
34 int plane () const
35 void setPlane ( int plane )
36 void setOption ( FormatOption opt )
37 bool testOption ( FormatOption opt ) const
38 Static Public Members
40 QGLFormat defaultFormat ()
41 void setDefaultFormat ( const QGLFormat & f )
42 QGLFormat defaultOverlayFormat ()
43 void setDefaultOverlayFormat ( const QGLFormat & f )
44 bool hasOpenGL ()
45 bool hasOpenGLOverlays ()
46
48 The QGLFormat class specifies the display format of an OpenGL rendering
49 context.
50 A display format has several characteristics:
52 Double or single buffering.
54 Depth buffer.
56 RGBA or color index mode.
58 Alpha channel.
60 Accumulation buffer.
62 Stencil buffer.
64 Stereo buffers.
66 Direct rendering.
68 Presence of an overlay.
70 The plane of an overlay format.
72 You create and tell a QGLFormat object what rendering options you want
74 from an OpenGL<sup>*</sup> rendering context.
75 OpenGL drivers or accelerated hardware may or may not support advanced
77 features such as alpha channel or stereographic viewing. If you request
78 some features that the driver/hardware does not provide when you create
79 a QGLWidget, you will get a rendering context with the nearest subset
80 of features.
81 There are different ways to define the display characteristics of a
83 rendering context. One is to create a QGLFormat and make it the default
84 for the entire application:
85 QGLFormat f;
87 f.setAlpha( TRUE );
88 f.setStereo( TRUE );
89 QGLFormat::setDefaultFormat( f );
90 Or you can specify the desired format when creating an object of your
92 QGLWidget subclass:
93 QGLFormat f;
95 f.setDoubleBuffer( FALSE ); // single buffer
96 f.setDirectRendering( FALSE ); // software rendering
97 MyGLWidget* myWidget = new MyGLWidget( f, ... );
98 After the widget has been created, you can find out which of the
100 requested features the system was able to provide:
101 QGLFormat f;
103 f.setOverlay( TRUE );
104 f.setStereo( TRUE );
105 MyGLWidget* myWidget = new MyGLWidget( f, ... );
106 if ( !w->format().stereo() ) {
107 // ok, goggles off
108 if ( !w->format().hasOverlay() ) {
109 qFatal( "Cool hardware required" );
110 }
111 }
112 <sup>*</sup> OpenGL is a trademark of Silicon Graphics, Inc. in the
114 United States and other countries.
115 See also QGLContext, QGLWidget, Graphics Classes, and Image Processing
117 Classes.
118
121 Constructs a QGLFormat object with the factory default settings:
122 Double buffer: Enabled.
124 Depth buffer: Enabled.
126 RGBA: Enabled (i.e., color index disabled).
128 Alpha channel: Disabled.
130 Accumulator buffer: Disabled.
132 Stencil buffer: Disabled.
134 Stereo: Disabled.
136 Direct rendering: Enabled.
138 Overlay: Disabled.
140 Plane: 0 (i.e., normal plane).
142
144 Creates a QGLFormat object that is a copy of the current application
145 default format.
146 If options is not 0, this copy is modified by these format options. The
148 options parameter should be FormatOption values OR'ed together.
149 This constructor makes it easy to specify a certain desired format in
151 classes derived from QGLWidget, for example:
152 // The rendering in MyGLWidget depends on using
154 // stencil buffer and alpha channel
155 MyGLWidget::MyGLWidget( QWidget* parent, const char* name )
156 : QGLWidget( QGLFormat( StencilBuffer | AlphaChannel ), parent, name )
157 {
158 if ( !format().stencil() )
159 qWarning( "Could not get stencil buffer; results will be suboptimal" );
160 if ( !format().alphaChannel() )
161 qWarning( "Could not get alpha channel; results will be suboptimal" );
162 ...
163 }
164 Note that there are FormatOption values to turn format settings both on
166 and off, e.g. DepthBuffer and NoDepthBuffer, DirectRendering and
167 IndirectRendering, etc.
168 The plane parameter defaults to 0 and is the plane which this format
170 should be associated with. Not all OpenGL implmentations supports
171 overlay/underlay rendering planes.
172 See also defaultFormat() and setOption().
174
176 Returns TRUE if the accumulation buffer is enabled; otherwise returns
177 FALSE. The accumulation buffer is disabled by default.
178 See also setAccum().
180
182 Returns TRUE if the alpha channel of the framebuffer is enabled;
183 otherwise returns FALSE. The alpha channel is disabled by default.
184 See also setAlpha().
186
188 Returns the default QGLFormat for the application. All QGLWidgets that
189 are created use this format unless another format is specified, e.g.
190 when they are constructed.
191 If no special default format has been set using setDefaultFormat(), the
193 default format is the same as that created with QGLFormat().
194 See also setDefaultFormat().
196
198 Returns the default QGLFormat for overlay contexts.
199 The factory default overlay format is:
201 Double buffer: Disabled.
203 Depth buffer: Disabled.
205 RGBA: Disabled (i.e., color index enabled).
207 Alpha channel: Disabled.
209 Accumulator buffer: Disabled.
211 Stencil buffer: Disabled.
213 Stereo: Disabled.
215 Direct rendering: Enabled.
217 Overlay: Disabled.
219 Plane: 1 (i.e., first overlay plane).
221 See also setDefaultFormat().
223
225 Returns TRUE if the depth buffer is enabled; otherwise returns FALSE.
226 The depth buffer is enabled by default.
227 See also setDepth().
229
231 Returns TRUE if direct rendering is enabled; otherwise returns FALSE.
232 Direct rendering is enabled by default.
234 See also setDirectRendering().
236
238 Returns TRUE if double buffering is enabled; otherwise returns FALSE.
239 Double buffering is enabled by default.
240 See also setDoubleBuffer().
242
244 Returns TRUE if the window system has any OpenGL support; otherwise
245 returns FALSE.
246 Warning: This function must not be called until the QApplication object
248 has been created.
249
251 Returns TRUE if the window system supports OpenGL overlays; otherwise
252 returns FALSE.
253 Warning: This function must not be called until the QApplication object
255 has been created.
256
258 Returns TRUE if overlay plane is enabled; otherwise returns FALSE.
259 Overlay is disabled by default.
261 See also setOverlay().
263
265 Returns the plane of this format. The default for normal formats is 0,
266 which means the normal plane. The default for overlay formats is 1,
267 which is the first overlay plane.
268 See also setPlane().
270
272 Returns TRUE if RGBA color mode is set. Returns FALSE if color index
273 mode is set. The default color mode is RGBA.
274 See also setRgba().
276
278 If enable is TRUE enables the accumulation buffer; otherwise disables
279 the accumulation buffer.
280 The accumulation buffer is disabled by default.
282 The accumulation buffer is used to create blur effects and multiple
284 exposures.
285 See also accum().
287
289 If enable is TRUE enables the alpha channel; otherwise disables the
290 alpha channel.
291 The alpha buffer is disabled by default.
293 The alpha channel is typically used for implementing transparency or
295 translucency. The A in RGBA specifies the transparency of a pixel.
296 See also alpha().
298
300 Sets a new default QGLFormat for the application to f. For example, to
301 set single buffering as the default instead of double buffering, your
302 main() might contain code like this:
303 QApplication a(argc, argv);
305 QGLFormat f;
306 f.setDoubleBuffer( FALSE );
307 QGLFormat::setDefaultFormat( f );
308 See also defaultFormat().
310
312 Sets a new default QGLFormat for overlay contexts to f. This format is
313 used whenever a QGLWidget is created with a format that hasOverlay()
314 enabled.
315 For example, to get a double buffered overlay context (if available),
317 use code like this:
318 QGLFormat f = QGLFormat::defaultOverlayFormat();
320 f.setDoubleBuffer( TRUE );
321 QGLFormat::setDefaultOverlayFormat( f );
322 As usual, you can find out after widget creation whether the underlying
324 OpenGL system was able to provide the requested specification:
325 // ...continued from above
327 MyGLWidget* myWidget = new MyGLWidget( QGLFormat( QGL::HasOverlay ), ... );
328 if ( myWidget->format().hasOverlay() ) {
329 // Yes, we got an overlay, let's check _its_ format:
330 QGLContext* olContext = myWidget->overlayContext();
331 if ( olContext->format().doubleBuffer() )
332 ; // yes, we got a double buffered overlay
333 else
334 ; // no, only single buffered overlays are available
335 }
336 See also defaultOverlayFormat().
338
340 If enable is TRUE enables the depth buffer; otherwise disables the
341 depth buffer.
342 The depth buffer is enabled by default.
344 The purpose of a depth buffer (or Z-buffering) is to remove hidden
346 surfaces. Pixels are assigned Z values based on the distance to the
347 viewer. A pixel with a high Z value is closer to the viewer than a
348 pixel with a low Z value. This information is used to decide whether to
349 draw a pixel or not.
350 See also depth().
352
354 If enable is TRUE enables direct rendering; otherwise disables direct
355 rendering.
356 Direct rendering is enabled by default.
358 Enabling this option will make OpenGL bypass the underlying window
360 system and render directly from hardware to the screen, if this is
361 supported by the system.
362 See also directRendering().
364
366 If enable is TRUE sets double buffering; otherwise sets single
367 buffering.
368 Double buffering is enabled by default.
370 Double buffering is a technique where graphics are rendered on an off-
372 screen buffer and not directly to the screen. When the drawing has been
373 completed, the program calls a swapBuffers() function to exchange the
374 screen contents with the buffer. The result is flicker-free drawing and
375 often better performance.
376 See also doubleBuffer(), QGLContext::swapBuffers(), and
378 QGLWidget::swapBuffers().
379
381 Sets the format option to opt.
382 See also testOption().
384
386 If enable is TRUE enables an overlay plane; otherwise disables the
387 overlay plane.
388 Enabling the overlay plane will cause QGLWidget to create an additional
390 context in an overlay plane. See the QGLWidget documentation for
391 further information.
392 See also hasOverlay().
394
396 Sets the requested plane to plane. 0 is the normal plane, 1 is the
397 first overlay plane, 2 is the second overlay plane, etc.; -1, -2, etc.
398 are underlay planes.
399 Note that in contrast to other format specifications, the plane
401 specifications will be matched exactly. This means that if you specify
402 a plane that the underlying OpenGL system cannot provide, an invalid
403 QGLWidget will be created.
404 See also plane().
406
408 If enable is TRUE sets RGBA mode. If enable is FALSE sets color index
409 mode.
410 The default color mode is RGBA.
412 RGBA is the preferred mode for most OpenGL applications. In RGBA color
414 mode you specify colors as red + green + blue + alpha quadruplets.
415 In color index mode you specify an index into a color lookup table.
417 See also rgba().
419
421 If enable is TRUE enables the stencil buffer; otherwise disables the
422 stencil buffer.
423 The stencil buffer is disabled by default.
425 The stencil buffer masks certain parts of the drawing area so that
427 masked parts are not drawn on.
428 See also stencil().
430
432 If enable is TRUE enables stereo buffering; otherwise disables stereo
433 buffering.
434 Stereo buffering is disabled by default.
436 Stereo buffering provides extra color buffers to generate left-eye and
438 right-eye images.
439 See also stereo().
441
443 Returns TRUE if the stencil buffer is enabled; otherwise returns FALSE.
444 The stencil buffer is disabled by default.
445 See also setStencil().
447
449 Returns TRUE if stereo buffering is enabled; otherwise returns FALSE.
450 Stereo buffering is disabled by default.
451 See also setStereo().
453
455 Returns TRUE if format option opt is set; otherwise returns FALSE.
456 See also setOption().
458
461 http://doc.trolltech.com/qglformat.html
462 http://www.trolltech.com/faq/tech.html
463
465 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
466 license file included in the distribution for a complete license
467 statement.
468
470 Generated automatically from the source code.
471
473 If you find a bug in Qt, please report it as described in
474 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
475 help you. Thank you.
476 The definitive Qt documentation is provided in HTML format; it is
478 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
479 web browser. This man page is provided as a convenience for those users
480 who prefer man pages, although this format is not officially supported
481 by Trolltech.
482 If you find errors in this manual page, please report them to qt-
484 bugs@trolltech.com. Please include the name of the manual page
485 (qglformat.3qt) and the Qt version (3.3.8).
486Trolltech AS 2 February 2007 QGLFormat(3qt)