1QGLWidget(3qt) QGLWidget(3qt)
2
6 QGLWidget - Widget for rendering OpenGL graphics
7
9 #include <qgl.h>
10 Inherits QWidget and QGL.
12 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 Public Slots
44 virtual void updateGL ()
45 virtual void updateOverlayGL ()
46 Static Public Members
48 QImage convertToGLFormat ( const QImage & img )
49 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
65 The QGLWidget class is a widget for rendering OpenGL graphics.
66 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 QGLWidget provides three convenient virtual functions that you can
74 reimplement in your subclass to perform the typical OpenGL tasks:
75 paintGL() - Renders the OpenGL scene. Gets called whenever the widget
77 needs to be updated.
78 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 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 Here is a rough outline of how a QGLWidget subclass might look:
89 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 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 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 QGLWidget provides functions for requesting a new display format and
139 you can also create widgets with customized rendering contexts.
140 You can also share OpenGL display lists between QGLWidgets (see the
142 documentation of the QGLWidget constructors for details).
143
145 The QGLWidget creates a GL overlay context in addition to the normal
146 context if overlays are supported by the underlying system.
147 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 paintOverlayGL()
154 resizeOverlayGL()
156 initializeOverlayGL()
158 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 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 <sup>*</sup> OpenGL is a trademark of Silicon Graphics, Inc. in the
171 United States and other countries.
172 See also Graphics Classes and Image Processing Classes.
174
177 QGLWidget * shareWidget = 0, WFlags f = 0 )
178 Constructs an OpenGL widget with a parent widget and a name.
179 The default format is used. The widget will be invalid if the system
181 has no OpenGL support.
182 The parent, name and widget flag, f, arguments are passed to the
184 QWidget constructor.
185 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 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 See also QGLFormat::defaultFormat().
197
199 name = 0, const QGLWidget * shareWidget = 0, WFlags f = 0 )
200 Constructs an OpenGL widget with parent parent, called name.
201 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 The widget will be invalid if the system has no OpenGL support.
207 The parent, name and widget flag, f, arguments are passed to the
209 QWidget constructor.
210 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 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 See also QGLFormat::defaultFormat() and isValid().
222
224 char * name = 0, const QGLWidget * shareWidget = 0, WFlags f = 0 )
225 Constructs an OpenGL widget with parent parent, called name.
226 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 The widget will be invalid if the system has no OpenGL support.
233 The parent, name and widget flag, f, arguments are passed to the
235 QWidget constructor.
236 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 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 See also QGLFormat::defaultFormat() and isValid().
248
250 Destroys the widget.
251
253 Returns TRUE if the widget is doing automatic GL buffer swapping;
254 otherwise returns FALSE.
255 See also setAutoBufferSwap().
257
259 Returns the colormap for this widget.
260 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 If no colormap has been set for this widget, the QColormap returned
266 will be empty.
267 See also setColormap().
269
271 Returns the context of this widget.
272 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
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 QImage tex1, tex2, buf;
285 if ( !buf.load( "gllogo.bmp" ) ) { // Load first image from file
286 We create tex1 (and another variable) for OpenGL, and load a real image
288 into buf.
289 tex1 = QGLWidget::convertToGLFormat( buf ); // flipped 32bit RGBA
291 A few lines later, we convert buf into OpenGL format and store it in
293 tex1.
294 glTexImage2D( GL_TEXTURE_2D, 0, 3, tex1.width(), tex1.height(), 0,
296 GL_RGBA, GL_UNSIGNED_BYTE, tex1.bits() );
297 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 Another function in the same example uses tex1 with OpenGL.
304 Example: opengl/texture/gltexobj.cpp.
306
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
313 Returns TRUE if the contained GL rendering context has double
314 buffering; otherwise returns FALSE.
315 See also QGLFormat::doubleBuffer().
317
319 Returns the format of the contained GL rendering context.
320
322 Executes the virtual function paintGL().
323 The widget's rendering context will become the current context and
325 initializeGL() will be called if it hasn't already been called.
326
328 Initializes OpenGL for this widget's context. Calls the virtual
329 function initializeGL().
330
332 Returns an image of the frame buffer. If withAlpha is TRUE the alpha
333 channel is included.
334 Depending on your hardware, you can explicitly select which color
336 buffer to grab with a glReadBuffer() call before calling this function.
337
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 This function should set up any required OpenGL context rendering
344 flags, defining display lists, etc.
345 There is no need to call makeCurrent() because this has already been
347 done when this function is called.
348
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 This function should set up any required OpenGL context rendering
357 flags, defining display lists, etc. for the overlay context.
358 There is no need to call makeOverlayCurrent() because this has already
360 been done when this function is called.
361
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 See also format().
369
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
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
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 Does nothing if this widget has no overlay.
385 See also makeCurrent().
387
389 Returns the overlay context of this widget, or 0 if this widget has no
390 overlay.
391 See also context().
393
395 Handles paint events. Will cause the virtual paintGL() function to be
396 called.
397 The widget's rendering context will become the current context and
399 initializeGL() will be called if it hasn't already been called.
400 Reimplemented from QWidget.
402
404 This virtual function is called whenever the widget needs to be
405 painted. Reimplement it in a subclass.
406 There is no need to call makeCurrent() because this has already been
408 done when this function is called.
409
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 There is no need to call makeOverlayCurrent() because this has already
418 been done when this function is called.
419
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 See also qglColor(), QGLContext::currentContext(), and QColor.
426
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 See also qglClearColor(), QGLContext::currentContext(), and QColor.
433
435 FALSE ) [virtual]
436 Renders the current scene on a pixmap and returns the pixmap.
437 You can use this method on both visible and invisible QGLWidgets.
439 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 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 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 Overlays are not rendered onto the pixmap.
454 If the GL rendering context and the desktop have different bit depths,
456 the result will most likely look surprising.
457 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
464 fnt = QFont ( ), int listBase = 2000 )
465 Renders the string str into the GL context of this widget.
466 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 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 Note: This function only works reliably with ASCII strings.
486
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 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
498 Handles resize events. Calls the virtual function resizeGL().
499 Reimplemented from QWidget.
501
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 There is no need to call makeCurrent() because this has already been
508 done when this function is called.
509
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 There is no need to call makeOverlayCurrent() because this has already
518 been done when this function is called.
519
521 If on is TRUE automatic GL buffer swapping is switched on; otherwise it
522 is switched off.
523 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 The buffer auto-swapping is on by default.
529 See also autoBufferSwap(), doubleBuffer(), and swapBuffers().
531
533 Set the colormap for this widget to cmap. Usually it is only top-level
534 widgets that can have colormaps installed.
535 See also colormap().
537
539 Swaps the screen contents with an off-screen buffer. This only works if
540 the widget's format specifies double buffer mode.
541 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 See also doubleBuffer(), setAutoBufferSwap(), and
547 QGLFormat::setDoubleBuffer().
548
550 Updates the widget by calling glDraw().
551
553 Updates the widget's overlay (if any). Will cause the virtual function
554 paintOverlayGL() to be executed.
555 The widget's rendering context will become the current context and
557 initializeGL() will be called if it hasn't already been called.
558
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
570 Generated automatically from the source code.
571
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 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 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).
586Trolltech AS 2 February 2007 QGLWidget(3qt)