qgl.cpp

qtopia-phone-2.2.0 下支持的opengl源程序。

  Does nothing if this widget has no overlay.

  \sa makeCurrent()
*/


/*
  OBSOLETE

  Sets a new format for this widget.

  If the underlying OpenGL/Window system cannot satisfy all the
  features requested in \a format, the nearest subset of features will
  be used. After creation, the format() method will return the actual
  rendering context format obtained.

  The widget will be assigned a new QGLContext, and the initializeGL()
  function will be executed for this new context before the first
  resizeGL() or paintGL().

  This method will try to keep any existing display list sharing with
  other QGLWidgets, but it may fail. Use isSharing() to test.

  \sa format(), isSharing(), isValid()
*/

void QGLWidget::setFormat( const QGLFormat &format )
{
    setContext( new QGLContext(format,this) );
}




/*!
  \fn const QGLContext *QGLWidget::context() const
  Returns the context of this widget.
*/

/*
  OBSOLETE

  \fn void QGLWidget::setContext( QGLContext *context,
                                  const QGLContext* shareContext,
                                  bool deleteOldContext )

  Sets a new context for this widget. The QGLContext \a context must
  be created using \e new. QGLWidget will delete \a context when
  another context is set or when the widget is destroyed.

  If \a context is invalid, QGLContext::create() is performed on
  it. The initializeGL() function will then be executed for the new
  context before the first resizeGL() or paintGL().

  If \a context is invalid, this method will try to keep any existing
  display list sharing with other QGLWidgets this widget currently
  has, or (if \a shareContext points to a valid context) start display
  list sharing with that context, but it may fail. Use isSharing() to
  test.

  If \a deleteOldContext is TRUE (the default), the existing context
  will be deleted. You may use FALSE here if you have kept a pointer
  to the old context (as returned by context()), and want to restore
  that context later.

  \sa context(), isSharing()
*/



/*!
  \fn void QGLWidget::updateGL()
  Updates the widget by calling glDraw().
*/

void QGLWidget::updateGL()
{
    glDraw();
}


/*!
  \fn void QGLWidget::updateOverlayGL()
  Updates the widget's overlay (if any). Will cause the virtual
  function paintOverlayGL() to be executed, initializing first as
  necessary.
*/


/*!
  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 already been
  done when this function is called.
*/

void QGLWidget::initializeGL()
{
}


/*!
  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::paintGL()
{
}


/*!
  \fn void QGLWidget::resizeGL( int width , int height )
  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::resizeGL( int, int )
{
}



/*!
  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.
*/

void QGLWidget::initializeOverlayGL()
{
}


/*!
  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::paintOverlayGL()
{
}


/*!
  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::resizeOverlayGL( int, int )
{
}




/*!
  Handles paint events. Will cause the virtual paintGL() function to
  be called, initializing first as necessary.
*/

void QGLWidget::paintEvent( QPaintEvent * )
{
    glDraw();
    updateOverlayGL();
}


/*!
  \fn void QGLWidget::resizeEvent( QResizeEvent * )
  Handles resize events. Calls the virtual function resizeGL().
*/


/*!
  \fn void QGLWidget::setMouseTracking( bool enable )
  \reimp
*/


/*!
  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 \a w and height \a h. If any of
  those are 0 (the default), the pixmap will have the same size as the
  widget.

  If \a 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.

  \bug May give unexpected results if the depth of the GL rendering
  context is different from the depth of the desktop.
*/

QPixmap QGLWidget::renderPixmap( int w, int h, bool useContext )
{
    QPixmap nullPm;
    QSize sz = size();
    if ( (w > 0) && (h > 0) )
	sz = QSize( w, h );
    QPixmap pm( sz );
    glcx->doneCurrent();
    bool success = TRUE;

    if ( useContext && isValid() && renderCxPm( &pm ) )
	return pm;

    QGLFormat fmt = format();
    fmt.setDirectRendering( FALSE );		// No direct rendering
    fmt.setDoubleBuffer( FALSE );		// We don't need dbl buf
    QGLContext* pcx = new QGLContext( fmt, &pm );
    QGLContext* ocx = (QGLContext*)context();
    setContext( pcx, 0, FALSE );
    if ( pcx->isValid() )
	updateGL();
    else
	success = FALSE;
    setContext( ocx );				// Will delete pcx

    if ( success )
	return pm;
    else
	return nullPm;
}

/*!
  Initializes OpenGL for this widget's context. Calls the virtual
  function initializeGL().
*/

void QGLWidget::glInit()
{
    initializeGL();
    glcx->setInitialized( TRUE );
}


/*!
  Executes the virtual function paintGL(), initializing first as necessary.
*/

void QGLWidget::glDraw()
{
    makeCurrent();
    if ( glcx->deviceIsPixmap() )
	glDrawBuffer( GL_FRONT_LEFT );
    if ( !glcx->initialized() ) {
	glInit();
	QPaintDeviceMetrics dm( glcx->device() );
	resizeGL( dm.width(), dm.height() ); // New context needs this "resize"
    }
    paintGL();
    if ( doubleBuffer() ) {
	if ( autoSwap )
	    swapBuffers();
    }
    else {
	glFlush();
    }
}


/*!
  Convenience function for specifying a drawing color to OpenGL. Calls
  glColor3 (in RGBA mode) or glIndex (in color-index mode) with the
  color \a c. Applies to the current GL context.

  \sa qglClearColor(), QGLContext::currentContext(), QColor
*/

void QGLWidget::qglColor( const QColor& c ) const
{
    const QGLContext* ctx = QGLContext::currentContext();
    if ( ctx ) {
	if ( ctx->format().rgba() )
	    glColor3ub( c.red(), c.green(), c.blue() );
	else
	    glIndexi( ctx->colorIndex( c ) );
    }
}

/*!
  Convenience function for specifying the clearing color to
  OpenGL. Calls glClearColor (in RGBA mode) or glClearIndex (in
  color-index mode) with the color \a c. Applies to the current GL
  context.

  \sa qglColor(), QGLContext::currentContext(), QColor
*/

void QGLWidget::qglClearColor( const QColor& c ) const
{
    const QGLContext* ctx = QGLContext::currentContext();
    if ( ctx ) {
	if ( ctx->format().rgba() )
	    glClearColor( (GLfloat)c.red() / 255.0, (GLfloat)c.green() / 255.0,
			  (GLfloat)c.blue() / 255.0, (GLfloat) 0.0 );
	else
	    glClearIndex( ctx->colorIndex( c ) );
    }
}


/*!  

  Convenience function for converting a QImage into the format expected by
  OpenGL's texture functions.

*/


QImage QGLWidget::convertToGLFormat( const QImage& img )
{
    QImage res = img.convertDepth( 32 );
    res = res.mirror();

    if ( QImage::systemByteOrder() == QImage::BigEndian ) {
	// Qt has ARGB; OpenGL wants RGBA
	for ( int i=0; i < res.height(); i++ ) {
	    uint *p = (uint*)res.scanLine( i );
	    uint *end = p + res.width();
	    while ( p < end ) {
		*p <<= 8;
		p++;
	    }
	}
    }
    else {
	// Qt has ARGB; OpenGL wants ABGR (i.e. RGBA backwards)
	res = res.swapRGB();
    }
    return res;
}


/*****************************************************************************
  QGL classes overview documentation.
 *****************************************************************************/

/*! \page opengl.html

\title Qt OpenGL 3D Graphics

<h2>Introduction</h2>

OpenGL is a standard API for rendering 3D graphics.

OpenGL only deals with 3D rendering and provides little or no support
for GUI programming issues. The user interface for an OpenGL
application must be created with another toolkit, such as Motif on the
X platform, Microsoft Foundation Classes (MFC) under Windows - or Qt
on <i>both</i> platforms.

The Qt OpenGL module makes it easy to use OpenGL in Qt
applications.  It provides an OpenGL widget class that can be used
just like any other Qt widget, only that it opens an OpenGL display
buffer where you can use the OpenGL API to render the contents.
 
The Qt OpenGL module is implemented as a platform-independent
Qt/C++ wrapper around the platform-dependent GLX and WGL C APIs. The
provided functionality is very similar to Mark Kilgard's GLUT library,
but with much more non-OpenGL-specific GUI functionality: the whole Qt
API.

<h2>Installation</h2>

When you install Qt for X11, the configure script will autodetect if
OpenGL headers and libraries are installed on your system, and if so, it
will include the Qt OpenGL module in the Qt library. (If your OpenGL
headers or libraries are placed in a non-standard directory, you may need
to change the SYSCONF_CXXFLAGS_OPENGL and/or SYSCONF_LFLAGS_OPENGL in the
config file for your system).

When you install Qt for Windows, the Qt OpenGL module is always included.

The Qt OpenGL module is not licensed for use with the Qt Professional
Edition. Consider upgrading to the Qt Enterprise Edition if you require
OpenGL support.

Note about using Mesa on X11: Mesa versions earlier than 3.1 would use the
name "MesaGL" and "MesaGLU" for the libraries, instead of "GL" and
"GLU". If you want to use a pre-3.1 version of Mesa, you must change
the Makefiles to use these library names instead. The easiest way to
do this edit the SYSCONF_LIBS_OPENGL line in the config file you are
using, changing "-lGL -lGLU" to "-lMesaGL -lMesaGLU"; then run "configure"
again.

<h2>The QGL Classes</h2>

The OpenGL support classes in Qt are:
<ul>
<li> <strong>\link QGLWidget QGLWidget\endlink:</strong> An easy-to-use Qt
  widget for rendering OpenGL scenes.
<li> <strong>\link QGLContext QGLContext\endlink:</strong> Encapsulates an OpenGL rendering context.
<li> <strong>\link QGLFormat QGLFormat\endlink:</strong> Specifies the
display format of a rendering context.
</ul>

Many applications need only the high-level QGLWidget class. The other QGL
classes provide advanced features. */