class QSurfaceFormat#

The QSurfaceFormat class represents the format of a QSurface . More…

Synopsis#

Methods#

def __init__()
def alphaBufferSize()
def blueBufferSize()
def colorSpace()
def depthBufferSize()
def greenBufferSize()
def hasAlpha()
def majorVersion()
def minorVersion()
def __ne__()
def __eq__()
def options()
def profile()
def redBufferSize()
def renderableType()
def samples()
def setAlphaBufferSize()
def setBlueBufferSize()
def setColorSpace()
def setDepthBufferSize()
def setGreenBufferSize()
def setMajorVersion()
def setMinorVersion()
def setOption()
def setOptions()
def setProfile()
def setRedBufferSize()
def setRenderableType()
def setSamples()
def setStencilBufferSize()
def setStereo()
def setSwapBehavior()
def setSwapInterval()
def setVersion()
def stencilBufferSize()
def stereo()
def swapBehavior()
def swapInterval()
def testOption()
def version()

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

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.

class FormatOption#

(inherits enum.Flag) This enum contains format options for use with QSurfaceFormat .

Constant

Description

QSurfaceFormat.StereoBuffers

Used to request stereo buffers in the surface format.

QSurfaceFormat.DebugContext

Used to request a debug context with extra debugging information.

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

QSurfaceFormat.ResetNotification

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.

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

Constant	Description
QSurfaceFormat.StereoBuffers	Used to request stereo buffers in the surface format.
QSurfaceFormat.DebugContext	Used to request a debug context with extra debugging information.
QSurfaceFormat.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.
QSurfaceFormat.ResetNotification	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.
QSurfaceFormat.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.

class 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

Description

QSurfaceFormat.DefaultSwapBehavior

The default, unspecified swap behaviour of the platform.

QSurfaceFormat.SingleBuffer

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

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

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.

Constant	Description
QSurfaceFormat.DefaultSwapBehavior	The default, unspecified swap behaviour of the platform.
QSurfaceFormat.SingleBuffer	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	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	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.

class RenderableType#

This enum specifies the rendering backend for the surface.

Constant

Description

QSurfaceFormat.DefaultRenderableType

The default, unspecified rendering method

QSurfaceFormat.OpenGL

Desktop OpenGL rendering

QSurfaceFormat.OpenGLES

OpenGL ES 2.0 rendering

QSurfaceFormat.OpenVG

Open Vector Graphics rendering

Constant	Description
QSurfaceFormat.DefaultRenderableType	The default, unspecified rendering method
QSurfaceFormat.OpenGL	Desktop OpenGL rendering
QSurfaceFormat.OpenGLES	OpenGL ES 2.0 rendering
QSurfaceFormat.OpenVG	Open Vector Graphics rendering

class OpenGLContextProfile#

This enum is used to specify the OpenGL context profile, in conjunction with setMajorVersion() and 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 DeprecatedFunctions .

Constant

Description

QSurfaceFormat.NoProfile

OpenGL version is lower than 3.2. For 3.2 and newer this is same as CoreProfile.

QSurfaceFormat.CoreProfile

Functionality deprecated in OpenGL version 3.0 is not available.

QSurfaceFormat.CompatibilityProfile

Functionality from earlier OpenGL versions is available.

Constant	Description
QSurfaceFormat.NoProfile	OpenGL version is lower than 3.2. For 3.2 and newer this is same as CoreProfile.
QSurfaceFormat.CoreProfile	Functionality deprecated in OpenGL version 3.0 is not available.
QSurfaceFormat.CompatibilityProfile	Functionality from earlier OpenGL versions is available.

class 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

Description

QSurfaceFormat.DefaultColorSpace

The default, unspecified color space.

QSurfaceFormat.sRGBColorSpace

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.

Constant	Description
QSurfaceFormat.DefaultColorSpace	The default, unspecified color space.
QSurfaceFormat.sRGBColorSpace	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.

__init__(options)#

Parameters:: options – Combination of FormatOption

Constructs a QSurfaceFormat with the given format options.

__init__()

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.

__init__(other)

Parameters:: other – QSurfaceFormat

Constructs a copy of other.

alphaBufferSize()#

Return type:: int

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

See also

setAlphaBufferSize()

blueBufferSize()#

Return type:: int

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

See also

setBlueBufferSize()

colorSpace()#

Return type:: QColorSpace

Returns the color space.

See also

setColorSpace()

static defaultFormat()#

Return type:: QSurfaceFormat

Returns the global default surface format.

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

See also

setDefaultFormat()

depthBufferSize()#

Return type:: int

Returns the depth buffer size.

See also

setDepthBufferSize()

greenBufferSize()#

Return type:: int

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

See also

setGreenBufferSize()

hasAlpha()#

Return type:: bool

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

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

majorVersion()#

Return type:: int

Returns the major OpenGL version.

The default version is 2.0.

See also

setMajorVersion()

minorVersion()#

Return type:: int

Returns the minor OpenGL version.

See also

setMinorVersion()

__ne__(rhs)#

Parameters:: rhs – QSurfaceFormat
Return type:: bool

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

__eq__(rhs)#

Parameters:: rhs – QSurfaceFormat
Return type:: bool

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

options()#

Return type:: Combination of FormatOption

Returns the currently set format options.

See also

setOption() setOptions() testOption()

profile()#

Return type:: OpenGLContextProfile

Get the configured OpenGL context profile.

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

See also

setProfile()

redBufferSize()#

Return type:: int

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

See also

setRedBufferSize()

renderableType()#

Return type:: RenderableType

Gets the renderable type.

Chooses between desktop OpenGL, OpenGL ES, and OpenVG .

See also

setRenderableType()

samples()#

Return type:: int

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()

setAlphaBufferSize(size)#

Parameters:: size – int

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

See also

alphaBufferSize()

setBlueBufferSize(size)#

Parameters:: size – int

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

See also

blueBufferSize()

setColorSpace(colorSpace)#

Parameters:: colorSpace – QColorSpace

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.

Note

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.