QSurfaceFormat

PyQt5.QtGui.QSurfaceFormat

Description

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

Classes

FormatOptions

Enums

ColorSpace

TODO

Member	Value	Description
DefaultColorSpace	TODO	TODO
sRGBColorSpace	TODO	TODO

---

FormatOption

This enum contains format options for use with QSurfaceFormat.

Member	Value	Description
DebugContext	0x0002	Used to request a debug context with extra debugging information.
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.
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.
StereoBuffers	0x0001	Used to request stereo buffers in the surface format.

---

OpenGLContextProfile

TODO

Member	Value	Description
CompatibilityProfile	TODO	TODO
CoreProfile	TODO	TODO
NoProfile	TODO	TODO

---

RenderableType

TODO

Member	Value	Description
DefaultRenderableType	TODO	TODO
OpenGL	TODO	TODO
OpenGLES	TODO	TODO
OpenVG	TODO	TODO

---

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.

Member	Value	Description
DefaultSwapBehavior	0	The default, unspecified swap behaviour of the platform.
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.
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.
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.

Methods

__init__()

TODO

---

__init__(Union[FormatOptions, FormatOption])

TODO

---

__init__(QSurfaceFormat)

Constructs a copy of other.

---

alphaBufferSize() → int

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

See also

setAlphaBufferSize().

---

blueBufferSize() → int

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

See also

setBlueBufferSize().

---

colorSpace() → ColorSpace

Returns the color space.

See also

setColorSpace().

---

@staticmethod
defaultFormat() → QSurfaceFormat

Returns the global default surface format.

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

See also

setDefaultFormat().

---

depthBufferSize() → int

Returns the depth buffer size.

See also

setDepthBufferSize().

---

__eq__(QSurfaceFormat) → bool

TODO

---

greenBufferSize() → int

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

See also

setGreenBufferSize().

---

hasAlpha() → 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() → int

Returns the major OpenGL version.

The default version is 2.0.

See also

setMajorVersion().

---

minorVersion() → int

Returns the minor OpenGL version.

See also

setMinorVersion().

---

__ne__(QSurfaceFormat) → bool

TODO

---

options() → FormatOptions

Returns the currently set format options.

See also

setOption(), setOptions(), testOption().

---

profile() → 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() → int

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

See also

setRedBufferSize().

---

renderableType() → RenderableType

Gets the renderable type.

Chooses between desktop OpenGL, OpenGL ES, and OpenVG.

See also

setRenderableType().

---

samples() → int

Returns the number of samples per pixel when multisampling is enabled. By default, multisampling is disabled.

See also

setSamples().

---

setAlphaBufferSize(int)

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

See also

alphaBufferSize().

---

setBlueBufferSize(int)

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

Note: On Mac OSX, be sure to set the buffer size of all color channels, otherwise this setting will have no effect. If one of the buffer sizes is not set, the current bit-depth of the screen is used.

See also

blueBufferSize().

---

setColorSpace(ColorSpace)

TODO

---

@staticmethod
setDefaultFormat(QSurfaceFormat)

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

See also

defaultFormat().

---

setDepthBufferSize(int)

Set the minimum depth buffer size to size.

See also

depthBufferSize().

---

setGreenBufferSize(int)

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

Note: On Mac OSX, be sure to set the buffer size of all color channels, otherwise this setting will have no effect. If one of the buffer sizes is not set, the current bit-depth of the screen is used.

See also

greenBufferSize().

---

setMajorVersion(int)

Sets the desired major OpenGL version.

See also

majorVersion().

---

setMinorVersion(int)

Sets the desired minor OpenGL version.

The default version is 2.0.

See also

minorVersion().

---

setOption(Union[FormatOptions, FormatOption])

TODO

---

setOption(FormatOption, on: bool = True)

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

See also

setOptions(), options(), testOption().

---

setOptions(Union[FormatOptions, FormatOption])

TODO

---

setProfile(OpenGLContextProfile)

TODO

---

setRedBufferSize(int)

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

Note: On Mac OSX, be sure to set the buffer size of all color channels, otherwise this setting will have no effect. If one of the buffer sizes is not set, the current bit-depth of the screen is used.

See also

redBufferSize().

---

setRenderableType(RenderableType)

TODO

---

setSamples(int)

Set the preferred number of samples per pixel when multisampling is enabled to numSamples. By default, multisampling is disabled.

See also

samples().

---

setStencilBufferSize(int)

Set the preferred stencil buffer size to size bits.

See also

stencilBufferSize().

---

setStereo(bool)

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

---

setSwapBehavior(SwapBehavior)

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.

See also

swapBehavior().

---

setSwapInterval(int)

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.

See also

swapInterval().

---

setVersion(int, int)

Sets the desired major and minor OpenGL versions.

The default version is 2.0.

See also

version().

---

stencilBufferSize() → int

Returns the stencil buffer size in bits.

See also

setStencilBufferSize().

---

stereo() → bool

See also

setStereo().

---

swapBehavior() → SwapBehavior

Returns the configured swap behaviour.

See also

setSwapBehavior().

---

swapInterval() → int

Returns the swap interval.

See also

setSwapInterval().

---

testOption(Union[FormatOptions, FormatOption]) → bool

TODO

---

testOption(FormatOption) → bool

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

See also

options().

---

version() → Tuple[int, int]

Returns a QPair<int, int> representing the OpenGL version.

Useful for version checks, for example format. >= qMakePair(3, 2)

See also

setVersion().