NAME

       SoQtGLWidget - The SoQtGLWidget class manages OpenGL contexts.

       This is the basic, abstract component class which sets up an OpenGL canvas for its
       subclasses.

SYNOPSIS

       #include <Inventor/Qt/SoQtGLWidget.h>

       Inherits SoQtComponent.

       Inherited by SoQtRenderArea.

   Public Member Functions
       void setBorder (const SbBool enable)
       SbBool isBorder (void) const
       virtual void setDoubleBuffer (const SbBool enable)
       SbBool isDoubleBuffer (void) const
       void setDrawToFrontBufferEnable (const SbBool enable)
       SbBool isDrawToFrontBufferEnable (void) const
       void setQuadBufferStereo (const SbBool enable)
       SbBool isQuadBufferStereo (void) const
       void setAccumulationBuffer (const SbBool enable)
       SbBool getAccumulationBuffer (void) const
       void setStencilBuffer (const SbBool enable)
       SbBool getStencilBuffer (void) const
       void setAlphaChannel (const SbBool enable)
       SbBool getAlphaChannel (void) const
       void setOverlayRender (const SbBool onoff)
       SbBool isOverlayRender (void) const
       void setSampleBuffers (const int numsamples)
       int getSampleBuffers (void) const
       void setStealFocus (SbBool enable)
       SbBool isStealFocus (void) const
       QWidget * getGLWidget (void) const
       QWidget * getNormalWidget (void) const
       QWidget * getOverlayWidget (void) const
       SbBool hasOverlayGLArea (void) const
       SbBool hasNormalGLArea (void) const
       unsigned long getOverlayTransparentPixel (void)
       void getPointSizeLimits (SbVec2f &range, float &granularity)
       void getLineWidthLimits (SbVec2f &range, float &granularity)

   Protected Member Functions
       SoQtGLWidget (QWidget *const parent=NULL, const char *const name=NULL, const SbBool
           embed=TRUE, const int glmodes=SO_GL_RGB, const SbBool build=TRUE)
       ~SoQtGLWidget ()
       virtual void processEvent (QEvent *event)
       QWidget * buildWidget (QWidget *parent)
       virtual void redraw (void)=0
       virtual void redrawOverlay (void)
       virtual void initGraphic (void)
       virtual void initOverlayGraphic (void)
       virtual void sizeChanged (const SbVec2s &size)
       virtual void widgetChanged (QWidget *w)
       void setGLSize (const SbVec2s size)
       SbVec2s getGLSize (void) const
       float getGLAspectRatio (void) const
       void setGlxSize (const SbVec2s size)
       SbVec2s getGlxSize (void) const
       float getGlxAspectRatio (void) const
       void setStereoBuffer (SbBool flag)
       SbBool isStereoBuffer (void) const
       SbBool isRGBMode (void)
       void glLockNormal (void)
       void glUnlockNormal (void)
       void glLockOverlay (void)
       void glUnlockOverlay (void)
       void glSwapBuffers (void)
       void glFlushBuffer (void)
       virtual SbBool glScheduleRedraw (void)

   Protected Attributes
       SbBool waitForExpose
       SbBool drawToFrontBuffer

   Friends
       class SoGuiGLWidgetP
       class SoQtGLWidgetP

   Additional Inherited Members

Detailed Description

       The SoQtGLWidget class manages OpenGL contexts.

       This is the basic, abstract component class which sets up an OpenGL canvas for its
       subclasses.

       Application programmers will normally not use this class directly, but rather through the
       interface of either its direct descendent; SoQtRenderArea, or through one of the 'rapid
       application development'-style viewer subclasses.

       An important thing to know about embedding SoQtGLWidget derived components into other Qt
       widgets is that you need to set up 'focus proxying' to have events still be sent to the
       OpenGL canvas widget. This is true for both the SoQtRenderArea aswell as all the viewer
       components (like SoQtExaminerViewer, SoQtPlaneViewer etc).

       As an example, if you embed an SoQtExaminerViewer inside a QFrame like this:

       QMainWindow * toplevel = new QMainWindow;
       QFrame * frame = new QFrame(toplevel);
       SoQtExaminerViewer * viewer = new SoQtExaminerViewer(toplevel);

       ...events from the keyboard will not always automatically be forwarded to the viewer
       OpenGL canvas. This is the code you need to add in this case:

       toplevel->setFocusProxy(viewer->getWidget());

Constructor & Destructor Documentation

   SoQtGLWidget::SoQtGLWidget (QWidget *const parent = NULL, const char *const name = NULL, const
       SbBool embed = TRUE, const int glmodes = SO_GL_RGB, const SbBool build = TRUE) [protected]
       The constructor is protected, as this is an abstract class to only be used by it's
       subclasses.

       References buildWidget(), SoQtComponent::getParentWidget(),
       SoQtComponent::setBaseWidget(), and SoQtComponent::setClassName().

   SoQtGLWidget::~SoQtGLWidget () [protected]
       Clean up all use of internal resources.

       The destructor is protected, as this is an abstract class to only be used by it's
       subclasses.

       References SoQtComponent::unregisterWidget().

Member Function Documentation

   void SoQtGLWidget::setBorder (const SbBool enable)
       Specify whether or not there should be a border framing the OpenGL canvas. The border will
       be 2 pixels wide.

       The default is to display the OpenGL canvas with no border.

       See also:
           isBorder()

   SbBool SoQtGLWidget::isBorder (void) const
       Returns whether or not there's a border framing the OpenGL canvas.

       See also:
           setBorder()

       Referenced by setGLSize().

   void SoQtGLWidget::setDoubleBuffer (const SbBool enable) [virtual]
       Switch between single and double buffer mode for the OpenGL canvas. The default is to use
       a single buffer canvas.

       See also:
           isDoubleBuffer()

       Reimplemented in SoQtViewer.

   SbBool SoQtGLWidget::isDoubleBuffer (void) const
       Returns the status of the buffer mode.

       See also:
           setDoubleBuffer()

       Referenced by SoQtViewer::actualRedraw(), SoQtRenderArea::redraw(), and
       SoQtViewer::SoQtViewer().

   void SoQtGLWidget::setDrawToFrontBufferEnable (const SbBool enable)
       If this is set to TRUE, rendering will happen in the front buffer even if the current
       rendering mode is double buffered.

       References drawToFrontBuffer.

   SbBool SoQtGLWidget::isDrawToFrontBufferEnable (void) const
       See also:
           setDrawToFrontBufferEnable()

       References drawToFrontBuffer.

       Referenced by SoQtRenderArea::redraw().

   void SoQtGLWidget::setQuadBufferStereo (const SbBool enable)
       Enables or disables OpenGL quad buffer stereo.

       Referenced by setStereoBuffer(), and SoQtViewer::setStereoType().

   SbBool SoQtGLWidget::isQuadBufferStereo (void) const
       Returns TRUE if quad buffer stereo is enabled for this widget.

       Referenced by SoQtViewer::getStereoType(), isStereoBuffer(), and
       SoQtViewer::setStereoType().

   void SoQtGLWidget::setAccumulationBuffer (const SbBool enable)
       Enables/disables the OpenGL accumulation buffer.

       For general information about accumulation buffers, confer with your OpenGL reference
       documentation.

       By default, the accumulation buffer will be attempted disabled. Whether or not it will
       actually be disabled depends on what OpenGL contexts are available on the system. It is
       perfectly possible that the only usable contexts with regard to the other settings (like
       double buffering and RGBA mode versus color index mode) causes the context selection to
       choose an OpenGL format that contains an accumulation buffer, even though it was not
       requested.

       Vice versa, one is not guaranteed to get accumulation buffers even when requested through
       this function, either because they are not available, or because they are only available
       in combination with other OpenGL context settings that are not wanted (like single
       buffers, non-accellerated rendering, etc).

       If you try to enable accumulation buffers by using this function, you should therefore in
       succession use the SoQtGLWidget::getAccumulationBuffer() to query whether or not an
       accumulation buffer could actually be set up.

       See also:
           SoQtRenderArea::setAntiAliasing()

   SbBool SoQtGLWidget::getAccumulationBuffer (void) const
       Returns whether the OpenGL accumulation buffer is enabled.

       The returned flag will indicate whether or not accumulation buffers are actually present,
       and not just parrot the input value to SoQtGLWidget::setAccumulationBuffer(). See
       documentation of that function for more information.

   void SoQtGLWidget::setStencilBuffer (const SbBool enable)
       Enables/disables the OpenGL stencil buffer.

       For general information about stencil buffers, confer with your OpenGL reference
       documentation.

       By default, the stencil buffer will be attempted disabled, but the same notes apply for
       stencil buffers as for accumulation buffers. For an explanation on the issue of stencil
       and accumulation buffer availability, see the function documentation of
       SoQtGLWidget::setAccumulationBuffer().

       Referenced by SoQtViewer::setStereoType().

   SbBool SoQtGLWidget::getStencilBuffer (void) const
       Returns whether the OpenGL stencil buffer is enabled.

       The returned flag will indicate whether or not stencil buffers are actually present, in
       the same manner as for SoQtGLWidget::getAccumulationBuffer(). See documentation of
       SoQtGLWidget::setStencilBuffer().

       Referenced by SoQtViewer::setStereoType().

   void SoQtGLWidget::setAlphaChannel (const SbBool enable)
       Enables/disables the alpha channel for the OpenGL context.

   SbBool SoQtGLWidget::getAlphaChannel (void) const
       Returns whether the alpha channel is enabled for the OpenGL context.

   void SoQtGLWidget::setOverlayRender (const SbBool onoff)
       Turn on or off the use of overlay planes.

       See also:
           isOverlayRender()

       Referenced by SoQtRenderArea::setOverlaySceneGraph().

   SbBool SoQtGLWidget::isOverlayRender (void) const
       Returns a flag indicating whether or not overplay planes are currently used.

       See also:
           setOverlayRender()

   void SoQtGLWidget::setSampleBuffers (const int numsamples)
       Set the number of samples use when enabling multisample buffer contexts. Multisampling
       will be enabled when numsamples > 1.

   int SoQtGLWidget::getSampleBuffers (void) const
       Returns the number of samples used for multisampling. Returns 1 if multisampling is
       disabled.

   void SoQtGLWidget::setStealFocus (SbBool enable)
       Sets whether the GL widget should steal keyboard focus when the mouse is over the GL view.

       Default is TRUE.

       See also:
           isStealFocus

       Since:
           SoQt 1.3.0

   SbBool SoQtGLWidget::isStealFocus (void) const
       Returns whether focus stealing policy is on (TRUE) or off (FALSE).

       Default is TRUE.

       See also:
           setStealFocus

       Since:
           SoQt 1.3.0

   QWidget * SoQtGLWidget::getGLWidget (void) const
       Returns a pointer to the toolkit-native GL widget.

       Referenced by SoQtPlaneViewer::afterRealizeHook(), getNormalWidget(), getOverlayWidget(),
       glFlushBuffer(), hasNormalGLArea(), SoQtFullViewer::openPopupMenu(),
       SoQtRenderArea::registerDevice(), SoQtFullViewer::setComponentCursor(), setGLSize(),
       SoQtRenderArea::unregisterDevice(), and SoQtRenderArea::widgetChanged().

   QWidget * SoQtGLWidget::getNormalWidget (void) const
       For SoQt, this returns the same widget pointer as that of SoQtGLWidget::getGLWidget().

       References getGLWidget().

       Referenced by hasNormalGLArea().

   QWidget * SoQtGLWidget::getOverlayWidget (void) const
       Returns widget associated with overlay planes, or NULL if no overlay planes are available.

       For the Qt toolkit, overlay planes is a feature of the QGLWidget, and not seen at a
       separate widget entity. So this call will just return the same widget reference as the
       SoQt::getGLWidget() call (if overlay planes are supported).

       References getGLWidget().

       Referenced by hasOverlayGLArea().

   SbBool SoQtGLWidget::hasOverlayGLArea (void) const
       Will return TRUE if an overlay GL drawing area exists.

       References getOverlayWidget().

       Referenced by SoQtRenderArea::glScheduleRedraw(), and SoQtRenderArea::redrawOverlay().

   SbBool SoQtGLWidget::hasNormalGLArea (void) const
       Will return TRUE if a normal GL drawing area exists.

       References getGLWidget(), getNormalWidget(), SoQtComponent::getSize(), glScheduleRedraw(),
       SoQt::NO_OPENGL_CANVAS, processEvent(), and waitForExpose.

       Referenced by SoQtRenderArea::redraw().

   unsigned long SoQtGLWidget::getOverlayTransparentPixel (void)
       Returns the overlay transparent pixel.

   void SoQtGLWidget::getPointSizeLimits (SbVec2f & range, float & granularity)
       This function is provided as a convenience for the application programmer to help with
       acquiring the OpenGL implementation limits for rendering points.

       For robust application code, one needs to consider the range limits when setting the
       SoDrawStyle::pointSize field.

       References glLockNormal(), and glUnlockNormal().

   void SoQtGLWidget::getLineWidthLimits (SbVec2f & range, float & granularity)
       This function is provided as a convenience for the application programmer to help with
       acquiring the OpenGL implementation limits for rendering lines.

       For robust application code, one needs to consider the range limits when setting the
       SoDrawStyle::lineWidth field.

       References glLockNormal(), and glUnlockNormal().

   void SoQtGLWidget::processEvent (QEvent * anyevent) [protected],  [virtual]
       Any events from the native window system that goes to the OpenGL canvas gets piped through
       this method.

       It is overridden in the subclasses to catch user interaction with the render canvas in the
       viewers, aswell as forwarding relevant events to the scenegraph.

       Reimplemented in SoQtRenderArea.

       Referenced by hasNormalGLArea().

   QWidget * SoQtGLWidget::buildWidget (QWidget * parent) [protected]
       This method builds the component contents in the given parent widget. For subclasses
       adding new user interface items, this method is typically overridden in the following
       manner:

       QWidget * MyOwnViewer::buildWidget(QWidget * parent)
       {
          QWidget * superw = <superclass>::buildWidget(parent);
          // [then move superw within MyOwnViewer framework and add own
          // user interface components]
       }

       References SoQtComponent::isTopLevelShell(), and SoQtComponent::registerWidget().

       Referenced by SoQtGLWidget().

   void SoQtGLWidget::redraw (void) [protected],  [pure virtual]
       This method is invoked when the GL buffer needs to be redrawn.

       Implemented in SoQtRenderArea.

   void SoQtGLWidget::redrawOverlay (void) [protected],  [virtual]
       Renders the overlay scene graph. Default method is empty. Subclasses should override this
       method.

       Reimplemented in SoQtRenderArea.

   void SoQtGLWidget::initGraphic (void) [protected],  [virtual]
       Will be called when GL widget should initialize graphic, after the widget has been
       created. Default method enabled GL_DEPTH_TEST.

       Reimplemented in SoQtRenderArea.

       References glLockNormal(), and glUnlockNormal().

   void SoQtGLWidget::initOverlayGraphic (void) [protected],  [virtual]
       Will be called after the overlay widget has been created, and subclasses should override
       this to initialize overlay stuff.

       Default method does nothing.

       Reimplemented in SoQtRenderArea.

   void SoQtGLWidget::sizeChanged (const SbVec2s & size) [protected],  [virtual]
       Called internally from within the SoQt library when the widget embedded in a component
       changes it size, which is usually triggered by end-user interaction.

       This method is then invoked to notify the component that the size has changed. It is
       called from the top and all the way down to the bottom, the size being adjusted to take
       into account extra decorations having been added at each level in the component class
       hierarchy.

       Reimplemented from SoQtComponent.

       Reimplemented in SoQtViewer, SoQtRenderArea, and SoQtFullViewer.

   void SoQtGLWidget::widgetChanged (QWidget * w) [protected],  [virtual]
       This is the method which gets called whenever we change which OpenGL widget is used.

       Should be overridden in subclasses which directly or indirectly store the return value
       from the SoQtGLWidget::getGLWidget() method.

       See also:
           sizeChanged()

       Reimplemented in SoQtRenderArea.

   void SoQtGLWidget::setGLSize (const SbVec2s size) [protected]
       Sets the size of the GL canvas.

       References getGLWidget(), and isBorder().

       Referenced by SoQtRenderArea::sizeChanged().

   SbVec2s SoQtGLWidget::getGLSize (void) const [protected]
       Return the dimensions of the OpenGL canvas.

       Referenced by SoQtFullViewer::openPopupMenu(), SoQtPlaneViewer::processSoEvent(),
       SoQtExaminerViewer::processSoEvent(), SoQtRenderArea::registerDevice(),
       SoQtRenderArea::setOverlaySceneManager(), SoQtRenderArea::setSceneManager(),
       SoQtExaminerViewer::setViewing(), and SoQtRenderArea::sizeChanged().

   float SoQtGLWidget::getGLAspectRatio (void) const [protected]
       Return the aspect ratio of the OpenGL canvas.

       Referenced by SoQtPlaneViewer::afterRealizeHook(), SoQtPlaneViewer::bottomWheelMotion(),
       SoQtPlaneViewer::leftWheelMotion(), SoQtPlaneViewer::processSoEvent(),
       SoQtExaminerViewer::processSoEvent(), and SoQtExaminerViewer::setViewing().

   void SoQtGLWidget::setGlxSize (const SbVec2s size) [inline],  [protected]
       This function has been renamed to the more appropriate setGLSize.

       See also:
           setGLSize

   SbVec2s SoQtGLWidget::getGlxSize (void) const [inline],  [protected]
       This function has been renamed to the more appropriate getGLSize.

       See also:
           getGLSize

   float SoQtGLWidget::getGlxAspectRatio (void) const [inline],  [protected]
       This function has been renamed to the more appropriate getGLAspectRatio.

       See also:
           getGLAspectRatio

   void SoQtGLWidget::setStereoBuffer (SbBool flag) [protected]
       Sets whether OpenGL stereo buffers (quad buffer stereo) should be used.

       References setQuadBufferStereo().

   SbBool SoQtGLWidget::isStereoBuffer (void) const [protected]
       Returns whether OpenGL stereo buffers are being used.

       References isQuadBufferStereo().

   SbBool SoQtGLWidget::isRGBMode (void) [protected]
       Returns TRUE if the normal GL context is in RGBA mode. Return FALSE if color index mode is
       used.

       Referenced by SoQtRenderArea::initGraphic(), and SoQtRenderArea::widgetChanged().

   void SoQtGLWidget::glLockNormal (void) [protected]
       This method calls make-current on the correct context and ups the lock level.

       Referenced by getLineWidthLimits(), getPointSizeLimits(), initGraphic(),
       SoQtRenderArea::processEvent(), and SoQtRenderArea::redraw().

   void SoQtGLWidget::glUnlockNormal (void) [protected]
       This method drops the lock level.

       Referenced by getLineWidthLimits(), getPointSizeLimits(), initGraphic(),
       SoQtRenderArea::processEvent(), and SoQtRenderArea::redraw().

   void SoQtGLWidget::glLockOverlay (void) [protected]
       This method calls make-current on the correct context and ups the lock level.

       Referenced by SoQtRenderArea::redrawOverlay().

   void SoQtGLWidget::glUnlockOverlay (void) [protected]
       This method drops the lock level.

       Referenced by SoQtRenderArea::redrawOverlay().

   void SoQtGLWidget::glSwapBuffers (void) [protected]
       Swap back buffer to front and vice versa.

       Referenced by SoQtRenderArea::redraw().

   void SoQtGLWidget::glFlushBuffer (void) [protected]
       Flush the current GL buffer. Simply calls glFlush().

       References getGLWidget().

       Referenced by SoQtRenderArea::redraw(), and SoQtRenderArea::redrawOverlay().

   SbBool SoQtGLWidget::glScheduleRedraw (void) [protected],  [virtual]
       Will be called whenever scene graph needs to be redrawn. If this method return FALSE,
       redraw() will be called immediately.

       Default method simply returns FALSE. Override this method to schedule a redraw and return
       TRUE if you're trying to do The Right Thing.

       Reimplemented in SoQtRenderArea.

       Referenced by hasNormalGLArea().

Member Data Documentation

   SbBool SoQtGLWidget::waitForExpose [protected]
       If this is TRUE, rendering should not be done yet. Upon the first expose event of a newly
       created OpenGL widget, this variable will be set to FALSE.

       Referenced by hasNormalGLArea(), SoQtRenderArea::redraw(), and
       SoQtRenderArea::redrawOverlay().

   SbBool SoQtGLWidget::drawToFrontBuffer [protected]
       If this is TRUE, rendering will happen in the front buffer even if the current rendering
       mode is double buffered.

       Referenced by isDrawToFrontBufferEnable(), and setDrawToFrontBufferEnable().

Author

       Generated automatically by Doxygen for SoQt from the source code.