QGLWidget(3qt)QGLWidget(3qt)NAME
QGLWidget - Widget for rendering OpenGL graphics
#include <qgl.h>
Inherits QGL and QWidget.
Public Members
QGLWidget ( QWidget * parent=0, const char * name=0, const
QGLWidget * shareWidget = 0, WFlags f=0 )
QGLWidget ( const QGLFormat & format, QWidget * parent=0,
const char * name=0, const QGLWidget * shareWidget =
0, WFlags f=0 )
~QGLWidget ()
void qglColor ( const QColor & c ) const
void qglClearColor ( const QColor & c ) const
bool isValid () const
bool isSharing () const
virtual void makeCurrent ()
bool doubleBuffer () const
virtual void swapBuffers ()
QGLFormat format () const
const QGLContext* context () const
virtual QPixmap renderPixmap ( int w = 0, int h = 0, bool
useContext = FALSE )
virtual void makeOverlayCurrent ()
const QGLContext* overlayContext () const
Public Slots
virtual void updateGL ()
virtual void updateOverlayGL ()
Static Public Members
QImage convertToGLFormat ( const QImage & img )
Protected Members
virtual void initializeGL ()
virtual void resizeGL ( int w, int h )
virtual void paintGL ()
virtual void initializeOverlayGL ()
virtual void resizeOverlayGL ( int w, int h )
virtual void paintOverlayGL ()
void setAutoBufferSwap ( bool on )
bool autoBufferSwap () const
virtual void paintEvent ( QPaintEvent * )
virtual void resizeEvent ( QResizeEvent * )
virtual void glInit ()
virtual void glDraw ()
DESCRIPTION
The QGLWidget class is a widget for rendering OpenGL
graphics.
Trolltech AS 13 June 2001 1
QGLWidget(3qt)QGLWidget(3qt)
QGLWidget provides functionality for displaying OpenGL
graphics integrated in a Qt application. It is very simple
to use: you inherit from it and use the subclass like any
other QWidget, only that instead of drawing the widget's
contents using QPainter & al., you use the standard OpenGL
rendering commands.
QGLWidget provides three convenient virtual functions that
you can reimplement in your subclass to perform the
typical OpenGL tasks:
paintGL() - Render the OpenGL scene. Gets called whenever
the widget needs to be updated.
resizeGL() - Set up OpenGL viewport, projection etc. Gets
called whenever the the widget has been resized (and also
when it shown for the first time, since all newly created
widgets get a resize event automatically).
initializeGL() - Set up the OpenGL rendering context,
define display lists etc. Gets called once before the
first time resizeGL() or paintGL() is called.
Here is a rough outline of how your QGLWidget subclass may
look:
class MyGLDrawer : public QGLWidget
{
Q_OBJECT // must include this if you use Qt signals/slots
public:
MyGLDrawer( QWidget *parent, const char *name )
: QGLWidget(parent,name) {}
protected:
void initializeGL()
{
// Set up the rendering context, define display lists etc.:
...
glClearColor( 0.0, 0.0, 0.0, 0.0 );
glEnable(GL_DEPTH_TEST);
...
}
void resizeGL( int w, int h )
{
// setup viewport, projection etc.:
glViewport( 0, 0, (GLint)w, (GLint)h );
...
glFrustum( ... );
...
}
void paintGL()
{
// draw the scene:
...
glRotatef( ... );
Trolltech AS 13 June 2001 2
QGLWidget(3qt)QGLWidget(3qt)
glMaterialfv( ... );
glBegin( GL_QUADS );
glVertex3f( ... );
glVertex3f( ... );
...
glEnd();
...
}
};
If you need to trigger a repaint from other places than
paintGL() (a typical example is when using timers to
animate scenes), you should call the widget's updateGL()
function.
When paintGL(), resizeGL() or initializeGL() is called,
your widget's OpenGL rendering context has been made
current. If you need to call the standard OpenGL API
functions from other places (e.g. in your widget's
constructor), you must call makeCurrent() first.
QGLWidget provides advanced functions for requesting a new
display format, and you can even set a new rendering
context.
You can achieve sharing of OpenGL display lists between
QGLWidgets, see the documentation of the QGLWidget
constructors for details.
About Overlays: The QGLWidget can create a GL overlay
context in addition to the normal context, if overlays are
supported by the underlying system.
If you want to use overlays, you specify it in the format.
(Note: Overlay must be requested in the format passed to
the QGLWidget constructor). Your GL widget should also
implement some or all of these virtual methods:
paintOverlayGL()resizeOverlayGL()initializeOverlayGL()
These methods work in the same way as the normal paintGL()
& al. functions, only that they will be called when with
the overlay context made current. You can explicitly make
the overlay context current by using makeOverlayCurrent(),
and you can access the overlay context directly (e.g. to
ask for its transparent color) by calling
overlayContext().
Note: QGLWidget overlay support is currently implemented
only for the X11 window system. The Windows implementation
Trolltech AS 13 June 2001 3
QGLWidget(3qt)QGLWidget(3qt)
is experimental.
Note: On X servers where the default visual is in an
overlay plane, non-GL Qt windows can also be used for
overlays; see the "overlay_x11" example program for
details.
MEMBER FUNCTION DOCUMENTATIONQGLWidget::QGLWidget ( QWidget * parent=0, const char * name=0,
const QGLWidget * shareWidget = 0, WFlags f=0 )
Constructs an OpenGL widget with a parent widget and a
name.
The default format is used. The widget will be invalid if
the system has no OpenGL support.
The parent, name and f arguments are passed to the QWidget
constructor.
If the shareWidget parameter points to a valid QGLWidget,
this widget will share OpenGL display lists with
shareWidget. Note: If this widget and shareWidget has
different formats, display list sharing may fail. You can
check whether display list sharing succeeded by using the
isSharing() method.
Note: Initialization of OpenGL rendering state etc. should
be done by overriding the initializeGL() function, not in
the constructor of your QGLWidget subclass.
See also QGLFormat::defaultFormat().
QGLWidget::QGLWidget ( const QGLFormat & format, QWidget *
parent=0, const char * name=0, const QGLWidget *
shareWidget = 0, WFlags f=0 )
Constructs an OpenGL widget with a parent widget and a
name.
The format argument specifies the desired rendering
options. If the underlying OpenGL/Window system cannot
satisfy all the features requested in format, the nearest
subset of features will be used. After creation, the
format() method will return the actual format obtained.
The widget will be invalid if the system has no OpenGL
support.
The parent, name and f arguments are passed to the QWidget
constructor.
If the shareWidget parameter points to a valid QGLWidget,
this widget will share OpenGL display lists with
shareWidget. Note: If this widget and shareWidget has
different formats, display list sharing may fail. You can
Trolltech AS 13 June 2001 4
QGLWidget(3qt)QGLWidget(3qt)
check whether display list sharing succeeded by using the
isSharing() method.
Note: Initialization of OpenGL rendering state etc. should
be done by overriding the initializeGL() function, not in
the constructor of your QGLWidget subclass.
See also QGLFormat::defaultFormat() and isValid().
QGLWidget::~QGLWidget ()
Destroys the widget.
bool QGLWidget::autoBufferSwap () const [protected]
Returns TRUE if the widget is doing automatic GL buffer
swapping.
See also setAutoBufferSwap().
const QGLContext * QGLWidget::context () const
Returns the context of this widget.
QImage QGLWidget::convertToGLFormat ( const QImage & img )
[static]
Convenience function for converting a QImage into the
format expected by OpenGL's texture functions.
bool QGLWidget::doubleBuffer () const
Returns TRUE if the contained GL rendering context has
double buffering.
See also QGLFormat::doubleBuffer().
QGLFormat QGLWidget::format () const
Returns the format of the contained GL rendering context.
void QGLWidget::glDraw () [virtual protected]
Executes the virtual function paintGL(), initializing
first as necessary.
void QGLWidget::glInit () [virtual protected]
Initializes OpenGL for this widget's context. Calls the
virtual function initializeGL().
void QGLWidget::initializeGL () [virtual protected]
This virtual function is called one time before the first
call to paintGL() or resizeGL(), and then one time
whenever the widget has been assigned a new QGLContext.
Reimplement it in a subclass.
This function should take care of setting any required
OpenGL context rendering flags, defining display lists,
etc.
There is no need to call makeCurrent() because this has
Trolltech AS 13 June 2001 5
QGLWidget(3qt)QGLWidget(3qt)
already been done when this function is called.
void QGLWidget::initializeOverlayGL () [virtual protected]
This virtual function is used in the same manner as
initializeGL(), only for the widget's overlay context
instead of the widget's main context. That is,
initializeOverlayGL() is called one time before the first
call to paintOverlayGL() or resizeOverlayGL(). Reimplement
it in a subclass.
This function should take care of setting any required
OpenGL context rendering flags, defining display lists,
etc., for the overlay context.
There is no need to call makeOverlayCurrent() because this
has already been done when this function is called.
bool QGLWidget::isSharing () const
Returns TRUE if display list sharing with another
QGLWidget was requested in the constructor, and the GL
system was able to provide it. The GL system may fail to
provide display list sharing if the two QGLWidgets use
different formats.
See also format().
bool QGLWidget::isValid () const
Returns TRUE if the widget has a valid GL rendering
context. A widget will be invalid if the system has no
OpenGL support
void QGLWidget::makeCurrent () [virtual]
Makes this widget the current widget for OpenGL
operations. I.e. makes this widget's rendering context the
current OpenGL rendering context.
void QGLWidget::makeOverlayCurrent () [virtual]
Makes the overlay context of this widget current. Use this
if you need to issue OpenGL commands to the overlay
context outside of initializeOverlayGL(),
resizeOverlayGL() and paintOverlayGL().
Does nothing if this widget has no overlay.
See also makeCurrent().
const QGLContext* QGLWidget::overlayContext () const
Returns the overlay context of this widget, or 0 if this
widget has no overlay.
See also context().
void QGLWidget::paintEvent ( QPaintEvent * ) [virtual protected]
Handles paint events. Will cause the virtual paintGL()Trolltech AS 13 June 2001 6
QGLWidget(3qt)QGLWidget(3qt)
function to be called, initializing first as necessary.
Reimplemented from QWidget.
void QGLWidget::paintGL () [virtual protected]
This virtual function is called whenever the widget needs
to be painted. Reimplement it in a subclass.
There is no need to call makeCurrent() because this has
already been done when this function is called.
void QGLWidget::paintOverlayGL () [virtual protected]
This virtual function is used in the same manner as
paintGL(), only for the widget's overlay context instead
of the widget's main context. That is, paintOverlayGL() is
called whenever the widget's overlay needs to be painted.
Reimplement it in a subclass.
There is no need to call makeOverlayCurrent() because this
has already been done when this function is called.
void QGLWidget::qglClearColor ( const QColor & c ) const
Convenience function for specifying the clearing color to
OpenGL. Calls glClearColor (in RGBA mode) or glClearIndex
(in color-index mode) with the color c. Applies to the
current GL context.
See also qglColor(), QGLContext::currentContext() and
QColor.
void QGLWidget::qglColor ( const QColor & c ) const
Convenience function for specifying a drawing color to
OpenGL. Calls glColor3 (in RGBA mode) or glIndex (in
color-index mode) with the color c. Applies to the current
GL context.
See also qglClearColor(), QGLContext::currentContext() and
QColor.
QPixmap QGLWidget::renderPixmap ( int w = 0, int h = 0, bool
useContext = FALSE ) [virtual]
Renders the current scene on a pixmap and returns it.
You may use this method on both visible and invisible
QGLWidgets.
This method will create a pixmap and a temporary
QGLContext to render on it. Then, initializeGL(),
resizeGL(), and paintGL() are called on this context.
Finally, the widget's original GL context is restored.
The size of the pixmap will be width w and height h. If
any of those are 0 (the default), the pixmap will have the
same size as the widget.
Trolltech AS 13 June 2001 7
QGLWidget(3qt)QGLWidget(3qt)
If useContext is TRUE, this method will try to be more
efficient by using the existing GL context to render the
pixmap. The default is FALSE. Use only if you know what
you are doing.
Any overlay is not rendered to the pixmap.
Bugs and limitations:
May give unexpected results if the depth of the GL
rendering context is different from the depth of the
desktop.
void QGLWidget::resizeEvent ( QResizeEvent * ) [virtual
protected]
Handles resize events. Calls the virtual function
resizeGL().
Reimplemented from QWidget.
void QGLWidget::resizeGL ( int width, int height ) [virtual
protected]
This virtual function is called whenever the widget has
been resized. Reimplement it in a subclass.
There is no need to call makeCurrent() because this has
already been done when this function is called.
void QGLWidget::resizeOverlayGL ( int, int ) [virtual protected]
This virtual function is used in the same manner as
paintGL(), only for the widget's overlay context instead
of the widget's main context. That is, resizeOverlayGL()
is called whenever the widget has been resized.
Reimplement it in a subclass.
There is no need to call makeOverlayCurrent() because this
has already been done when this function is called.
void QGLWidget::setAutoBufferSwap ( bool on ) [protected]
Turns on or off the automatic GL buffer swapping. If on,
and the widget is using a double-buffered format, the
background and foreground GL buffers will automatically be
swapped after each time the paintGL() function has been
called.
The buffer auto-swapping is on by default.
See also autoBufferSwap(), doubleBuffer() and
swapBuffers().
void QGLWidget::setMouseTracking ( bool enable ) [virtual]
Reimplemented for internal reasons; the API is not
affected.
Trolltech AS 13 June 2001 8
QGLWidget(3qt)QGLWidget(3qt)
Reimplemented from QWidget.
void QGLWidget::swapBuffers () [virtual]
Swaps the screen contents with an off-screen buffer. Works
only if the widget's format specifies double buffer mode.
Normally, there is no need to explicitly call this
function, because it is done automatically after each
widget repaint, i.e. after each time paintGL() has been
executed.
See also doubleBuffer(), setAutoBufferSwap() and
QGLFormat::setDoubleBuffer().
void QGLWidget::updateGL () [virtual slot]
Updates the widget by calling glDraw().
void QGLWidget::updateOverlayGL () [virtual slot]
Updates the widget's overlay (if any). Will cause the
virtual function paintOverlayGL() to be executed,
initializing first as necessary.
SEE ALSO
http://doc.trolltech.com/qglwidget.html
http://www.trolltech.com/faq/tech.html
COPYRIGHT
Copyright 1992-2001 Trolltech AS,
http://www.trolltech.com. See the license file included
in the distribution for a complete license statement.
AUTHOR
Generated automatically from the source code.
BUGS
If you find a bug in Qt, please report it as described in
http://doc.trolltech.com/bughowto.html. Good bug reports
make our job much simpler. Thank you.
In case of content or formattting problems with this
manual page, please report them to qt-bugs@trolltech.com.
Please include the name of the manual page (qglwidget.3qt)
and the Qt version (2.3.1).
Trolltech AS 13 June 2001 9
