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.

       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:
                 ...

                 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

       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 DOCUMENTATION


QGLWidget::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

       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.

       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().

       Handles paint events. Will cause the virtual paintGL()
       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

       same size as the widget.

       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().

       Reimplemented for internal reasons; the API is not
       affected.

       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).


Man(1) output converted with man2html