summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorSamuel Rødal <samuel.rodal@nokia.com>2012-02-21 13:40:57 +0100
committerQt by Nokia <qt-info@nokia.com>2012-02-23 11:57:00 +0100
commit04652b9856f70c5d38eefd4907a02bd929059705 (patch)
tree571a63c62c706f4ce945a8e8335966894cb92787
parent660af10dee503729025952ed2374b8a081f941a2 (diff)
Added documentation for QSurfaceFormat.
Change-Id: I3b42b09e6e42092c098e4fc20c5ba7dd7e354116 Reviewed-by: Gunnar Sletta <gunnar.sletta@nokia.com>
-rw-r--r--src/gui/kernel/qsurfaceformat.cpp151
1 files changed, 136 insertions, 15 deletions
diff --git a/src/gui/kernel/qsurfaceformat.cpp b/src/gui/kernel/qsurfaceformat.cpp
index b97852dc1d..9021d82e20 100644
--- a/src/gui/kernel/qsurfaceformat.cpp
+++ b/src/gui/kernel/qsurfaceformat.cpp
@@ -106,10 +106,86 @@ public:
int minor;
};
+/*!
+ \class QSurfaceFormat
+ \brief The QSurfaceFormat class represents the format of a QSurface.
+
+ The format includes the size of the color buffers, red, green, and blue;
+ the size of the alpha buffer; the size of the depth and stencil buffers;
+ and number of samples per pixel for multisampling. In addition, the format
+ contains surface configuration parameters such as OpenGL profile and
+ version for rendering, whether or not enable stereo buffers, and swap
+ behaviour.
+*/
+
+/*!
+ \enum QSurfaceFormat::FormatOption
+
+ This enum contains format options for use with QSurfaceFormat.
+
+ \value StereoBuffers Used to request stereo buffers in the surface format.
+ \value DebugContext Used to request a debug context with extra debugging information.
+ This requires OpenGL version 3.0 or higher.
+ \value DeprecatedFunctions Used to request that deprecated functions be included
+ in the OpenGL context profile. If not specified, you should get a forward compatible context
+ without support functionality marked as deprecated. This requires OpenGL version 3.0 or higher.
+*/
+
+/*!
+ \enum QSurfaceFormat::SwapBehavior
+
+ This enum is used by QSurfaceFormat to specify the swap behaviour of a surface. The swap behaviour
+ is mostly transparent to the application, but it affects factors such as rendering latency and
+ throughput.
+
+ \value DefaultSwapBehavior The default, unspecified swap behaviour of the platform.
+ \value SingleBuffer Used to request single buffering, which might result in flickering
+ when OpenGL rendering is done directly to screen without an intermediate offscreen
+ buffer.
+ \value DoubleBuffer This is typically the default swap behaviour on desktop platforms,
+ consisting of one back buffer and one front buffer. Rendering is done to the back
+ buffer, and then the back buffer and front buffer are swapped, or the contents of
+ the back buffer are copied to the front buffer, depending on the implementation.
+ \value TripleBuffer This swap behaviour is sometimes used in order to decrease the
+ risk of skipping a frame when the rendering rate is just barely keeping up with
+ the screen refresh rate. Depending on the platform it might also lead to slightly
+ more efficient use of the GPU due to improved pipelining behaviour. Triple buffering
+ comes at the cost of an extra frame of memory usage and latency, and might not be
+ supported depending on the underlying platform.
+*/
+
+/*!
+ \enum QSurfaceFormat::OpenGLContextProfile
+
+ This enum is used to specify the OpenGL context profile, in
+ conjunction with QSurfaceFormat::setMajorVersion() and
+ QSurfaceFormat::setMinorVersion().
+
+ Profiles are exposed in OpenGL 3.2 and above, and are used
+ to choose between a restricted core profile, and a compatibility
+ profile which might contain deprecated support functionality.
+
+ Note that the core profile might still contain functionality that
+ is deprecated and scheduled for removal in a higher version. To
+ get access to the deprecated functionality for the core profile
+ in the set OpenGL version you can use the QSurfaceFormat format option
+ QSurfaceFormat::DeprecatedFunctions.
+
+ \value NoProfile OpenGL version is lower than 3.2.
+ \value CoreProfile Functionality deprecated in OpenGL version 3.0 is not available.
+ \value CompatibilityProfile Functionality from earlier OpenGL versions is available.
+*/
+
+/*!
+ Constructs a default initialized QSurfaceFormat.
+*/
QSurfaceFormat::QSurfaceFormat() : d(new QSurfaceFormatPrivate)
{
}
+/*!
+ Constructs a QSurfaceFormat with the given format \a options.
+*/
QSurfaceFormat::QSurfaceFormat(QSurfaceFormat::FormatOptions options) :
d(new QSurfaceFormatPrivate(options))
{
@@ -131,7 +207,6 @@ void QSurfaceFormat::detach()
/*!
Constructs a copy of \a other.
*/
-
QSurfaceFormat::QSurfaceFormat(const QSurfaceFormat &other)
{
d = other.d;
@@ -141,7 +216,6 @@ QSurfaceFormat::QSurfaceFormat(const QSurfaceFormat &other)
/*!
Assigns \a other to this object.
*/
-
QSurfaceFormat &QSurfaceFormat::operator=(const QSurfaceFormat &other)
{
if (d != other.d) {
@@ -182,7 +256,6 @@ QSurfaceFormat::~QSurfaceFormat()
\sa stereo()
*/
-
void QSurfaceFormat::setStereo(bool enable)
{
QSurfaceFormat::FormatOptions newOptions = d->opts;
@@ -199,8 +272,7 @@ void QSurfaceFormat::setStereo(bool enable)
/*!
Returns the number of samples per pixel when multisampling is
- enabled. By default, the highest number of samples that is
- available is used.
+ enabled. By default, multisampling is disabled.
\sa setSampleBuffers(), sampleBuffers(), setSamples()
*/
@@ -211,8 +283,7 @@ int QSurfaceFormat::samples() const
/*!
Set the preferred number of samples per pixel when multisampling
- is enabled to \a numSamples. By default, the highest number of
- samples available is used.
+ is enabled to \a numSamples. By default, multisampling is disabled.
\sa setSampleBuffers(), sampleBuffers(), samples()
*/
@@ -229,7 +300,6 @@ void QSurfaceFormat::setSamples(int numSamples)
\sa testOption()
*/
-
void QSurfaceFormat::setOption(QSurfaceFormat::FormatOptions opt)
{
const QSurfaceFormat::FormatOptions newOptions = d->opts | opt;
@@ -244,7 +314,6 @@ void QSurfaceFormat::setOption(QSurfaceFormat::FormatOptions opt)
\sa setOption()
*/
-
bool QSurfaceFormat::testOption(QSurfaceFormat::FormatOptions opt) const
{
return d->opts & opt;
@@ -273,6 +342,13 @@ int QSurfaceFormat::depthBufferSize() const
return d->depthSize;
}
+/*!
+ Set the swap behaviour of the surface.
+
+ The swap behaviour specifies whether single, double, or triple
+ buffering is desired. The default, SwapBehavior::DefaultSwapBehavior,
+ gives the default swap behavior of the platform.
+*/
void QSurfaceFormat::setSwapBehavior(SwapBehavior behavior)
{
if (d->swapBehavior != behavior) {
@@ -281,19 +357,29 @@ void QSurfaceFormat::setSwapBehavior(SwapBehavior behavior)
}
}
+/*!
+ Returns the configured swap behaviour.
+ \sa setSwapBehavior()
+*/
QSurfaceFormat::SwapBehavior QSurfaceFormat::swapBehavior() const
{
return d->swapBehavior;
}
+/*!
+ Returns true if the alpha buffer size is greater than zero.
+
+ This means that the surface might be used with per pixel
+ translucency effects.
+*/
bool QSurfaceFormat::hasAlpha() const
{
return d->alphaBufferSize > 0;
}
/*!
- Set the preferred stencil buffer size to \a size.
+ Set the preferred stencil buffer size to \a size bits.
\sa stencilBufferSize(), setStencil(), stencil()
*/
@@ -306,7 +392,7 @@ void QSurfaceFormat::setStencilBufferSize(int size)
}
/*!
- Returns the stencil buffer size.
+ Returns the stencil buffer size in bits.
\sa stencil(), setStencil(), setStencilBufferSize()
*/
@@ -315,26 +401,41 @@ int QSurfaceFormat::stencilBufferSize() const
return d->stencilSize;
}
+/*!
+ Get the size in bits of the red channel of the color buffer.
+*/
int QSurfaceFormat::redBufferSize() const
{
return d->redBufferSize;
}
+/*!
+ Get the size in bits of the green channel of the color buffer.
+*/
int QSurfaceFormat::greenBufferSize() const
{
return d->greenBufferSize;
}
+/*!
+ Get the size in bits of the blue channel of the color buffer.
+*/
int QSurfaceFormat::blueBufferSize() const
{
return d->blueBufferSize;
}
+/*!
+ Get the size in bits of the alpha channel of the color buffer.
+*/
int QSurfaceFormat::alphaBufferSize() const
{
return d->alphaBufferSize;
}
+/*!
+ Set the desired size in bits of the red channel of the color buffer.
+*/
void QSurfaceFormat::setRedBufferSize(int size)
{
if (d->redBufferSize != size) {
@@ -343,6 +444,9 @@ void QSurfaceFormat::setRedBufferSize(int size)
}
}
+/*!
+ Set the desired size in bits of the green channel of the color buffer.
+*/
void QSurfaceFormat::setGreenBufferSize(int size)
{
if (d->greenBufferSize != size) {
@@ -351,6 +455,9 @@ void QSurfaceFormat::setGreenBufferSize(int size)
}
}
+/*!
+ Set the desired size in bits of the blue channel of the color buffer.
+*/
void QSurfaceFormat::setBlueBufferSize(int size)
{
if (d->blueBufferSize != size) {
@@ -359,6 +466,9 @@ void QSurfaceFormat::setBlueBufferSize(int size)
}
}
+/*!
+ Set the desired size in bits of the alpha channel of the color buffer.
+*/
void QSurfaceFormat::setAlphaBufferSize(int size)
{
if (d->alphaBufferSize != size) {
@@ -368,10 +478,10 @@ void QSurfaceFormat::setAlphaBufferSize(int size)
}
/*!
- Sets the desired OpenGL context profile.
+ Sets the desired OpenGL context profile.
- This setting is ignored if the requested OpenGL version is
- less than 3.2.
+ This setting is ignored if the requested OpenGL version is
+ less than 3.2.
*/
void QSurfaceFormat::setProfile(OpenGLContextProfile profile)
{
@@ -381,6 +491,12 @@ void QSurfaceFormat::setProfile(OpenGLContextProfile profile)
}
}
+/*!
+ Get the configured OpenGL context profile.
+
+ This setting is ignored if the requested OpenGL version is
+ less than 3.2.
+*/
QSurfaceFormat::OpenGLContextProfile QSurfaceFormat::profile() const
{
return d->profile;
@@ -428,6 +544,12 @@ int QSurfaceFormat::minorVersion() const
return d->minor;
}
+/*!
+ Returns true if all the options of the two QSurfaceFormat objects
+ are equal.
+
+ \relates QSurfaceFormat
+*/
bool operator==(const QSurfaceFormat& a, const QSurfaceFormat& b)
{
return (a.d == b.d) || ((int) a.d->opts == (int) b.d->opts
@@ -450,7 +572,6 @@ bool operator==(const QSurfaceFormat& a, const QSurfaceFormat& b)
\relates QSurfaceFormat
*/
-
bool operator!=(const QSurfaceFormat& a, const QSurfaceFormat& b)
{
return !(a == b);