SoGuiGLWidgetCommon.cpp.in

// @configure_input@

/**************************************************************************\
 * Copyright (c) Kongsberg Oil & Gas Technologies AS
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 * 
 * Redistributions of source code must retain the above copyright notice,
 * this list of conditions and the following disclaimer.
 * 
 * Redistributions in binary form must reproduce the above copyright
 * notice, this list of conditions and the following disclaimer in the
 * documentation and/or other materials provided with the distribution.
 * 
 * Neither the name of the copyright holder nor the names of its
 * contributors may be used to endorse or promote products derived from
 * this software without specific prior written permission.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
\**************************************************************************/

#define PRIVATE(obj) ((SoGuiGLWidgetP *)(obj->pimpl))

// *************************************************************************

/*!
  \class So@Gui@GLWidget So@Gui@GLWidget.h Inventor/@Gui@/So@Gui@GLWidget.h
  \brief The So@Gui@GLWidget class manages OpenGL contexts.

  \ingroup components

  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,
  So@Gui@RenderArea, or through one of the "rapid application
  development"-style viewer subclasses.

  \if SOQT_DOC

  An important thing to know about embedding So@Gui@GLWidget derived
  components into other @Gui@ 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 So@Gui@RenderArea as well as all
  the viewer components (like So@Gui@ExaminerViewer,
  So@Gui@PlaneViewer etc).

  As an example, if you embed an So@Gui@ExaminerViewer inside a QFrame
  like this:

  \code
  QMainWindow * toplevel = new QMainWindow;
  QFrame * frame = new QFrame(toplevel);
  So@Gui@ExaminerViewer * viewer = new So@Gui@ExaminerViewer(toplevel);
  \endcode

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

  \code
  toplevel->setFocusProxy(viewer->getWidget());
  \endcode

  \endif

  \if SOWIN_DOC

  For debugging purposes, SoWinGLWidget provides the
  OIV_FORCE_PIXEL_FORMAT environment variable to make it possible to
  override the pixel format chosen by the internal attribute match
  algorithm.

  \endif
*/

// *************************************************************************

#ifdef HAVE_CONFIG_H
#include <config.h>
#endif // HAVE_CONFIG_H

#include <Inventor/@Gui@/common/gl.h>
#include <Inventor/@Gui@/So@Gui@GLWidget.h>
#include <Inventor/@Gui@/So@Gui@GLWidgetP.h>

// *************************************************************************

// All shared documentation for functions with specific
// implementations in the individual toolkits.

/*!
  \fn So@Gui@GLWidget::So@Gui@GLWidget(@WIDGET@ const parent, const char * const name, const SbBool embed, const int glmodes, const SbBool build)

  The constructor is protected, as this is an abstract class to only
  be used by its subclasses.
*/

/*!
  \fn So@Gui@GLWidget::~So@Gui@GLWidget()

  Clean up all use of internal resources.

  The destructor is protected, as this is an abstract class to only be
  used by its subclasses.
*/

/*!
  \fn void So@Gui@GLWidget::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.

  \sa isBorder()
*/

/*!
  \fn SbBool So@Gui@GLWidget::isBorder(void) const

  Returns whether or not there's a border framing the OpenGL canvas.

  \sa setBorder()
*/

/*!
  \fn void So@Gui@GLWidget::setOverlayRender(const SbBool onoff)

  Turn on or off the use of overlay planes.

  \sa isOverlayRender()
*/

/*!
  \fn SbBool So@Gui@GLWidget::isOverlayRender(void) const

  Returns a flag indicating whether or not overplay planes are
  currently used.

  \sa setOverlayRender()
*/

/*!
  \fn void So@Gui@GLWidget::setDoubleBuffer(const SbBool enable)

  Switch between single and double buffer mode for the OpenGL canvas.
  The default is to use a single buffer canvas.

  \sa isDoubleBuffer()
*/

/*!
  \fn SbBool So@Gui@GLWidget::isDoubleBuffer(void) const

  Returns the status of the buffer mode.

  \sa setDoubleBuffer()
*/

/*!
  \fn void So@Gui@GLWidget::setQuadBufferStereo(const SbBool enable)

  Enables or disables OpenGL quad buffer stereo.
*/

/*!
  \fn SbBool So@Gui@GLWidget::isQuadBufferStereo(void) const

  Returns \c TRUE if quad buffer stereo is enabled for this widget.
*/

/*!
  \fn void So@Gui@GLWidget::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 \e 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-accelerated rendering, etc).

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

  \sa So@Gui@RenderArea::setAntiAliasing()
*/

/*!
  \fn SbBool So@Gui@GLWidget::getAccumulationBuffer(void) const

  Returns whether the OpenGL accumulation buffer is enabled.

  The returned flag will indicate whether or not accumulation buffers
  are \e actually present, and not just parrot the input value to
  So@Gui@GLWidget::setAccumulationBuffer(). See documentation of that
  function for more information.
*/

/*!
  \fn void So@Gui@GLWidget::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
  So@Gui@GLWidget::setAccumulationBuffer().
*/

/*!
  \fn SbBool So@Gui@GLWidget::getStencilBuffer(void) const

  Returns whether the OpenGL stencil buffer is enabled.

  The returned flag will indicate whether or not stencil buffers are
  \e actually present, in the same manner as for
  So@Gui@GLWidget::getAccumulationBuffer(). See documentation of
  So@Gui@GLWidget::setStencilBuffer().
*/

/*!
  \fn void So@Gui@GLWidget::setAlphaChannel(const SbBool enable)

  Enables/disables the alpha channel for the OpenGL context.
*/

/*!
  \fn SbBool So@Gui@GLWidget::getAlphaChannel(void) const

  Returns whether the alpha channel is enabled for the OpenGL context.
*/

/*!
  \fn void So@Gui@GLWidget::setDrawToFrontBufferEnable(const SbBool enable)

  If this is set to \c TRUE, rendering will happen in the front buffer
  even if the current rendering mode is double buffered.
*/

/*!
  \fn SbBool So@Gui@GLWidget::isDrawToFrontBufferEnable(void) const
  \sa setDrawToFrontBufferEnable()
*/

/*!
  \fn @WIDGET@ So@Gui@GLWidget::buildWidget(@WIDGET@ parent)

  This method builds the component contents in the given \a parent
  widget. For subclasses adding new user interface items, this method
  is typically overridden in the following manner:

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

/*!
  \fn virtual void So@Gui@GLWidget::redraw(void)

  This method is invoked when the GL buffer needs to be redrawn.
 */

/*!
  \var SbBool So@Gui@GLWidget::waitForExpose

  If this is \c TRUE, rendering should not be done yet. Upon the first
  expose event of a newly created OpenGL widget, this variable will
  be set to \c FALSE.
*/

/*!
  \var SbBool So@Gui@GLWidget::drawToFrontBuffer

  If this is \c TRUE, rendering will happen in the front buffer even
  if the current rendering mode is double buffered.
*/

/*!
  \fn @WIDGET@ So@Gui@GLWidget::getNormalWidget(void) const

  \if SOQT_DOC
  For SoQt, this returns the same widget pointer as that of
  SoQtGLWidget::getGLWidget().
  \endif
*/

/*!
  \fn @WIDGET@ So@Gui@GLWidget::getOverlayWidget(void) const

  Returns widget associated with overlay planes, or \c NULL if no
  overlay planes are available.

  \if SOQT_DOC
  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).
  \endif
*/

/*!
  \fn void So@Gui@GLWidget::setGLSize(const SbVec2s size)
  Sets the size of the GL canvas.
*/

/*!
  \fn SbVec2s So@Gui@GLWidget::getGLSize(void) const

  Return the dimensions of the OpenGL canvas.
*/

/*!
  \fn float So@Gui@GLWidget::getGLAspectRatio(void) const

  Return the aspect ratio of the OpenGL canvas.
*/

/*!
  \fn void So@Gui@GLWidget::setGlxSize(const SbVec2s size)
  This function has been renamed to the more appropriate setGLSize.
  \sa setGLSize
*/

/*!
  \fn SbVec2s So@Gui@GLWidget::getGlxSize(void) const
  This function has been renamed to the more appropriate getGLSize.
  \sa getGLSize
*/

/*!
  \fn float So@Gui@GLWidget::getGlxAspectRatio(void) const
  This function has been renamed to the more appropriate getGLAspectRatio.
  \sa getGLAspectRatio
*/

/*!
  \fn @WIDGET@ So@Gui@GLWidget::getGLWidget(void) const

  Returns a pointer to the toolkit-native GL widget.
*/

/*!
  \fn void So@Gui@GLWidget::widgetChanged(@WIDGET@ w)

  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 So@Gui@GLWidget::getGLWidget()
  method.

  \sa sizeChanged()
*/

/*!
  \fn void So@Gui@GLWidget::processEvent(@EVENT@ anyevent)

  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, as well as forwarding relevant
  events to the scene graph.
*/

/*!
  \fn void So@Gui@GLWidget::glLockNormal(void)

  This method calls make-current on the correct context and increases the
  lock level.
*/

/*!
  \fn void So@Gui@GLWidget::glUnlockNormal(void)

  This method decreases the lock level.
*/

/*!
  \fn void So@Gui@GLWidget::glSwapBuffers(void)
  Swap back buffer to front and vice versa.
*/

/*!
  \fn void So@Gui@GLWidget::glFlushBuffer(void)

  Flush the current GL buffer. Simply calls glFlush().
*/

/*!
  \fn void So@Gui@GLWidget::glLockOverlay(void)

  This method calls make-current on the correct context and increases the
  lock level.
*/

/*!
  \fn void So@Gui@GLWidget::glUnlockOverlay(void)

  This method decreases the lock level.
*/

/*!
  \fn unsigned long So@Gui@GLWidget::getOverlayTransparentPixel(void)
  Returns the overlay transparent pixel.
*/

/*!
  \fn SbBool So@Gui@GLWidget::isRGBMode(void)

  Returns \c TRUE if the normal GL context is in RGBA mode.
  Return \c FALSE if color index mode is used.
*/

/*!
  \fn void So@Gui@GLWidget::redrawOverlay(void)

  Renders the overlay scene graph. Default method is empty. Subclasses
  should override this method.
*/

/*!
  \fn SbBool So@Gui@GLWidget::hasNormalGLArea(void) const 

  Will return \c TRUE if a normal GL drawing area exists.
*/

/*!
  \fn SbBool So@Gui@GLWidget::hasOverlayGLArea(void) const 

  Will return \c TRUE if an overlay GL drawing area exists.
*/

/*!
  \fn void So@Gui@GLWidget::initGraphic(void)

  Will be called when GL widget should initialize graphic, after
  the widget has been created. Default method enabled GL_DEPTH_TEST.
*/

/*!
  \fn void So@Gui@GLWidget::initOverlayGraphic(void)

  Will be called after the overlay widget has been created, and subclasses
  should override this to initialize overlay stuff.

  Default method does nothing.
*/

/*!
  \fn SbBool So@Gui@GLWidget::glScheduleRedraw(void)

  Will be called whenever scene graph needs to be redrawn.  If this
  method return \c FALSE, redraw() will be called immediately.

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

/*!
  \fn void So@Gui@GLWidget::setStealFocus(SbBool enable)

  Sets whether the GL widget should steal keyboard focus when the
  mouse is over the GL view.

  Default is \c TRUE.

  \sa isStealFocus
  \since So@Gui@ 1.3.0
*/

/*!
  \fn SbBool So@Gui@GLWidget::isStealFocus(void) const

  Returns whether focus stealing policy is on (\c TRUE) or off (\c
  FALSE).

  Default is \c TRUE.

  \sa setStealFocus
  \since So@Gui@ 1.3.0
*/


/*! 
  \fn void So@Gui@GLWidget::setSampleBuffers(const int numsamples)
  
  Set the number of samples use when enabling multisample buffer contexts.
  Multisampling will be enabled when numsamples > 1.
  
*/

/*! 
  \fn int So@Gui@GLWidget::getSampleBuffers(void) const
  
  Returns the number of samples used for multisampling. Returns 1 if
  multisampling is disabled.
*/

// Documented in common/SoGuiGLWidgetCommon.cpp.in.
void
So@Gui@GLWidget::setStealFocus(SbBool enable)
{
  PRIVATE(this)->stealFocus = enable;
}

// Documented in common/SoGuiGLWidgetCommon.cpp.in.
SbBool
So@Gui@GLWidget::isStealFocus(void) const
{
  return PRIVATE(this)->stealFocus;
}

// *************************************************************************

/*!
  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.
*/
void
So@Gui@GLWidget::getPointSizeLimits(SbVec2f & range, float & granularity)
{
  this->glLockNormal();

  GLfloat vals[2];
  glGetFloatv(GL_POINT_SIZE_RANGE, vals);

  // Matthias Koenig reported on coin-discuss that the OpenGL
  // implementation on SGI Onyx 2 InfiniteReality returns 0 for the
  // lowest point size, but it will still set the return value of
  // glGetError() to GL_INVALID_VALUE if this size is attempted
  // used. So the boundary range fix in the next line of code is a
  // workaround for that OpenGL implementation bug.
  //
  // 0.0f and lower values are explicitly disallowed, according to
  // the OpenGL 1.3 specification, Chapter 3.3.

  if (vals[0] <= 0.0f) { vals[0] = So@Gui@Min(1.0f, vals[1]); }

  range.setValue(vals[0], vals[1]);

  GLfloat gran[1];
  glGetFloatv(GL_POINT_SIZE_GRANULARITY, gran);
  granularity = gran[0];

  this->glUnlockNormal();
}

/*!
  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.
*/
void
So@Gui@GLWidget::getLineWidthLimits(SbVec2f & range, float & granularity)
{
  this->glLockNormal();

  GLfloat vals[2];
  glGetFloatv(GL_LINE_WIDTH_RANGE, vals);

  // Matthias Koenig reported on coin-discuss that the OpenGL
  // implementation on SGI Onyx 2 InfiniteReality returns 0 for the
  // lowest line width, but it will still set the return value of
  // glGetError() to GL_INVALID_VALUE if this size is attempted
  // used. This is a workaround for what looks like an OpenGL bug.

  if (vals[0] <= 0.0f) { vals[0] = So@Gui@Min(1.0f, vals[1]); }

  range.setValue(vals[0], vals[1]);

  GLfloat gran[1];
  glGetFloatv(GL_LINE_WIDTH_GRANULARITY, gran);
  granularity = gran[0];

  this->glUnlockNormal();
}

// FIXME: other implementation specifics to check are
//
//  * maximum stack depths (attribute, modelview matrix, name,
//    projection matrix, texture matrix)
//
//  * max display list nesting
//
//  * max nr of clip planes
//
//  * max nr of light sources
//
//  * max 3D texture size (needs specific extension?)
//
// 20020802 mortene.

/*!
  Sets whether OpenGL stereo buffers (quad buffer stereo) should be
  used.
*/
void
So@Gui@GLWidget::setStereoBuffer(SbBool flag)
{
  // FIXME: is this really correct? 20011012 mortene.
  this->setQuadBufferStereo(flag);
}

/*!
  Returns whether OpenGL stereo buffers are being used.
*/
SbBool
So@Gui@GLWidget::isStereoBuffer(void) const
{
  // FIXME: is this really correct? 20011012 mortene.
  return this->isQuadBufferStereo();
}

// *************************************************************************

#ifndef DOXYGEN_SKIP_THIS

// Remaining code is for the SoGuiGLWidgetP "private implementation"
// class.


SoGuiGLWidgetP::SoGuiGLWidgetP(So@Gui@GLWidget * publ)
{
  this->pub = publ;
  this->stealFocus = TRUE;
}

SoGuiGLWidgetP::~SoGuiGLWidgetP()
{
}

// Just forward from a static function, so we can find out from
// anywhere within the library -- without exposing the API for the app
// programmer.
SbBool
SoGuiGLWidgetP::isDirectRendering(So@Gui@GLWidget * w)
{
  return ((SoGuiGLWidgetP *)(w->pimpl))->isDirectRendering();
}

#undef PRIVATE
#endif // DOXYGEN_SKIP_THIS

// *************************************************************************