Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
QSurfaceFormat Class Reference

The QSurfaceFormat class represents the format of a QSurface. \inmodule QtGui. More...

#include <qsurfaceformat.h>

+ Collaboration diagram for QSurfaceFormat:

Public Types

enum  FormatOption {
  StereoBuffers = 0x0001 , DebugContext = 0x0002 , DeprecatedFunctions = 0x0004 , ResetNotification = 0x0008 ,
  ProtectedContent = 0x0010
}
 This enum contains format options for use with QSurfaceFormat. More...
 
enum  SwapBehavior { DefaultSwapBehavior , SingleBuffer , DoubleBuffer , TripleBuffer }
 This enum is used by QSurfaceFormat to specify the swap behaviour of a surface. More...
 
enum  RenderableType { DefaultRenderableType = 0x0 , OpenGL = 0x1 , OpenGLES = 0x2 , OpenVG = 0x4 }
 This enum specifies the rendering backend for the surface. More...
 
enum  OpenGLContextProfile { NoProfile , CoreProfile , CompatibilityProfile }
 This enum is used to specify the OpenGL context profile, in conjunction with QSurfaceFormat::setMajorVersion() and QSurfaceFormat::setMinorVersion(). More...
 
enum  ColorComponentType { FixedColorComponentType , FloatColorComponentType }
 

Public Member Functions

 QSurfaceFormat ()
 Constructs a default initialized QSurfaceFormat.
 
Q_IMPLICIT QSurfaceFormat (FormatOptions options)
 
 QSurfaceFormat (const QSurfaceFormat &other)
 Constructs a copy of other.
 
QSurfaceFormatoperator= (const QSurfaceFormat &other)
 Assigns other to this object.
 
 ~QSurfaceFormat ()
 Destroys the QSurfaceFormat.
 
void setDepthBufferSize (int size)
 Set the minimum depth buffer size to size.
 
int depthBufferSize () const
 Returns the depth buffer size.
 
void setStencilBufferSize (int size)
 Set the preferred stencil buffer size to size bits.
 
int stencilBufferSize () const
 Returns the stencil buffer size in bits.
 
void setRedBufferSize (int size)
 Set the desired size in bits of the red channel of the color buffer.
 
int redBufferSize () const
 Get the size in bits of the red channel of the color buffer.
 
void setGreenBufferSize (int size)
 Set the desired size in bits of the green channel of the color buffer.
 
int greenBufferSize () const
 Get the size in bits of the green channel of the color buffer.
 
void setBlueBufferSize (int size)
 Set the desired size in bits of the blue channel of the color buffer.
 
int blueBufferSize () const
 Get the size in bits of the blue channel of the color buffer.
 
void setAlphaBufferSize (int size)
 Set the desired size in bits of the alpha channel of the color buffer.
 
int alphaBufferSize () const
 Get the size in bits of the alpha channel of the color buffer.
 
void setColorComponentType (ColorComponentType type)
 Sets the color component type.
 
ColorComponentType colorComponentType () const
 
void setSamples (int numSamples)
 Set the preferred number of samples per pixel when multisampling is enabled to numSamples.
 
int samples () const
 Returns the number of samples per pixel when multisampling is enabled, or -1 when multisampling is disabled.
 
void setSwapBehavior (SwapBehavior behavior)
 Set the swap behavior of the surface.
 
SwapBehavior swapBehavior () const
 Returns the configured swap behaviour.
 
bool hasAlpha () const
 Returns true if the alpha buffer size is greater than zero.
 
void setProfile (OpenGLContextProfile profile)
 Sets the desired OpenGL context profile.
 
OpenGLContextProfile profile () const
 Get the configured OpenGL context profile.
 
void setRenderableType (RenderableType type)
 Sets the desired renderable type.
 
RenderableType renderableType () const
 Gets the renderable type.
 
void setMajorVersion (int majorVersion)
 Sets the desired major OpenGL version.
 
int majorVersion () const
 Returns the major OpenGL version.
 
void setMinorVersion (int minorVersion)
 Sets the desired minor OpenGL version.
 
int minorVersion () const
 Returns the minor OpenGL version.
 
std::pair< int, int > version () const
 Returns a std::pair<int, int> representing the OpenGL version.
 
void setVersion (int major, int minor)
 Sets the desired major and minor OpenGL versions.
 
bool stereo () const
 Returns true if stereo buffering is enabled; otherwise returns false.
 
void setStereo (bool enable)
 If enable is true enables stereo buffering; otherwise disables stereo buffering.
 
void setOptions (QSurfaceFormat::FormatOptions options)
 
void setOption (FormatOption option, bool on=true)
 
bool testOption (FormatOption option) const
 
QSurfaceFormat::FormatOptions options () const
 
int swapInterval () const
 Returns the swap interval.
 
void setSwapInterval (int interval)
 Sets the preferred swap interval.
 
const QColorSpacecolorSpace () const
 
void setColorSpace (const QColorSpace &colorSpace)
 Sets the preferred colorSpace.
 

Static Public Member Functions

static void setDefaultFormat (const QSurfaceFormat &format)
 Sets the global default surface format.
 
static QSurfaceFormat defaultFormat ()
 Returns the global default surface format.
 

Friends

bool operator== (const QSurfaceFormat &lhs, const QSurfaceFormat &rhs) noexcept
 Returns true if all the options of the two QSurfaceFormat objects lhs and rhs are equal.
 
bool operator!= (const QSurfaceFormat &lhs, const QSurfaceFormat &rhs) noexcept
 Returns false if all the options of the two QSurfaceFormat objects lhs and rhs are equal; otherwise returns true.
 
Q_GUI_EXPORT QDebug operator<< (QDebug dbg, const QSurfaceFormat &f)
 

Detailed Description

The QSurfaceFormat class represents the format of a QSurface. \inmodule QtGui.

Since
5.0

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 to enable stereo buffers, and swap behaviour.

Note
When troubleshooting context or window format issues, it can be helpful to enable the logging category {qt.qpa.gl}. Depending on the platform, this may print useful debug information when it comes to OpenGL initialization and the native visual or framebuffer configurations which QSurfaceFormat gets mapped to.

Definition at line 15 of file qsurfaceformat.h.

Member Enumeration Documentation

◆ ColorComponentType

Enumerator
FixedColorComponentType 
FloatColorComponentType 

Definition at line 60 of file qsurfaceformat.h.

◆ 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. \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. \value ResetNotification Enables notifications about resets of the OpenGL context. The status is then queryable via the context's \l{QOpenGLContext::isValid()}{isValid()} function. Note that not setting this flag does not guarantee that context state loss never occurs. Additionally, some implementations may choose to report context loss regardless of this flag. Platforms that support dynamically enabling the monitoring of the loss of context, such as, Windows with WGL, or Linux/X11 (xcb) with GLX, will monitor the status in every call to \l{QOpenGLContext::makeCurrent()}{makeCurrent()}. See \l{QOpenGLContext::isValid()}{isValid()} for more information on this. \value ProtectedContent Enables access to protected content. This allows the GPU to operate on protected resources (surfaces, buffers, textures), for example DRM-protected video content. Currently only implemented for EGL.

Enumerator
StereoBuffers 
DebugContext 
DeprecatedFunctions 
ResetNotification 
ProtectedContent 

Definition at line 19 of file qsurfaceformat.h.

◆ 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. For 3.2 and newer this is same as CoreProfile. \value CoreProfile Functionality deprecated in OpenGL version 3.0 is not available. \value CompatibilityProfile Functionality from earlier OpenGL versions is available.

Enumerator
NoProfile 
CoreProfile 
CompatibilityProfile 

Definition at line 45 of file qsurfaceformat.h.

◆ RenderableType

This enum specifies the rendering backend for the surface.

\value DefaultRenderableType The default, unspecified rendering method \value OpenGL Desktop OpenGL rendering \value OpenGLES OpenGL ES 2.0 rendering \value OpenVG Open Vector Graphics rendering

Enumerator
DefaultRenderableType 
OpenGL 
OpenGLES 
OpenVG 

Definition at line 37 of file qsurfaceformat.h.

◆ 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.

Enumerator
DefaultSwapBehavior 
SingleBuffer 
DoubleBuffer 
TripleBuffer 

Definition at line 29 of file qsurfaceformat.h.

Constructor & Destructor Documentation

◆ QSurfaceFormat() [1/3]

QSurfaceFormat::QSurfaceFormat ( )

Constructs a default initialized QSurfaceFormat.

Note
By default OpenGL 2.0 is requested since this provides the highest grade of portability between platforms and OpenGL implementations.

Definition at line 206 of file qsurfaceformat.cpp.

◆ QSurfaceFormat() [2/3]

Q_IMPLICIT QSurfaceFormat::QSurfaceFormat ( FormatOptions options)

◆ QSurfaceFormat() [3/3]

QSurfaceFormat::QSurfaceFormat ( const QSurfaceFormat & other)

Constructs a copy of other.

Definition at line 234 of file qsurfaceformat.cpp.

◆ ~QSurfaceFormat()

QSurfaceFormat::~QSurfaceFormat ( )

Destroys the QSurfaceFormat.

Definition at line 257 of file qsurfaceformat.cpp.

Member Function Documentation

◆ alphaBufferSize()

int QSurfaceFormat::alphaBufferSize ( ) const

Get the size in bits of the alpha channel of the color buffer.

Definition at line 492 of file qsurfaceformat.cpp.

◆ blueBufferSize()

int QSurfaceFormat::blueBufferSize ( ) const

Get the size in bits of the blue channel of the color buffer.

Definition at line 484 of file qsurfaceformat.cpp.

◆ colorComponentType()

QSurfaceFormat::ColorComponentType QSurfaceFormat::colorComponentType ( ) const
Returns
the color component type.
Since
6.10
See also
setColorComponentType()

Definition at line 570 of file qsurfaceformat.cpp.

◆ colorSpace()

const QColorSpace & QSurfaceFormat::colorSpace ( ) const
Returns
the color space.
Since
5.10
See also
setColorSpace()

Definition at line 789 of file qsurfaceformat.cpp.

◆ defaultFormat()

QSurfaceFormat QSurfaceFormat::defaultFormat ( )
static

Returns the global default surface format.

When setDefaultFormat() is not called, this is a default-constructed QSurfaceFormat.

Since
5.4
See also
setDefaultFormat()

Definition at line 842 of file qsurfaceformat.cpp.

◆ depthBufferSize()

int QSurfaceFormat::depthBufferSize ( ) const

Returns the depth buffer size.

See also
setDepthBufferSize()

Definition at line 401 of file qsurfaceformat.cpp.

◆ greenBufferSize()

int QSurfaceFormat::greenBufferSize ( ) const

Get the size in bits of the green channel of the color buffer.

Definition at line 476 of file qsurfaceformat.cpp.

◆ hasAlpha()

bool QSurfaceFormat::hasAlpha ( ) const

Returns true if the alpha buffer size is greater than zero.

This means that the surface might be used with per pixel translucency effects.

Definition at line 437 of file qsurfaceformat.cpp.

◆ majorVersion()

int QSurfaceFormat::majorVersion ( ) const

Returns the major OpenGL version.

The default version is 2.0.

Definition at line 639 of file qsurfaceformat.cpp.

◆ minorVersion()

int QSurfaceFormat::minorVersion ( ) const

Returns the minor OpenGL version.

Definition at line 660 of file qsurfaceformat.cpp.

◆ operator=()

QSurfaceFormat & QSurfaceFormat::operator= ( const QSurfaceFormat & other)

Assigns other to this object.

Definition at line 243 of file qsurfaceformat.cpp.

◆ options()

QSurfaceFormat::FormatOptions QSurfaceFormat::options ( ) const
Since
5.3

Returns the currently set format options.

See also
setOption(), setOptions(), testOption()

Definition at line 378 of file qsurfaceformat.cpp.

Referenced by testing.tools.test_runner._TestCaseRunner::_NewImageArtifact(), testing.tools.test_runner._TestCaseRunner::_RegenerateIfNeeded(), testing.tools.test_runner.TestRunner::IsSkiaGoldEnabled(), testing.tools.test_runner._TestCaseRunner::TestPixel(), and testing.tools.test_runner._TestCaseRunner::TestText().

+ Here is the caller graph for this function:

◆ profile()

QSurfaceFormat::OpenGLContextProfile QSurfaceFormat::profile ( ) const

Get the configured OpenGL context profile.

This setting is ignored if the requested OpenGL version is less than 3.2.

Definition at line 618 of file qsurfaceformat.cpp.

◆ redBufferSize()

int QSurfaceFormat::redBufferSize ( ) const

Get the size in bits of the red channel of the color buffer.

Definition at line 468 of file qsurfaceformat.cpp.

◆ renderableType()

QSurfaceFormat::RenderableType QSurfaceFormat::renderableType ( ) const

Gets the renderable type.

Chooses between desktop OpenGL, OpenGL ES, and OpenVG.

Definition at line 593 of file qsurfaceformat.cpp.

◆ samples()

int QSurfaceFormat::samples ( ) const

Returns the number of samples per pixel when multisampling is enabled, or -1 when multisampling is disabled.

The default return value is -1.

See also
setSamples()

Definition at line 301 of file qsurfaceformat.cpp.

◆ setAlphaBufferSize()

void QSurfaceFormat::setAlphaBufferSize ( int size)

Set the desired size in bits of the alpha channel of the color buffer.

Definition at line 533 of file qsurfaceformat.cpp.

◆ setBlueBufferSize()

void QSurfaceFormat::setBlueBufferSize ( int size)

Set the desired size in bits of the blue channel of the color buffer.

Definition at line 522 of file qsurfaceformat.cpp.

◆ setColorComponentType()

void QSurfaceFormat::setColorComponentType ( ColorComponentType type)

Sets the color component type.

The default is FixedColorComponentType. To request a floating-point color buffer, set FloatColorComponentType. The red, green, and blue buffer sizes should then be set either to 16 or 32, to specify either half (16-bit) floating point components or 32-bit. The most commonly supported and used choice is the former (16-bit), for example when high dynamic range rendering is desired.

Since
6.10
See also
colorComponentType()

Definition at line 555 of file qsurfaceformat.cpp.

◆ setColorSpace()

void QSurfaceFormat::setColorSpace ( const QColorSpace & colorSpace)

Sets the preferred colorSpace.

For example, this allows requesting windows with default framebuffers that are sRGB-capable on platforms that support it.

Note
When the requested color space is not supported by the platform, the request is ignored. Query the QSurfaceFormat after window creation to verify if the color space request could be honored or not.
This setting controls if the default framebuffer of the window is capable of updates and blending in a given color space. It does not change applications' output by itself. The applications' rendering code will still have to opt in via the appropriate OpenGL calls to enable updates and blending to be performed in the given color space instead of using the standard linear operations.
Since
6.0
See also
colorSpace()

Definition at line 750 of file qsurfaceformat.cpp.

◆ setDefaultFormat()

void QSurfaceFormat::setDefaultFormat ( const QSurfaceFormat & format)
static

Sets the global default surface format.

This format is used by default in QOpenGLContext, QWindow, QOpenGLWidget and similar classes.

It can always be overridden on a per-instance basis by using the class in question's own setFormat() function. However, it is often more convenient to set the format for all windows once at the start of the application. It also guarantees proper behavior in cases where shared contexts are required, because setting the format via this function guarantees that all contexts and surfaces, even the ones created internally by Qt, will use the same format.

Note
When setting Qt::AA_ShareOpenGLContexts, it is strongly recommended to place the call to this function before the construction of the QGuiApplication or QApplication. Otherwise format will not be applied to the global share context and therefore issues may arise with context sharing afterwards.
Since
5.4
See also
defaultFormat()

Definition at line 819 of file qsurfaceformat.cpp.

◆ setDepthBufferSize()

void QSurfaceFormat::setDepthBufferSize ( int size)

Set the minimum depth buffer size to size.

See also
depthBufferSize()

Definition at line 388 of file qsurfaceformat.cpp.

◆ setGreenBufferSize()

void QSurfaceFormat::setGreenBufferSize ( int size)

Set the desired size in bits of the green channel of the color buffer.

Definition at line 511 of file qsurfaceformat.cpp.

◆ setMajorVersion()

void QSurfaceFormat::setMajorVersion ( int majorVersion)

Sets the desired major OpenGL version.

Definition at line 626 of file qsurfaceformat.cpp.

◆ setMinorVersion()

void QSurfaceFormat::setMinorVersion ( int minor)

Sets the desired minor OpenGL version.

The default version is 2.0.

Definition at line 649 of file qsurfaceformat.cpp.

◆ setOption()

void QSurfaceFormat::setOption ( QSurfaceFormat::FormatOption option,
bool on = true )
Since
5.3

Sets the format option option if on is true; otherwise, clears the option.

To verify that an option was respected, compare the actual format to the requested format after surface/context creation.

See also
setOptions(), options(), testOption()

Definition at line 348 of file qsurfaceformat.cpp.

◆ setOptions()

void QSurfaceFormat::setOptions ( QSurfaceFormat::FormatOptions options)
Since
5.3

Sets the format options to options.

To verify that an option was respected, compare the actual format to the requested format after surface/context creation.

See also
options(), testOption()

Definition at line 330 of file qsurfaceformat.cpp.

◆ setProfile()

void QSurfaceFormat::setProfile ( OpenGLContextProfile profile)

Sets the desired OpenGL context profile.

This setting is ignored if the requested OpenGL version is less than 3.2.

Definition at line 604 of file qsurfaceformat.cpp.

◆ setRedBufferSize()

void QSurfaceFormat::setRedBufferSize ( int size)

Set the desired size in bits of the red channel of the color buffer.

Definition at line 500 of file qsurfaceformat.cpp.

◆ setRenderableType()

void QSurfaceFormat::setRenderableType ( RenderableType type)

Sets the desired renderable type.

Chooses between desktop OpenGL, OpenGL ES, and OpenVG.

Definition at line 580 of file qsurfaceformat.cpp.

◆ setSamples()

void QSurfaceFormat::setSamples ( int numSamples)

Set the preferred number of samples per pixel when multisampling is enabled to numSamples.

By default, multisampling is disabled.

See also
samples()

Definition at line 312 of file qsurfaceformat.cpp.

◆ setStencilBufferSize()

void QSurfaceFormat::setStencilBufferSize ( int size)

Set the preferred stencil buffer size to size bits.

See also
stencilBufferSize()

Definition at line 447 of file qsurfaceformat.cpp.

◆ setStereo()

void QSurfaceFormat::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.

See also
stereo()

Definition at line 283 of file qsurfaceformat.cpp.

◆ setSwapBehavior()

void QSurfaceFormat::setSwapBehavior ( SwapBehavior behavior)

Set the swap behavior of the surface.

The swap behavior specifies whether single, double, or triple buffering is desired. The default, DefaultSwapBehavior, gives the default swap behavior of the platform.

Definition at line 413 of file qsurfaceformat.cpp.

◆ setSwapInterval()

void QSurfaceFormat::setSwapInterval ( int interval)

Sets the preferred swap interval.

The swap interval specifies the minimum number of video frames that are displayed before a buffer swap occurs. This can be used to sync the GL drawing into a window to the vertical refresh of the screen.

Setting an interval value of 0 will turn the vertical refresh syncing off, any value higher than 0 will turn the vertical syncing on. Setting interval to a higher value, for example 10, results in having 10 vertical retraces between every buffer swap.

The default interval is 1.

Changing the swap interval may not be supported by the underlying platform. In this case, the request will be silently ignored.

Since
5.3
See also
swapInterval()

Definition at line 709 of file qsurfaceformat.cpp.

◆ setVersion()

void QSurfaceFormat::setVersion ( int major,
int minor )

Sets the desired major and minor OpenGL versions.

The default version is 2.0.

Definition at line 680 of file qsurfaceformat.cpp.

◆ stencilBufferSize()

int QSurfaceFormat::stencilBufferSize ( ) const

Returns the stencil buffer size in bits.

See also
setStencilBufferSize()

Definition at line 460 of file qsurfaceformat.cpp.

◆ stereo()

bool QSurfaceFormat::stereo ( ) const
inline

Returns true if stereo buffering is enabled; otherwise returns false.

Stereo buffering is disabled by default.

See also
setStereo()

Definition at line 155 of file qsurfaceformat.h.

◆ swapBehavior()

QSurfaceFormat::SwapBehavior QSurfaceFormat::swapBehavior ( ) const

Returns the configured swap behaviour.

See also
setSwapBehavior()

Definition at line 426 of file qsurfaceformat.cpp.

◆ swapInterval()

int QSurfaceFormat::swapInterval ( ) const

Returns the swap interval.

Since
5.3
See also
setSwapInterval()

Definition at line 724 of file qsurfaceformat.cpp.

◆ testOption()

bool QSurfaceFormat::testOption ( QSurfaceFormat::FormatOption option) const
Since
5.3

Returns true if the format option option is set; otherwise returns false.

See also
options()

Definition at line 366 of file qsurfaceformat.cpp.

◆ version()

std::pair< int, int > QSurfaceFormat::version ( ) const

Returns a std::pair<int, int> representing the OpenGL version.

Useful for version checks, for example format.version() >= std::pair(3, 2)

Definition at line 670 of file qsurfaceformat.cpp.

Friends And Related Symbol Documentation

◆ operator!=

bool operator!= ( const QSurfaceFormat & lhs,
const QSurfaceFormat & rhs )
friend

Returns false if all the options of the two QSurfaceFormat objects lhs and rhs are equal; otherwise returns true.

Definition at line 142 of file qsurfaceformat.h.

◆ operator<<

◆ operator==

bool operator== ( const QSurfaceFormat & lhs,
const QSurfaceFormat & rhs )
friend

Returns true if all the options of the two QSurfaceFormat objects lhs and rhs are equal.

Definition at line 140 of file qsurfaceformat.h.


The documentation for this class was generated from the following files: