1QGLFormat(3qt)                                                  QGLFormat(3qt)
2
3
4

NAME

6       QGLFormat - The display format of an OpenGL rendering context
7

SYNOPSIS

9       #include <qgl.h>
10
11       Inherits QGL.
12
13   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
39   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

DESCRIPTION

48       The QGLFormat class specifies the display format of an OpenGL rendering
49       context.
50
51       A display format has several characteristics:
52
53       Double or single buffering.
54
55       Depth buffer.
56
57       RGBA or color index mode.
58
59       Alpha channel.
60
61       Accumulation buffer.
62
63       Stencil buffer.
64
65       Stereo buffers.
66
67       Direct rendering.
68
69       Presence of an overlay.
70
71       The plane of an overlay format.
72
73       You create and tell a QGLFormat object what rendering options you want
74       from an OpenGL<sup>*</sup> rendering context.
75
76       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
82       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
86           QGLFormat f;
87           f.setAlpha( TRUE );
88           f.setStereo( TRUE );
89           QGLFormat::setDefaultFormat( f );
90
91       Or you can specify the desired format when creating an object of your
92       QGLWidget subclass:
93
94           QGLFormat f;
95           f.setDoubleBuffer( FALSE );                 // single buffer
96           f.setDirectRendering( FALSE );              // software rendering
97           MyGLWidget* myWidget = new MyGLWidget( f, ... );
98
99       After the widget has been created, you can find out which of the
100       requested features the system was able to provide:
101
102           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
113       <sup>*</sup> OpenGL is a trademark of Silicon Graphics, Inc. in the
114       United States and other countries.
115
116       See also QGLContext, QGLWidget, Graphics Classes, and Image Processing
117       Classes.
118

MEMBER FUNCTION DOCUMENTATION

QGLFormat::QGLFormat ()

121       Constructs a QGLFormat object with the factory default settings:
122
123       Double buffer: Enabled.
124
125       Depth buffer: Enabled.
126
127       RGBA: Enabled (i.e., color index disabled).
128
129       Alpha channel: Disabled.
130
131       Accumulator buffer: Disabled.
132
133       Stencil buffer: Disabled.
134
135       Stereo: Disabled.
136
137       Direct rendering: Enabled.
138
139       Overlay: Disabled.
140
141       Plane: 0 (i.e., normal plane).
142

QGLFormat::QGLFormat ( int options, int plane = 0 )

144       Creates a QGLFormat object that is a copy of the current application
145       default format.
146
147       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
150       This constructor makes it easy to specify a certain desired format in
151       classes derived from QGLWidget, for example:
152
153           // 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
165       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
169       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
173       See also defaultFormat() and setOption().
174

bool QGLFormat::accum () const

176       Returns TRUE if the accumulation buffer is enabled; otherwise returns
177       FALSE. The accumulation buffer is disabled by default.
178
179       See also setAccum().
180

bool QGLFormat::alpha () const

182       Returns TRUE if the alpha channel of the framebuffer is enabled;
183       otherwise returns FALSE. The alpha channel is disabled by default.
184
185       See also setAlpha().
186

QGLFormat QGLFormat::defaultFormat () [static]

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
192       If no special default format has been set using setDefaultFormat(), the
193       default format is the same as that created with QGLFormat().
194
195       See also setDefaultFormat().
196

QGLFormat QGLFormat::defaultOverlayFormat () [static]

198       Returns the default QGLFormat for overlay contexts.
199
200       The factory default overlay format is:
201
202       Double buffer: Disabled.
203
204       Depth buffer: Disabled.
205
206       RGBA: Disabled (i.e., color index enabled).
207
208       Alpha channel: Disabled.
209
210       Accumulator buffer: Disabled.
211
212       Stencil buffer: Disabled.
213
214       Stereo: Disabled.
215
216       Direct rendering: Enabled.
217
218       Overlay: Disabled.
219
220       Plane: 1 (i.e., first overlay plane).
221
222       See also setDefaultFormat().
223

bool QGLFormat::depth () const

225       Returns TRUE if the depth buffer is enabled; otherwise returns FALSE.
226       The depth buffer is enabled by default.
227
228       See also setDepth().
229

bool QGLFormat::directRendering () const

231       Returns TRUE if direct rendering is enabled; otherwise returns FALSE.
232
233       Direct rendering is enabled by default.
234
235       See also setDirectRendering().
236

bool QGLFormat::doubleBuffer () const

238       Returns TRUE if double buffering is enabled; otherwise returns FALSE.
239       Double buffering is enabled by default.
240
241       See also setDoubleBuffer().
242

bool QGLFormat::hasOpenGL () [static]

244       Returns TRUE if the window system has any OpenGL support; otherwise
245       returns FALSE.
246
247       Warning: This function must not be called until the QApplication object
248       has been created.
249

bool QGLFormat::hasOpenGLOverlays () [static]

251       Returns TRUE if the window system supports OpenGL overlays; otherwise
252       returns FALSE.
253
254       Warning: This function must not be called until the QApplication object
255       has been created.
256

bool QGLFormat::hasOverlay () const

258       Returns TRUE if overlay plane is enabled; otherwise returns FALSE.
259
260       Overlay is disabled by default.
261
262       See also setOverlay().
263

int QGLFormat::plane () const

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
269       See also setPlane().
270

bool QGLFormat::rgba () const

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
275       See also setRgba().
276

void QGLFormat::setAccum ( bool enable )

278       If enable is TRUE enables the accumulation buffer; otherwise disables
279       the accumulation buffer.
280
281       The accumulation buffer is disabled by default.
282
283       The accumulation buffer is used to create blur effects and multiple
284       exposures.
285
286       See also accum().
287

void QGLFormat::setAlpha ( bool enable )

289       If enable is TRUE enables the alpha channel; otherwise disables the
290       alpha channel.
291
292       The alpha buffer is disabled by default.
293
294       The alpha channel is typically used for implementing transparency or
295       translucency. The A in RGBA specifies the transparency of a pixel.
296
297       See also alpha().
298

void QGLFormat::setDefaultFormat ( const QGLFormat & f ) [static]

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
304           QApplication a(argc, argv);
305           QGLFormat f;
306           f.setDoubleBuffer( FALSE );
307           QGLFormat::setDefaultFormat( f );
308
309       See also defaultFormat().
310

void QGLFormat::setDefaultOverlayFormat ( const QGLFormat & f ) [static]

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
316       For example, to get a double buffered overlay context (if available),
317       use code like this:
318
319           QGLFormat f = QGLFormat::defaultOverlayFormat();
320           f.setDoubleBuffer( TRUE );
321           QGLFormat::setDefaultOverlayFormat( f );
322
323       As usual, you can find out after widget creation whether the underlying
324       OpenGL system was able to provide the requested specification:
325
326           // ...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
337       See also defaultOverlayFormat().
338

void QGLFormat::setDepth ( bool enable )

340       If enable is TRUE enables the depth buffer; otherwise disables the
341       depth buffer.
342
343       The depth buffer is enabled by default.
344
345       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
351       See also depth().
352

void QGLFormat::setDirectRendering ( bool enable )

354       If enable is TRUE enables direct rendering; otherwise disables direct
355       rendering.
356
357       Direct rendering is enabled by default.
358
359       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
363       See also directRendering().
364

void QGLFormat::setDoubleBuffer ( bool enable )

366       If enable is TRUE sets double buffering; otherwise sets single
367       buffering.
368
369       Double buffering is enabled by default.
370
371       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
377       See also doubleBuffer(), QGLContext::swapBuffers(), and
378       QGLWidget::swapBuffers().
379

void QGLFormat::setOption ( FormatOption opt )

381       Sets the format option to opt.
382
383       See also testOption().
384

void QGLFormat::setOverlay ( bool enable )

386       If enable is TRUE enables an overlay plane; otherwise disables the
387       overlay plane.
388
389       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
393       See also hasOverlay().
394

void QGLFormat::setPlane ( int plane )

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
400       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
405       See also plane().
406

void QGLFormat::setRgba ( bool enable )

408       If enable is TRUE sets RGBA mode. If enable is FALSE sets color index
409       mode.
410
411       The default color mode is RGBA.
412
413       RGBA is the preferred mode for most OpenGL applications. In RGBA color
414       mode you specify colors as red + green + blue + alpha quadruplets.
415
416       In color index mode you specify an index into a color lookup table.
417
418       See also rgba().
419

void QGLFormat::setStencil ( bool enable )

421       If enable is TRUE enables the stencil buffer; otherwise disables the
422       stencil buffer.
423
424       The stencil buffer is disabled by default.
425
426       The stencil buffer masks certain parts of the drawing area so that
427       masked parts are not drawn on.
428
429       See also stencil().
430

void QGLFormat::setStereo ( bool enable )

432       If enable is TRUE enables stereo buffering; otherwise disables stereo
433       buffering.
434
435       Stereo buffering is disabled by default.
436
437       Stereo buffering provides extra color buffers to generate left-eye and
438       right-eye images.
439
440       See also stereo().
441

bool QGLFormat::stencil () const

443       Returns TRUE if the stencil buffer is enabled; otherwise returns FALSE.
444       The stencil buffer is disabled by default.
445
446       See also setStencil().
447

bool QGLFormat::stereo () const

449       Returns TRUE if stereo buffering is enabled; otherwise returns FALSE.
450       Stereo buffering is disabled by default.
451
452       See also setStereo().
453

bool QGLFormat::testOption ( FormatOption opt ) const

455       Returns TRUE if format option opt is set; otherwise returns FALSE.
456
457       See also setOption().
458
459

SEE ALSO

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

AUTHOR

470       Generated automatically from the source code.
471

BUGS

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
477       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
483       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).
486
487
488
489Trolltech AS                    2 February 2007                 QGLFormat(3qt)
Impressum