QSurfaceFormat Class
The QSurfaceFormat class represents the format of a QSurface. More...
| Header: | #include <QSurfaceFormat> |
| qmake: | QT += gui |
| Since: | Qt 5.0 |
This class was introduced in Qt 5.0.
Public Types
| enum | ColorSpace { DefaultColorSpace, sRGBColorSpace } |
| enum | FormatOption { StereoBuffers, DebugContext, DeprecatedFunctions, ResetNotification } |
| enum | OpenGLContextProfile { NoProfile, CoreProfile, CompatibilityProfile } |
| enum | RenderableType { DefaultRenderableType, OpenGL, OpenGLES, OpenVG } |
| enum | SwapBehavior { DefaultSwapBehavior, SingleBuffer, DoubleBuffer, TripleBuffer } |
Detailed Description
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.
Member Type Documentation
enum QSurfaceFormat::ColorSpace
This enum is used to specify the preferred color space, controlling if the window's associated default framebuffer is able to do updates and blending in a given encoding instead of the standard linear operations.
| Constant | Value | Description |
|---|---|---|
QSurfaceFormat::DefaultColorSpace | 0 | The default, unspecified color space. |
QSurfaceFormat::sRGBColorSpace | 1 | When GL_ARB_framebuffer_sRGB or GL_EXT_framebuffer_sRGB is supported by the platform and this value is set, the window will be created with an sRGB-capable default framebuffer. Note that some platforms may return windows with a sRGB-capable default framebuffer even when not requested explicitly. |
enum QSurfaceFormat::FormatOption
This enum contains format options for use with QSurfaceFormat.
| Constant | Value | Description |
|---|---|---|
QSurfaceFormat::StereoBuffers | 0x0001 | Used to request stereo buffers in the surface format. |
QSurfaceFormat::DebugContext | 0x0002 | Used to request a debug context with extra debugging information. |
QSurfaceFormat::DeprecatedFunctions | 0x0004 | 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. |
QSurfaceFormat::ResetNotification | 0x0008 | Enables notifications about resets of the OpenGL context. The status is then queryable via the context's 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 makeCurrent(). See isValid() for more information on this. |
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.
| Constant | Value | Description |
|---|---|---|
QSurfaceFormat::NoProfile | 0 | OpenGL version is lower than 3.2. For 3.2 and newer this is same as CoreProfile. |
QSurfaceFormat::CoreProfile | 1 | Functionality deprecated in OpenGL version 3.0 is not available. |
QSurfaceFormat::CompatibilityProfile | 2 | Functionality from earlier OpenGL versions is available. |
enum QSurfaceFormat::RenderableType
This enum specifies the rendering backend for the surface.
| Constant | Value | Description |
|---|---|---|
QSurfaceFormat::DefaultRenderableType | 0x0 | The default, unspecified rendering method |
QSurfaceFormat::OpenGL | 0x1 | Desktop OpenGL rendering |
QSurfaceFormat::OpenGLES | 0x2 | OpenGL ES 2.0 rendering |
QSurfaceFormat::OpenVG | 0x4 | Open Vector Graphics rendering |
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.
| Constant | Value | Description |
|---|---|---|
QSurfaceFormat::DefaultSwapBehavior | 0 | The default, unspecified swap behaviour of the platform. |
QSurfaceFormat::SingleBuffer | 1 | Used to request single buffering, which might result in flickering when OpenGL rendering is done directly to screen without an intermediate offscreen buffer. |
QSurfaceFormat::DoubleBuffer | 2 | 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. |
QSurfaceFormat::TripleBuffer | 3 | 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. |