qglformat.3qt

Linux下的基于X11的图形开发环境。

'\" t
.TH QGLFormat 3qt "9 December 2002" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2001 Trolltech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QGLFormat \- The display format of an OpenGL rendering context
.SH SYNOPSIS
\fC#include <qgl.h>\fR
.PP
Inherits QGL.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "\fBQGLFormat\fR ()"
.br
.ti -1c
.BI "\fBQGLFormat\fR ( int options, int plane = 0 )"
.br
.ti -1c
.BI "bool \fBdoubleBuffer\fR () const"
.br
.ti -1c
.BI "void \fBsetDoubleBuffer\fR ( bool enable )"
.br
.ti -1c
.BI "bool \fBdepth\fR () const"
.br
.ti -1c
.BI "void \fBsetDepth\fR ( bool enable )"
.br
.ti -1c
.BI "bool \fBrgba\fR () const"
.br
.ti -1c
.BI "void \fBsetRgba\fR ( bool enable )"
.br
.ti -1c
.BI "bool \fBalpha\fR () const"
.br
.ti -1c
.BI "void \fBsetAlpha\fR ( bool enable )"
.br
.ti -1c
.BI "bool \fBaccum\fR () const"
.br
.ti -1c
.BI "void \fBsetAccum\fR ( bool enable )"
.br
.ti -1c
.BI "bool \fBstencil\fR () const"
.br
.ti -1c
.BI "void \fBsetStencil\fR ( bool enable )"
.br
.ti -1c
.BI "bool \fBstereo\fR () const"
.br
.ti -1c
.BI "void \fBsetStereo\fR ( bool enable )"
.br
.ti -1c
.BI "bool \fBdirectRendering\fR () const"
.br
.ti -1c
.BI "void \fBsetDirectRendering\fR ( bool enable )"
.br
.ti -1c
.BI "bool \fBhasOverlay\fR () const"
.br
.ti -1c
.BI "void \fBsetOverlay\fR ( bool enable )"
.br
.ti -1c
.BI "int \fBplane\fR () const"
.br
.ti -1c
.BI "void \fBsetPlane\fR ( int plane )"
.br
.ti -1c
.BI "void \fBsetOption\fR ( FormatOption opt )"
.br
.ti -1c
.BI "bool \fBtestOption\fR ( FormatOption opt ) const"
.br
.in -1c
.SS "Static Public Members"
.in +1c
.ti -1c
.BI "QGLFormat \fBdefaultFormat\fR ()"
.br
.ti -1c
.BI "void \fBsetDefaultFormat\fR ( const QGLFormat & f )"
.br
.ti -1c
.BI "QGLFormat \fBdefaultOverlayFormat\fR ()"
.br
.ti -1c
.BI "void \fBsetDefaultOverlayFormat\fR ( const QGLFormat & f )"
.br
.ti -1c
.BI "bool \fBhasOpenGL\fR ()"
.br
.ti -1c
.BI "bool \fBhasOpenGLOverlays\fR ()"
.br
.in -1c
.SH DESCRIPTION
The QGLFormat class specifies the display format of an OpenGL rendering context.
.PP
A display format has several characteristics:
.TP
Double or single buffering.
.TP
Depth buffer.
.TP
RGBA or color index mode.
.TP
Alpha channel.
.TP
Accumulation buffer.
.TP
Stencil buffer.
.TP
Stereo buffers.
.TP
Direct rendering.
.TP
Presence of an overlay.
.TP
The plane of an overlay format.
.PP
You create and tell a QGLFormat object what rendering options you want from an OpenGL<sup>*</sup> rendering context.
.PP
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.
.PP
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:
.PP
.nf
.br
    QGLFormat f;
.br
    f.setAlpha( TRUE );
.br
    f.setStereo( TRUE );
.br
    QGLFormat::setDefaultFormat( f );
.br
.fi
.PP
Or you can specify the desired format when creating an object of your QGLWidget subclass:
.PP
.nf
.br
    QGLFormat f;
.br
    f.setDoubleBuffer( FALSE );                 // single buffer
.br
    f.setDirectRendering( FALSE );              // software rendering
.br
    MyGLWidget* myWidget = new MyGLWidget( f, ... );
.br
.fi
.PP
After the widget has been created, you can find out which of the requested features the system was able to provide:
.PP
.nf
.br
    QGLFormat f;
.br
    f.setOverlay( TRUE );
.br
    f.setStereo( TRUE );
.br
    MyGLWidget* myWidget = new MyGLWidget( f, ... );
.br
    if ( !w->format().stereo() ) {
.br
        // ok, goggles off
.br
        if ( !w->format().hasOverlay() ) {
.br
            qFatal( "Cool hardware required" );
.br
        }
.br
    }
.br
.fi
.PP
<sup>*</sup> OpenGL is a trademark of Silicon Graphics, Inc. in the United States and other countries.
.PP
See also QGLContext, QGLWidget, Graphics Classes, and Image Processing Classes.
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QGLFormat::QGLFormat ()"
Constructs a QGLFormat object with the factory default settings:
.TP
Double buffer: Enabled.
.TP
Depth buffer: Enabled.
.TP
RGBA: Enabled (i.e., color index disabled).
.TP
Alpha channel: Disabled.
.TP
Accumulator buffer: Disabled.
.TP
Stencil buffer: Disabled.
.TP
Stereo: Disabled.
.TP
Direct rendering: Enabled.
.TP
Overlay: Disabled.
.TP
Plane: 0 (i.e., normal plane).
.SH "QGLFormat::QGLFormat ( int options, int plane = 0 )"
Creates a QGLFormat object that is a copy of the current application default format.
.PP
If \fIoptions\fR is not 0, this copy is modified by these format options. The \fIoptions\fR parameter should be FormatOption values OR'ed together.
.PP
This constructor makes it easy to specify a certain desired format in classes derived from QGLWidget, for example:
.PP
.nf
.br
    // The rendering in MyGLWidget depends on using
.br
    // stencil buffer and alpha channel
.br
    MyGLWidget::MyGLWidget( QWidget* parent, const char* name )
.br
        : QGLWidget( QGLFormat( StencilBuffer | AlphaChannel ), parent, name )
.br
    {
.br
        if ( !format().stencil() )
.br
            qWarning( "Could not get stencil buffer; results will be suboptimal" );
.br
        if ( !format().alphaChannel() )
.br
            qWarning( "Could not get alpha channel; results will be suboptimal" );
.br
        ...
.br
    }
.br
.fi
.PP
Note that there are FormatOption values to turn format settings both on and off, e.g. DepthBuffer and NoDepthBuffer, DirectRendering and IndirectRendering, etc.
.PP
The \fIplane\fR parameter defaults to 0 and is the plane which this format should be associated with. Not all OpenGL implmentations supports overlay/underlay rendering planes.