1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the QtGui module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** GNU Lesser General Public License Usage
10 ** This file may be used under the terms of the GNU Lesser General Public
11 ** License version 2.1 as published by the Free Software Foundation and
12 ** appearing in the file LICENSE.LGPL included in the packaging of this
13 ** file. Please review the following information to ensure the GNU Lesser
14 ** General Public License version 2.1 requirements will be met:
15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
17 ** In addition, as a special exception, Nokia gives you certain additional
18 ** rights. These rights are described in the Nokia Qt LGPL Exception
19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
21 ** GNU General Public License Usage
22 ** Alternatively, this file may be used under the terms of the GNU General
23 ** Public License version 3.0 as published by the Free Software Foundation
24 ** and appearing in the file LICENSE.GPL included in the packaging of this
25 ** file. Please review the following information to ensure the GNU General
26 ** Public License version 3.0 requirements will be met:
27 ** http://www.gnu.org/copyleft/gpl.html.
30 ** Alternatively, this file may be used in accordance with the terms and
31 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
42 #include "qsurfaceformat.h"
44 #include <QtCore/qatomic.h>
45 #include <QtCore/QDebug>
57 class QSurfaceFormatPrivate
60 explicit QSurfaceFormatPrivate(QSurfaceFormat::FormatOptions _opts = 0)
69 , swapBehavior(QSurfaceFormat::DefaultSwapBehavior)
71 , renderableType(QSurfaceFormat::DefaultRenderableType)
72 , profile(QSurfaceFormat::NoProfile)
78 QSurfaceFormatPrivate(const QSurfaceFormatPrivate *other)
81 redBufferSize(other->redBufferSize),
82 greenBufferSize(other->greenBufferSize),
83 blueBufferSize(other->blueBufferSize),
84 alphaBufferSize(other->alphaBufferSize),
85 depthSize(other->depthSize),
86 stencilSize(other->stencilSize),
87 swapBehavior(other->swapBehavior),
88 numSamples(other->numSamples),
89 renderableType(other->renderableType),
90 profile(other->profile),
97 QSurfaceFormat::FormatOptions opts;
104 QSurfaceFormat::SwapBehavior swapBehavior;
106 QSurfaceFormat::RenderableType renderableType;
107 QSurfaceFormat::OpenGLContextProfile profile;
113 \class QSurfaceFormat
115 \brief The QSurfaceFormat class represents the format of a QSurface.
117 The format includes the size of the color buffers, red, green, and blue;
118 the size of the alpha buffer; the size of the depth and stencil buffers;
119 and number of samples per pixel for multisampling. In addition, the format
120 contains surface configuration parameters such as OpenGL profile and
121 version for rendering, whether or not enable stereo buffers, and swap
126 \enum QSurfaceFormat::FormatOption
128 This enum contains format options for use with QSurfaceFormat.
130 \value StereoBuffers Used to request stereo buffers in the surface format.
131 \value DebugContext Used to request a debug context with extra debugging information.
132 This requires OpenGL version 3.0 or higher.
133 \value DeprecatedFunctions Used to request that deprecated functions be included
134 in the OpenGL context profile. If not specified, you should get a forward compatible context
135 without support functionality marked as deprecated. This requires OpenGL version 3.0 or higher.
139 \enum QSurfaceFormat::SwapBehavior
141 This enum is used by QSurfaceFormat to specify the swap behaviour of a surface. The swap behaviour
142 is mostly transparent to the application, but it affects factors such as rendering latency and
145 \value DefaultSwapBehavior The default, unspecified swap behaviour of the platform.
146 \value SingleBuffer Used to request single buffering, which might result in flickering
147 when OpenGL rendering is done directly to screen without an intermediate offscreen
149 \value DoubleBuffer This is typically the default swap behaviour on desktop platforms,
150 consisting of one back buffer and one front buffer. Rendering is done to the back
151 buffer, and then the back buffer and front buffer are swapped, or the contents of
152 the back buffer are copied to the front buffer, depending on the implementation.
153 \value TripleBuffer This swap behaviour is sometimes used in order to decrease the
154 risk of skipping a frame when the rendering rate is just barely keeping up with
155 the screen refresh rate. Depending on the platform it might also lead to slightly
156 more efficient use of the GPU due to improved pipelining behaviour. Triple buffering
157 comes at the cost of an extra frame of memory usage and latency, and might not be
158 supported depending on the underlying platform.
162 \enum QSurfaceFormat::OpenGLContextProfile
164 This enum is used to specify the OpenGL context profile, in
165 conjunction with QSurfaceFormat::setMajorVersion() and
166 QSurfaceFormat::setMinorVersion().
168 Profiles are exposed in OpenGL 3.2 and above, and are used
169 to choose between a restricted core profile, and a compatibility
170 profile which might contain deprecated support functionality.
172 Note that the core profile might still contain functionality that
173 is deprecated and scheduled for removal in a higher version. To
174 get access to the deprecated functionality for the core profile
175 in the set OpenGL version you can use the QSurfaceFormat format option
176 QSurfaceFormat::DeprecatedFunctions.
178 \value NoProfile OpenGL version is lower than 3.2.
179 \value CoreProfile Functionality deprecated in OpenGL version 3.0 is not available.
180 \value CompatibilityProfile Functionality from earlier OpenGL versions is available.
184 Constructs a default initialized QSurfaceFormat.
186 QSurfaceFormat::QSurfaceFormat() : d(new QSurfaceFormatPrivate)
191 Constructs a QSurfaceFormat with the given format \a options.
193 QSurfaceFormat::QSurfaceFormat(QSurfaceFormat::FormatOptions options) :
194 d(new QSurfaceFormatPrivate(options))
201 void QSurfaceFormat::detach()
203 if (d->ref.load() != 1) {
204 QSurfaceFormatPrivate *newd = new QSurfaceFormatPrivate(d);
212 Constructs a copy of \a other.
214 QSurfaceFormat::QSurfaceFormat(const QSurfaceFormat &other)
221 Assigns \a other to this object.
223 QSurfaceFormat &QSurfaceFormat::operator=(const QSurfaceFormat &other)
235 Destroys the QSurfaceFormat.
237 QSurfaceFormat::~QSurfaceFormat()
244 \fn bool QSurfaceFormat::stereo() const
246 Returns true if stereo buffering is enabled; otherwise returns
247 false. Stereo buffering is disabled by default.
253 If \a enable is true enables stereo buffering; otherwise disables
256 Stereo buffering is disabled by default.
258 Stereo buffering provides extra color buffers to generate left-eye
259 and right-eye images.
263 void QSurfaceFormat::setStereo(bool enable)
265 QSurfaceFormat::FormatOptions newOptions = d->opts;
267 newOptions |= QSurfaceFormat::StereoBuffers;
269 newOptions &= ~QSurfaceFormat::StereoBuffers;
271 if (int(newOptions) != int(d->opts)) {
273 d->opts = newOptions;
278 Returns the number of samples per pixel when multisampling is
279 enabled. By default, multisampling is disabled.
281 \sa setSampleBuffers(), sampleBuffers(), setSamples()
283 int QSurfaceFormat::samples() const
285 return d->numSamples;
289 Set the preferred number of samples per pixel when multisampling
290 is enabled to \a numSamples. By default, multisampling is disabled.
292 \sa setSampleBuffers(), sampleBuffers(), samples()
294 void QSurfaceFormat::setSamples(int numSamples)
296 if (d->numSamples != numSamples) {
298 d->numSamples = numSamples;
303 Sets the format option to \a opt.
307 void QSurfaceFormat::setOption(QSurfaceFormat::FormatOptions opt)
309 const QSurfaceFormat::FormatOptions newOptions = d->opts | opt;
310 if (int(newOptions) != int(d->opts)) {
312 d->opts = newOptions;
317 Returns true if format option \a opt is set; otherwise returns false.
321 bool QSurfaceFormat::testOption(QSurfaceFormat::FormatOptions opt) const
323 return d->opts & opt;
327 Set the minimum depth buffer size to \a size.
329 \sa depthBufferSize(), setDepth(), depth()
331 void QSurfaceFormat::setDepthBufferSize(int size)
333 if (d->depthSize != size) {
340 Returns the depth buffer size.
342 \sa depth(), setDepth(), setDepthBufferSize()
344 int QSurfaceFormat::depthBufferSize() const
350 Set the swap behaviour of the surface.
352 The swap behaviour specifies whether single, double, or triple
353 buffering is desired. The default, SwapBehavior::DefaultSwapBehavior,
354 gives the default swap behavior of the platform.
356 void QSurfaceFormat::setSwapBehavior(SwapBehavior behavior)
358 if (d->swapBehavior != behavior) {
360 d->swapBehavior = behavior;
365 Returns the configured swap behaviour.
367 \sa setSwapBehavior()
369 QSurfaceFormat::SwapBehavior QSurfaceFormat::swapBehavior() const
371 return d->swapBehavior;
375 Returns true if the alpha buffer size is greater than zero.
377 This means that the surface might be used with per pixel
378 translucency effects.
380 bool QSurfaceFormat::hasAlpha() const
382 return d->alphaBufferSize > 0;
386 Set the preferred stencil buffer size to \a size bits.
388 \sa stencilBufferSize(), setStencil(), stencil()
390 void QSurfaceFormat::setStencilBufferSize(int size)
392 if (d->stencilSize != size) {
394 d->stencilSize = size;
399 Returns the stencil buffer size in bits.
401 \sa stencil(), setStencil(), setStencilBufferSize()
403 int QSurfaceFormat::stencilBufferSize() const
405 return d->stencilSize;
409 Get the size in bits of the red channel of the color buffer.
411 int QSurfaceFormat::redBufferSize() const
413 return d->redBufferSize;
417 Get the size in bits of the green channel of the color buffer.
419 int QSurfaceFormat::greenBufferSize() const
421 return d->greenBufferSize;
425 Get the size in bits of the blue channel of the color buffer.
427 int QSurfaceFormat::blueBufferSize() const
429 return d->blueBufferSize;
433 Get the size in bits of the alpha channel of the color buffer.
435 int QSurfaceFormat::alphaBufferSize() const
437 return d->alphaBufferSize;
441 Set the desired size in bits of the red channel of the color buffer.
443 void QSurfaceFormat::setRedBufferSize(int size)
445 if (d->redBufferSize != size) {
447 d->redBufferSize = size;
452 Set the desired size in bits of the green channel of the color buffer.
454 void QSurfaceFormat::setGreenBufferSize(int size)
456 if (d->greenBufferSize != size) {
458 d->greenBufferSize = size;
463 Set the desired size in bits of the blue channel of the color buffer.
465 void QSurfaceFormat::setBlueBufferSize(int size)
467 if (d->blueBufferSize != size) {
469 d->blueBufferSize = size;
474 Set the desired size in bits of the alpha channel of the color buffer.
476 void QSurfaceFormat::setAlphaBufferSize(int size)
478 if (d->alphaBufferSize != size) {
480 d->alphaBufferSize = size;
485 Sets the desired renderable type.
487 Chooses between desktop OpenGL, OpenGL ES, and OpenVG.
489 void QSurfaceFormat::setRenderableType(RenderableType type)
491 if (d->renderableType != type) {
493 d->renderableType = type;
498 Gets the renderable type.
500 Chooses between desktop OpenGL, OpenGL ES, and OpenVG.
502 QSurfaceFormat::RenderableType QSurfaceFormat::renderableType() const
504 return d->renderableType;
508 Sets the desired OpenGL context profile.
510 This setting is ignored if the requested OpenGL version is
513 void QSurfaceFormat::setProfile(OpenGLContextProfile profile)
515 if (d->profile != profile) {
517 d->profile = profile;
522 Get the configured OpenGL context profile.
524 This setting is ignored if the requested OpenGL version is
527 QSurfaceFormat::OpenGLContextProfile QSurfaceFormat::profile() const
533 Sets the desired major OpenGL version.
535 void QSurfaceFormat::setMajorVersion(int major)
537 if (d->major != major) {
544 Returns the major OpenGL version.
546 The default version is 2.0.
548 int QSurfaceFormat::majorVersion() const
554 Sets the desired minor OpenGL version.
556 The default version is 2.0.
558 void QSurfaceFormat::setMinorVersion(int minor)
560 if (d->minor != minor) {
567 Returns the minor OpenGL version.
569 int QSurfaceFormat::minorVersion() const
575 Returns true if all the options of the two QSurfaceFormat objects
578 \relates QSurfaceFormat
580 bool operator==(const QSurfaceFormat& a, const QSurfaceFormat& b)
582 return (a.d == b.d) || ((int) a.d->opts == (int) b.d->opts
583 && a.d->stencilSize == b.d->stencilSize
584 && a.d->redBufferSize == b.d->redBufferSize
585 && a.d->greenBufferSize == b.d->greenBufferSize
586 && a.d->blueBufferSize == b.d->blueBufferSize
587 && a.d->alphaBufferSize == b.d->alphaBufferSize
588 && a.d->depthSize == b.d->depthSize
589 && a.d->numSamples == b.d->numSamples
590 && a.d->swapBehavior == b.d->swapBehavior
591 && a.d->profile == b.d->profile
592 && a.d->major == b.d->major
593 && a.d->minor == b.d->minor);
597 Returns false if all the options of the two QSurfaceFormat objects
598 \a a and \a b are equal; otherwise returns true.
600 \relates QSurfaceFormat
602 bool operator!=(const QSurfaceFormat& a, const QSurfaceFormat& b)
607 #ifndef QT_NO_DEBUG_STREAM
608 QDebug operator<<(QDebug dbg, const QSurfaceFormat &f)
610 const QSurfaceFormatPrivate * const d = f.d;
612 dbg.nospace() << "QSurfaceFormat("
613 << "version " << d->major << '.' << d->minor
614 << ", options " << d->opts
615 << ", depthBufferSize " << d->depthSize
616 << ", redBufferSize " << d->redBufferSize
617 << ", greenBufferSize " << d->greenBufferSize
618 << ", blueBufferSize " << d->blueBufferSize
619 << ", alphaBufferSize " << d->alphaBufferSize
620 << ", stencilBufferSize " << d->stencilSize
621 << ", samples " << d->numSamples
622 << ", swapBehavior " << d->swapBehavior
623 << ", profile " << d->profile