From bd0f3345a938b35ce6a12f6150373b0955b8dd12 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Sun, 10 Jul 2011 15:24:15 -0500 Subject: Add Qt3 development HEAD version --- doc/html/qglformat.html | 474 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 474 insertions(+) create mode 100644 doc/html/qglformat.html (limited to 'doc/html/qglformat.html') diff --git a/doc/html/qglformat.html b/doc/html/qglformat.html new file mode 100644 index 0000000..e4967ef --- /dev/null +++ b/doc/html/qglformat.html @@ -0,0 +1,474 @@ + + + + + +QGLFormat Class + + + + + + + +

QGLFormat Class Reference
[OpenGL module]

+ +

The QGLFormat class specifies the display format of an OpenGL +rendering context. +More... +

#include <qgl.h> +

Inherits QGL. +

List of all member functions. +

Public Members

QGLFormat ()
QGLFormat ( int options, int plane = 0 )
bool doubleBuffer () const
void setDoubleBuffer ( bool enable )
bool depth () const
void setDepth ( bool enable )
bool rgba () const
void setRgba ( bool enable )
bool alpha () const
void setAlpha ( bool enable )
bool accum () const
void setAccum ( bool enable )
bool stencil () const
void setStencil ( bool enable )
bool stereo () const
void setStereo ( bool enable )
bool directRendering () const
void setDirectRendering ( bool enable )
bool hasOverlay () const
void setOverlay ( bool enable )
int plane () const
void setPlane ( int plane )
void setOption ( FormatOption opt )
bool testOption ( FormatOption opt ) const

Static Public Members

QGLFormat defaultFormat ()
void setDefaultFormat ( const QGLFormat & f )
QGLFormat defaultOverlayFormat ()
void setDefaultOverlayFormat ( const QGLFormat & f )
bool hasOpenGL ()
bool hasOpenGLOverlays ()

Detailed Description

+ + +The QGLFormat class specifies the display format of an OpenGL +rendering context. + +

+ + +

A display format has several characteristics: +

Double or single buffering. +
Depth buffer. +
RGBA or color index mode. +
Alpha channel. +
Accumulation buffer. +
Stencil buffer. +
Stereo buffers. +
Direct rendering. +
Presence of an overlay. +
The plane of an overlay format. +

You create and tell a QGLFormat object what rendering options you +want from an OpenGL^* rendering context. +

OpenGL drivers or accelerated hardware may or may not support +advanced features such as alpha channel or stereographic viewing. +If you request some features that the driver/hardware does not +provide when you create a QGLWidget, you will get a rendering +context with the nearest subset of features. +

There are different ways to define the display characteristics of +a rendering context. One is to create a QGLFormat and make it the +default for the entire application: +

+    QGLFormat f;
+    f.setAlpha( TRUE );
+    f.setStereo( TRUE );
+    QGLFormat::setDefaultFormat( f );
+

+ +

Or you can specify the desired format when creating an object of +your QGLWidget subclass: +

+    QGLFormat f;
+    f.setDoubleBuffer( FALSE );                 // single buffer
+    f.setDirectRendering( FALSE );              // software rendering
+    MyGLWidget* myWidget = new MyGLWidget( f, ... );
+

+ +

After the widget has been created, you can find out which of the +requested features the system was able to provide: +

+    QGLFormat f;
+    f.setOverlay( TRUE );
+    f.setStereo( TRUE );
+    MyGLWidget* myWidget = new MyGLWidget( f, ... );
+    if ( !w->format().stereo() ) {
+        // ok, goggles off
+        if ( !w->format().hasOverlay() ) {
+            qFatal( "Cool hardware required" );
+        }
+    }
+

+ +

^* OpenGL is a trademark of Silicon Graphics, Inc. in the +United States and other countries. +

Member Function Documentation

QGLFormat::QGLFormat () +

+Constructs a QGLFormat object with the factory default settings: +

Double buffer: Enabled. +
Depth buffer: Enabled. +
RGBA: Enabled (i.e., color index disabled). +
Alpha channel: Disabled. +
Accumulator buffer: Disabled. +
Stencil buffer: Disabled. +
Stereo: Disabled. +
Direct rendering: Enabled. +
Overlay: Disabled. +
Plane: 0 (i.e., normal plane). +

+ +

QGLFormat::QGLFormat ( int options, int plane = 0 ) +

+Creates a QGLFormat object that is a copy of the current application default format. +

If options is not 0, this copy is modified by these format +options. The options parameter should be FormatOption values +OR'ed together. +

This constructor makes it easy to specify a certain desired format +in classes derived from QGLWidget, for example: +

+    // The rendering in MyGLWidget depends on using
+    // stencil buffer and alpha channel
+    MyGLWidget::MyGLWidget( QWidget* parent, const char* name )
+        : QGLWidget( QGLFormat( StencilBuffer | AlphaChannel ), parent, name )
+    {
+        if ( !format().stencil() )
+            qWarning( "Could not get stencil buffer; results will be suboptimal" );
+        if ( !format().alphaChannel() )
+            qWarning( "Could not get alpha channel; results will be suboptimal" );
+        ...
+    }
+

+ +

Note that there are FormatOption values to turn format settings +both on and off, e.g. DepthBuffer and NoDepthBuffer, +DirectRendering and IndirectRendering, etc. +

The plane parameter defaults to 0 and is the plane which this +format should be associated with. Not all OpenGL implmentations +supports overlay/underlay rendering planes. +

See also defaultFormat() and setOption(). + +

bool QGLFormat::accum () const +

+ +

Returns TRUE if the accumulation buffer is enabled; otherwise +returns FALSE. The accumulation buffer is disabled by default. +

bool QGLFormat::alpha () const +

+ +

Returns TRUE if the alpha channel of the framebuffer is enabled; +otherwise returns FALSE. The alpha channel is disabled by default. +

QGLFormat QGLFormat::defaultFormat () `[static]` +

+Returns the default QGLFormat for the application. All QGLWidgets +that are created use this format unless another format is +specified, e.g. when they are constructed. +

If no special default format has been set using +setDefaultFormat(), the default format is the same as that created +with QGLFormat(). +

QGLFormat QGLFormat::defaultOverlayFormat () `[static]` +

+Returns the default QGLFormat for overlay contexts. +

The factory default overlay format is: +

Double buffer: Disabled. +
Depth buffer: Disabled. +
RGBA: Disabled (i.e., color index enabled). +
Alpha channel: Disabled. +
Accumulator buffer: Disabled. +
Stencil buffer: Disabled. +
Stereo: Disabled. +
Direct rendering: Enabled. +
Overlay: Disabled. +
Plane: 1 (i.e., first overlay plane). +

bool QGLFormat::depth () const +

+ +

Returns TRUE if the depth buffer is enabled; otherwise returns +FALSE. The depth buffer is enabled by default. +

bool QGLFormat::directRendering () const +

+ +

Returns TRUE if direct rendering is enabled; otherwise returns +FALSE. +

Direct rendering is enabled by default. +

bool QGLFormat::doubleBuffer () const +

+ +

Returns TRUE if double buffering is enabled; otherwise returns +FALSE. Double buffering is enabled by default. +

bool QGLFormat::hasOpenGL () `[static]` +

+ +

Returns TRUE if the window system has any OpenGL support; +otherwise returns FALSE. +

Warning: This function must not be called until the QApplication +object has been created. + +

bool QGLFormat::hasOpenGLOverlays () `[static]` +

+ +

Returns TRUE if the window system supports OpenGL overlays; +otherwise returns FALSE. +

Warning: This function must not be called until the QApplication +object has been created. + +

bool QGLFormat::hasOverlay () const +

+ +

Returns TRUE if overlay plane is enabled; otherwise returns FALSE. +

Overlay is disabled by default. +

int QGLFormat::plane () const +

+Returns the plane of this format. The default for normal formats +is 0, which means the normal plane. The default for overlay +formats is 1, which is the first overlay plane. +

bool QGLFormat::rgba () const +

+ +

Returns TRUE if RGBA color mode is set. Returns FALSE if color +index mode is set. The default color mode is RGBA. +

void QGLFormat::setAccum ( bool enable ) +

+If enable is TRUE enables the accumulation buffer; otherwise +disables the accumulation buffer. +

The accumulation buffer is disabled by default. +

The accumulation buffer is used to create blur effects and +multiple exposures. +

void QGLFormat::setAlpha ( bool enable ) +

+If enable is TRUE enables the alpha channel; otherwise disables +the alpha channel. +

The alpha buffer is disabled by default. +

The alpha channel is typically used for implementing transparency +or translucency. The A in RGBA specifies the transparency of a +pixel. +

void QGLFormat::setDefaultFormat ( const QGLFormat & f ) `[static]` +

+Sets a new default QGLFormat for the application to f. For +example, to set single buffering as the default instead of double +buffering, your main() might contain code like this: +

+    QApplication a(argc, argv);
+    QGLFormat f;
+    f.setDoubleBuffer( FALSE );
+    QGLFormat::setDefaultFormat( f );
+

+ +

void QGLFormat::setDefaultOverlayFormat ( const QGLFormat & f ) `[static]` +

+Sets a new default QGLFormat for overlay contexts to f. This +format is used whenever a QGLWidget is created with a format that +hasOverlay() enabled. +

For example, to get a double buffered overlay context (if +available), use code like this: +

+    QGLFormat f = QGLFormat::defaultOverlayFormat();
+    f.setDoubleBuffer( TRUE );
+    QGLFormat::setDefaultOverlayFormat( f );
+

+ +

As usual, you can find out after widget creation whether the +underlying OpenGL system was able to provide the requested +specification: +

+    // ...continued from above
+    MyGLWidget* myWidget = new MyGLWidget( QGLFormat( QGL::HasOverlay ), ... );
+    if ( myWidget->format().hasOverlay() ) {
+        // Yes, we got an overlay, let's check _its_ format:
+        QGLContext* olContext = myWidget->overlayContext();
+        if ( olContext->format().doubleBuffer() )
+            ; // yes, we got a double buffered overlay
+        else
+            ; // no, only single buffered overlays are available
+    }
+

+ +

void QGLFormat::setDepth ( bool enable ) +

+If enable is TRUE enables the depth buffer; otherwise disables +the depth buffer. +

The depth buffer is enabled by default. +

The purpose of a depth buffer (or Z-buffering) is to remove hidden +surfaces. Pixels are assigned Z values based on the distance to +the viewer. A pixel with a high Z value is closer to the viewer +than a pixel with a low Z value. This information is used to +decide whether to draw a pixel or not. +

void QGLFormat::setDirectRendering ( bool enable ) +

+If enable is TRUE enables direct rendering; otherwise disables +direct rendering. +

Direct rendering is enabled by default. +

Enabling this option will make OpenGL bypass the underlying window +system and render directly from hardware to the screen, if this is +supported by the system. +

void QGLFormat::setDoubleBuffer ( bool enable ) +

+If enable is TRUE sets double buffering; otherwise sets single +buffering. +

Double buffering is enabled by default. +

Double buffering is a technique where graphics are rendered on an +off-screen buffer and not directly to the screen. When the drawing +has been completed, the program calls a swapBuffers() function to +exchange the screen contents with the buffer. The result is +flicker-free drawing and often better performance. +

See also doubleBuffer(), QGLContext::swapBuffers(), and QGLWidget::swapBuffers(). + +

void QGLFormat::setOption ( FormatOption opt ) +

+Sets the format option to opt. +

void QGLFormat::setOverlay ( bool enable ) +

+If enable is TRUE enables an overlay plane; otherwise disables +the overlay plane. +

Enabling the overlay plane will cause QGLWidget to create an +additional context in an overlay plane. See the QGLWidget +documentation for further information. +

void QGLFormat::setPlane ( int plane ) +

+Sets the requested plane to plane. 0 is the normal plane, 1 is +the first overlay plane, 2 is the second overlay plane, etc.; -1, +-2, etc. are underlay planes. +

Note that in contrast to other format specifications, the plane +specifications will be matched exactly. This means that if you +specify a plane that the underlying OpenGL system cannot provide, +an invalid QGLWidget will be +created. +

void QGLFormat::setRgba ( bool enable ) +

+If enable is TRUE sets RGBA mode. If enable is FALSE sets +color index mode. +

The default color mode is RGBA. +

RGBA is the preferred mode for most OpenGL applications. In RGBA +color mode you specify colors as red + green + blue + alpha +quadruplets. +

In color index mode you specify an index into a color lookup +table. +

void QGLFormat::setStencil ( bool enable ) +

+If enable is TRUE enables the stencil buffer; otherwise +disables the stencil buffer. +

The stencil buffer is disabled by default. +

The stencil buffer masks certain parts of the drawing area so that +masked parts are not drawn on. +

void QGLFormat::setStereo ( bool enable ) +

+If enable is TRUE enables stereo buffering; otherwise disables +stereo buffering. +

Stereo buffering is disabled by default. +

Stereo buffering provides extra color buffers to generate left-eye +and right-eye images. +

bool QGLFormat::stencil () const +

+ +

Returns TRUE if the stencil buffer is enabled; otherwise returns +FALSE. The stencil buffer is disabled by default. +

bool QGLFormat::stereo () const +

+ +

Returns TRUE if stereo buffering is enabled; otherwise returns +FALSE. Stereo buffering is disabled by default. +

bool QGLFormat::testOption ( FormatOption opt ) const +

+Returns TRUE if format option opt is set; otherwise returns FALSE. +

QGLFormat Class Reference[OpenGL module]