1QGLWidget(3qt)                                                  QGLWidget(3qt)
2
3
4

NAME

6       QGLWidget - Widget for rendering OpenGL graphics
7

SYNOPSIS

9       #include <qgl.h>
10
11       Inherits QWidget and QGL.
12
13   Public Members
14       QGLWidget ( QWidget * parent = 0, const char * name = 0, const
15           QGLWidget * shareWidget = 0, WFlags f = 0 )
16       QGLWidget ( QGLContext * context, QWidget * parent, const char * name =
17           0, const QGLWidget * shareWidget = 0, WFlags f = 0 )
18       QGLWidget ( const QGLFormat & format, QWidget * parent = 0, const char
19           * name = 0, const QGLWidget * shareWidget = 0, WFlags f = 0 )
20       ~QGLWidget ()
21       void qglColor ( const QColor & c ) const
22       void qglClearColor ( const QColor & c ) const
23       bool isValid () const
24       bool isSharing () const
25       virtual void makeCurrent ()
26       void doneCurrent ()
27       bool doubleBuffer () const
28       virtual void swapBuffers ()
29       QGLFormat format () const
30       const QGLContext * context () const
31       virtual QPixmap renderPixmap ( int w = 0, int h = 0, bool useContext =
32           FALSE )
33       virtual QImage grabFrameBuffer ( bool withAlpha = FALSE )
34       virtual void makeOverlayCurrent ()
35       const QGLContext * overlayContext () const
36       const QGLColormap & colormap () const
37       void setColormap ( const QGLColormap & cmap )
38       void renderText ( int x, int y, const QString & str, const QFont & fnt
39           = QFont ( ), int listBase = 2000 )
40       void renderText ( double x, double y, double z, const QString & str,
41           const QFont & fnt = QFont ( ), int listBase = 2000 )
42
43   Public Slots
44       virtual void updateGL ()
45       virtual void updateOverlayGL ()
46
47   Static Public Members
48       QImage convertToGLFormat ( const QImage & img )
49
50   Protected Members
51       virtual void initializeGL ()
52       virtual void resizeGL ( int width, int height )
53       virtual void paintGL ()
54       virtual void initializeOverlayGL ()
55       virtual void resizeOverlayGL ( int width, int height )
56       virtual void paintOverlayGL ()
57       void setAutoBufferSwap ( bool on )
58       bool autoBufferSwap () const
59       virtual void paintEvent ( QPaintEvent * )
60       virtual void resizeEvent ( QResizeEvent * )
61       virtual void glInit ()
62       virtual void glDraw ()
63

DESCRIPTION

65       The QGLWidget class is a widget for rendering OpenGL graphics.
66
67       QGLWidget provides functionality for displaying OpenGL<sup>*</sup>
68       graphics integrated into a Qt application. It is very simple to use.
69       You inherit from it and use the subclass like any other QWidget, except
70       that instead of drawing the widget's contents using QPainter etc. you
71       use the standard OpenGL rendering commands.
72
73       QGLWidget provides three convenient virtual functions that you can
74       reimplement in your subclass to perform the typical OpenGL tasks:
75
76       paintGL() - Renders the OpenGL scene. Gets called whenever the widget
77       needs to be updated.
78
79       resizeGL() - Sets up the OpenGL viewport, projection, etc. Gets called
80       whenever the the widget has been resized (and also when it is shown for
81       the first time because all newly created widgets get a resize event
82       automatically).
83
84       initializeGL() - Sets up the OpenGL rendering context, defines display
85       lists, etc. Gets called once before the first time resizeGL() or
86       paintGL() is called.
87
88       Here is a rough outline of how a QGLWidget subclass might look:
89
90           class MyGLDrawer : public QGLWidget
91           {
92               Q_OBJECT        // must include this if you use Qt signals/slots
93           public:
94               MyGLDrawer( QWidget *parent, const char *name )
95                   : QGLWidget(parent, name) {}
96           protected:
97               void initializeGL()
98               {
99                   // Set up the rendering context, define display lists etc.:
100                   ...
101                   glClearColor( 0.0, 0.0, 0.0, 0.0 );
102                   glEnable(GL_DEPTH_TEST);
103                   ...
104               }
105               void resizeGL( int w, int h )
106               {
107                   // setup viewport, projection etc.:
108                   glViewport( 0, 0, (GLint)w, (GLint)h );
109                   ...
110                   glFrustum( ... );
111                   ...
112               }
113               void paintGL()
114               {
115                   // draw the scene:
116                   ...
117                   glRotatef( ... );
118                   glMaterialfv( ... );
119                   glBegin( GL_QUADS );
120                   glVertex3f( ... );
121                   glVertex3f( ... );
122                   ...
123                   glEnd();
124                   ...
125               }
126           };
127
128       If you need to trigger a repaint from places other than paintGL() (a
129       typical example is when using timers to animate scenes), you should
130       call the widget's updateGL() function.
131
132       Your widget's OpenGL rendering context is made current when paintGL(),
133       resizeGL(), or initializeGL() is called. If you need to call the
134       standard OpenGL API functions from other places (e.g. in your widget's
135       constructor or in your own paint functions), you must call
136       makeCurrent() first.
137
138       QGLWidget provides functions for requesting a new display format and
139       you can also create widgets with customized rendering contexts.
140
141       You can also share OpenGL display lists between QGLWidgets (see the
142       documentation of the QGLWidget constructors for details).
143

Overlays

145       The QGLWidget creates a GL overlay context in addition to the normal
146       context if overlays are supported by the underlying system.
147
148       If you want to use overlays, you specify it in the format. (Note:
149       Overlay must be requested in the format passed to the QGLWidget
150       constructor.) Your GL widget should also implement some or all of these
151       virtual methods:
152
153       paintOverlayGL()
154
155       resizeOverlayGL()
156
157       initializeOverlayGL()
158
159       These methods work in the same way as the normal paintGL() etc.
160       functions, except that they will be called when the overlay context is
161       made current. You can explicitly make the overlay context current by
162       using makeOverlayCurrent(), and you can access the overlay context
163       directly (e.g. to ask for its transparent color) by calling
164       overlayContext().
165
166       On X servers in which the default visual is in an overlay plane, non-GL
167       Qt windows can also be used for overlays. See the
168       examples/opengl/overlay_x11 example program for details.
169
170       <sup>*</sup> OpenGL is a trademark of Silicon Graphics, Inc. in the
171       United States and other countries.
172
173       See also Graphics Classes and Image Processing Classes.
174

MEMBER FUNCTION DOCUMENTATION

QGLWidget::QGLWidget ( QWidget * parent = 0, const char * name = 0, const

177       QGLWidget * shareWidget = 0, WFlags f = 0 )
178       Constructs an OpenGL widget with a parent widget and a name.
179
180       The default format is used. The widget will be invalid if the system
181       has no OpenGL support.
182
183       The parent, name and widget flag, f, arguments are passed to the
184       QWidget constructor.
185
186       If the shareWidget parameter points to a valid QGLWidget, this widget
187       will share OpenGL display lists with shareWidget. If this widget and
188       shareWidget have different formats, display list sharing may fail. You
189       can check whether display list sharing succeeded by calling
190       isSharing().
191
192       The initialization of OpenGL rendering state, etc. should be done by
193       overriding the initializeGL() function, rather than in the constructor
194       of your QGLWidget subclass.
195
196       See also QGLFormat::defaultFormat().
197

QGLWidget::QGLWidget ( QGLContext * context, QWidget * parent, const char *

199       name = 0, const QGLWidget * shareWidget = 0, WFlags f = 0 )
200       Constructs an OpenGL widget with parent parent, called name.
201
202       The context argument is a pointer to the QGLContext that you wish to be
203       bound to this widget. This allows you to pass in your own QGLContext
204       sub-classes.
205
206       The widget will be invalid if the system has no OpenGL support.
207
208       The parent, name and widget flag, f, arguments are passed to the
209       QWidget constructor.
210
211       If the shareWidget parameter points to a valid QGLWidget, this widget
212       will share OpenGL display lists with shareWidget. If this widget and
213       shareWidget have different formats, display list sharing may fail. You
214       can check whether display list sharing succeeded by calling
215       isSharing().
216
217       The initialization of OpenGL rendering state, etc. should be done by
218       overriding the initializeGL() function, rather than in the constructor
219       of your QGLWidget subclass.
220
221       See also QGLFormat::defaultFormat() and isValid().
222

QGLWidget::QGLWidget ( const QGLFormat & format, QWidget * parent = 0, const

224       char * name = 0, const QGLWidget * shareWidget = 0, WFlags f = 0 )
225       Constructs an OpenGL widget with parent parent, called name.
226
227       The format argument specifies the desired rendering options. If the
228       underlying OpenGL/Window system cannot satisfy all the features
229       requested in format, the nearest subset of features will be used. After
230       creation, the format() method will return the actual format obtained.
231
232       The widget will be invalid if the system has no OpenGL support.
233
234       The parent, name and widget flag, f, arguments are passed to the
235       QWidget constructor.
236
237       If the shareWidget parameter points to a valid QGLWidget, this widget
238       will share OpenGL display lists with shareWidget. If this widget and
239       shareWidget have different formats, display list sharing may fail. You
240       can check whether display list sharing succeeded by calling
241       isSharing().
242
243       The initialization of OpenGL rendering state, etc. should be done by
244       overriding the initializeGL() function, rather than in the constructor
245       of your QGLWidget subclass.
246
247       See also QGLFormat::defaultFormat() and isValid().
248

QGLWidget::~QGLWidget ()

250       Destroys the widget.
251

bool QGLWidget::autoBufferSwap () const [protected]

253       Returns TRUE if the widget is doing automatic GL buffer swapping;
254       otherwise returns FALSE.
255
256       See also setAutoBufferSwap().
257

const QGLColormap & QGLWidget::colormap () const

259       Returns the colormap for this widget.
260
261       Usually it is only top-level widgets that can have different colormaps
262       installed. Asking for the colormap of a child widget will return the
263       colormap for the child's top-level widget.
264
265       If no colormap has been set for this widget, the QColormap returned
266       will be empty.
267
268       See also setColormap().
269

const QGLContext * QGLWidget::context () const

271       Returns the context of this widget.
272
273       It is possible that the context is not valid (see isValid()), for
274       example, if the underlying hardware does not support the format
275       attributes that were requested.
276

QImage QGLWidget::convertToGLFormat ( const QImage & img ) [static]

278       Converts the image img into the unnamed format expected by OpenGL
279       functions such as glTexImage2D(). The returned image is not usable as a
280       QImage, but QImage::width(), QImage::height() and QImage::bits() may be
281       used with OpenGL. The following few lines are from the texture example.
282       Most of the code is irrelevant, so we just quote the relevant bits:
283
284               QImage tex1, tex2, buf;
285               if ( !buf.load( "gllogo.bmp" ) ) {  // Load first image from file
286
287       We create tex1 (and another variable) for OpenGL, and load a real image
288       into buf.
289
290               tex1 = QGLWidget::convertToGLFormat( buf );  // flipped 32bit RGBA
291
292       A few lines later, we convert buf into OpenGL format and store it in
293       tex1.
294
295               glTexImage2D( GL_TEXTURE_2D, 0, 3, tex1.width(), tex1.height(), 0,
296                             GL_RGBA, GL_UNSIGNED_BYTE, tex1.bits() );
297
298       Note the dimension restrictions for texture images as described in the
299       glTexImage2D() documentation. The width must be 2^m + 2*border and the
300       height 2^n + 2*border where m and n are integers and border is either 0
301       or 1.
302
303       Another function in the same example uses tex1 with OpenGL.
304
305       Example: opengl/texture/gltexobj.cpp.
306

void QGLWidget::doneCurrent ()

308       Makes no GL context the current context. Normally, you do not need to
309       call this function; QGLContext calls it as necessary. However, it may
310       be useful in multithreaded environments.
311

bool QGLWidget::doubleBuffer () const

313       Returns TRUE if the contained GL rendering context has double
314       buffering; otherwise returns FALSE.
315
316       See also QGLFormat::doubleBuffer().
317

QGLFormat QGLWidget::format () const

319       Returns the format of the contained GL rendering context.
320

void QGLWidget::glDraw () [virtual protected]

322       Executes the virtual function paintGL().
323
324       The widget's rendering context will become the current context and
325       initializeGL() will be called if it hasn't already been called.
326

void QGLWidget::glInit () [virtual protected]

328       Initializes OpenGL for this widget's context. Calls the virtual
329       function initializeGL().
330

QImage QGLWidget::grabFrameBuffer ( bool withAlpha = FALSE ) [virtual]

332       Returns an image of the frame buffer. If withAlpha is TRUE the alpha
333       channel is included.
334
335       Depending on your hardware, you can explicitly select which color
336       buffer to grab with a glReadBuffer() call before calling this function.
337

void QGLWidget::initializeGL () [virtual protected]

339       This virtual function is called once before the first call to paintGL()
340       or resizeGL(), and then once whenever the widget has been assigned a
341       new QGLContext. Reimplement it in a subclass.
342
343       This function should set up any required OpenGL context rendering
344       flags, defining display lists, etc.
345
346       There is no need to call makeCurrent() because this has already been
347       done when this function is called.
348

void QGLWidget::initializeOverlayGL () [virtual protected]

350       This virtual function is used in the same manner as initializeGL()
351       except that it operates on the widget's overlay context instead of the
352       widget's main context. This means that initializeOverlayGL() is called
353       once before the first call to paintOverlayGL() or resizeOverlayGL().
354       Reimplement it in a subclass.
355
356       This function should set up any required OpenGL context rendering
357       flags, defining display lists, etc. for the overlay context.
358
359       There is no need to call makeOverlayCurrent() because this has already
360       been done when this function is called.
361

bool QGLWidget::isSharing () const

363       Returns TRUE if display list sharing with another QGLWidget was
364       requested in the constructor, and the GL system was able to provide it;
365       otherwise returns FALSE. The GL system may fail to provide display list
366       sharing if the two QGLWidgets use different formats.
367
368       See also format().
369

bool QGLWidget::isValid () const

371       Returns TRUE if the widget has a valid GL rendering context; otherwise
372       returns FALSE. A widget will be invalid if the system has no OpenGL
373       support.
374

void QGLWidget::makeCurrent () [virtual]

376       Makes this widget the current widget for OpenGL operations, i.e. makes
377       the widget's rendering context the current OpenGL rendering context.
378

void QGLWidget::makeOverlayCurrent () [virtual]

380       Makes the overlay context of this widget current. Use this if you need
381       to issue OpenGL commands to the overlay context outside of
382       initializeOverlayGL(), resizeOverlayGL(), and paintOverlayGL().
383
384       Does nothing if this widget has no overlay.
385
386       See also makeCurrent().
387

const QGLContext * QGLWidget::overlayContext () const

389       Returns the overlay context of this widget, or 0 if this widget has no
390       overlay.
391
392       See also context().
393

void QGLWidget::paintEvent ( QPaintEvent * ) [virtual protected]

395       Handles paint events. Will cause the virtual paintGL() function to be
396       called.
397
398       The widget's rendering context will become the current context and
399       initializeGL() will be called if it hasn't already been called.
400
401       Reimplemented from QWidget.
402

void QGLWidget::paintGL () [virtual protected]

404       This virtual function is called whenever the widget needs to be
405       painted. Reimplement it in a subclass.
406
407       There is no need to call makeCurrent() because this has already been
408       done when this function is called.
409

void QGLWidget::paintOverlayGL () [virtual protected]

411       This virtual function is used in the same manner as paintGL() except
412       that it operates on the widget's overlay context instead of the
413       widget's main context. This means that paintOverlayGL() is called
414       whenever the widget's overlay needs to be painted. Reimplement it in a
415       subclass.
416
417       There is no need to call makeOverlayCurrent() because this has already
418       been done when this function is called.
419

void QGLWidget::qglClearColor ( const QColor & c ) const

421       Convenience function for specifying the clearing color to OpenGL. Calls
422       glClearColor (in RGBA mode) or glClearIndex (in color-index mode) with
423       the color c. Applies to the current GL context.
424
425       See also qglColor(), QGLContext::currentContext(), and QColor.
426

void QGLWidget::qglColor ( const QColor & c ) const

428       Convenience function for specifying a drawing color to OpenGL. Calls
429       glColor3 (in RGBA mode) or glIndex (in color-index mode) with the color
430       c. Applies to the current GL context.
431
432       See also qglClearColor(), QGLContext::currentContext(), and QColor.
433

QPixmap QGLWidget::renderPixmap ( int w = 0, int h = 0, bool useContext =

435       FALSE ) [virtual]
436       Renders the current scene on a pixmap and returns the pixmap.
437
438       You can use this method on both visible and invisible QGLWidgets.
439
440       This method will create a pixmap and a temporary QGLContext to render
441       on the pixmap. It will then call initializeGL(), resizeGL(), and
442       paintGL() on this context. Finally, the widget's original GL context is
443       restored.
444
445       The size of the pixmap will be w pixels wide and h pixels high unless
446       one of these parameters is 0 (the default), in which case the pixmap
447       will have the same size as the widget.
448
449       If useContext is TRUE, this method will try to be more efficient by
450       using the existing GL context to render the pixmap. The default is
451       FALSE. Only use TRUE if you understand the risks.
452
453       Overlays are not rendered onto the pixmap.
454
455       If the GL rendering context and the desktop have different bit depths,
456       the result will most likely look surprising.
457
458       Note that the creation of display lists, modifications of the view
459       frustum etc. should be done from within initializeGL(). If this is not
460       done, the temporary QGLContext will not be initialized properly, and
461       the rendered pixmap may be incomplete/corrupted.
462

void QGLWidget::renderText ( int x, int y, const QString & str, const QFont &

464       fnt = QFont ( ), int listBase = 2000 )
465       Renders the string str into the GL context of this widget.
466
467       x and y are specified in window coordinates, with the origin in the
468       upper left-hand corner of the window. If fnt is not specified, the
469       currently set application font will be used to render the string. To
470       change the color of the rendered text you can use the glColor() call
471       (or the qglColor() convenience function), just before the renderText()
472       call. Note that if you have GL_LIGHTING enabled, the string will not
473       appear in the color you want. You should therefore switch lighting off
474       before using renderText().
475
476       listBase specifies the index of the first display list that is
477       generated by this function. The default value is 2000. 256 display
478       lists will be generated, one for each of the first 256 characters in
479       the font that is used to render the string. If several fonts are used
480       in the same widget, the display lists for these fonts will follow the
481       last generated list. You would normally not have to change this value
482       unless you are using lists in the same range. The lists are deleted
483       when the widget is destroyed.
484
485       Note: This function only works reliably with ASCII strings.
486

void QGLWidget::renderText ( double x, double y, double z, const QString &

488       str, const QFont & fnt = QFont ( ), int listBase = 2000 )
489       This is an overloaded member function, provided for convenience. It
490       behaves essentially like the above function.
491
492       x, y and z are specified in scene or object coordinates relative to the
493       currently set projection and model matrices. This can be useful if you
494       want to annotate models with text labels and have the labels move with
495       the model as it is rotated etc.
496

void QGLWidget::resizeEvent ( QResizeEvent * ) [virtual protected]

498       Handles resize events. Calls the virtual function resizeGL().
499
500       Reimplemented from QWidget.
501

void QGLWidget::resizeGL ( int width, int height ) [virtual protected]

503       This virtual function is called whenever the widget has been resized.
504       The new size is passed in width and height. Reimplement it in a
505       subclass.
506
507       There is no need to call makeCurrent() because this has already been
508       done when this function is called.
509

void QGLWidget::resizeOverlayGL ( int width, int height ) [virtual protected]

511       This virtual function is used in the same manner as paintGL() except
512       that it operates on the widget's overlay context instead of the
513       widget's main context. This means that resizeOverlayGL() is called
514       whenever the widget has been resized. The new size is passed in width
515       and height. Reimplement it in a subclass.
516
517       There is no need to call makeOverlayCurrent() because this has already
518       been done when this function is called.
519

void QGLWidget::setAutoBufferSwap ( bool on ) [protected]

521       If on is TRUE automatic GL buffer swapping is switched on; otherwise it
522       is switched off.
523
524       If on is TRUE and the widget is using a double-buffered format, the
525       background and foreground GL buffers will automatically be swapped
526       after each paintGL() call.
527
528       The buffer auto-swapping is on by default.
529
530       See also autoBufferSwap(), doubleBuffer(), and swapBuffers().
531

void QGLWidget::setColormap ( const QGLColormap & cmap )

533       Set the colormap for this widget to cmap. Usually it is only top-level
534       widgets that can have colormaps installed.
535
536       See also colormap().
537

void QGLWidget::swapBuffers () [virtual]

539       Swaps the screen contents with an off-screen buffer. This only works if
540       the widget's format specifies double buffer mode.
541
542       Normally, there is no need to explicitly call this function because it
543       is done automatically after each widget repaint, i.e. each time after
544       paintGL() has been executed.
545
546       See also doubleBuffer(), setAutoBufferSwap(), and
547       QGLFormat::setDoubleBuffer().
548

void QGLWidget::updateGL () [virtual slot]

550       Updates the widget by calling glDraw().
551

void QGLWidget::updateOverlayGL () [virtual slot]

553       Updates the widget's overlay (if any). Will cause the virtual function
554       paintOverlayGL() to be executed.
555
556       The widget's rendering context will become the current context and
557       initializeGL() will be called if it hasn't already been called.
558
559

SEE ALSO

561       http://doc.trolltech.com/qglwidget.html
562       http://www.trolltech.com/faq/tech.html
563
565       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
566       license file included in the distribution for a complete license
567       statement.
568

AUTHOR

570       Generated automatically from the source code.
571

BUGS

573       If you find a bug in Qt, please report it as described in
574       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
575       help you. Thank you.
576
577       The definitive Qt documentation is provided in HTML format; it is
578       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
579       web browser. This man page is provided as a convenience for those users
580       who prefer man pages, although this format is not officially supported
581       by Trolltech.
582
583       If you find errors in this manual page, please report them to qt-
584       bugs@trolltech.com.  Please include the name of the manual page
585       (qglwidget.3qt) and the Qt version (3.3.8).
586
587
588
589Trolltech AS                    2 February 2007                 QGLWidget(3qt)
Impressum