Represents the format of a QSurface. More...

Public Typedefs
using	FormatOptions = QFlags< FormatOption >

Public Types
enum	FormatOption

enum	OpenGLContextProfile

enum	RenderableType

enum	SwapBehavior

Public Methods
	QSurfaceFormat (const QSurfaceFormat &other)

	QSurfaceFormat (FormatOptions options)

	~QSurfaceFormat ()

int	alphaBufferSize () const

int	blueBufferSize () const

int	depthBufferSize () const

int	greenBufferSize () const

bool	hasAlpha () const

int	majorVersion () const

int	minorVersion () const

QSurfaceFormat &	operator= (const QSurfaceFormat &other)

QSurfaceFormat::FormatOptions	options () const

OpenGLContextProfile	profile () const

int	redBufferSize () const

RenderableType	renderableType () const

int	samples () const

void	setAlphaBufferSize (int size)

void	setBlueBufferSize (int size)

void	setDepthBufferSize (int size)

void	setGreenBufferSize (int size)

void	setMajorVersion (int majorVersion)

void	setOption (FormatOption option, bool on=true)

void	setOptions (QSurfaceFormat::FormatOptions options)

void	setProfile (OpenGLContextProfile profile)

void	setRedBufferSize (int size)

void	setRenderableType (RenderableType type)

void	setSamples (int numSamples)

void	setStencilBufferSize (int size)

void	setStereo (bool enable)

void	setSwapBehavior (SwapBehavior behavior)

void	setSwapInterval (int interval)

void	setVersion (int major, int minor)

int	stencilBufferSize () const

bool	stereo () const

SwapBehavior	swapBehavior () const

int	swapInterval () const

bool	testOption (FormatOption option) const

QPair< int, int >	version () const

Static Public Methods
static QSurfaceFormat	defaultFormat ()

static void	setDefaultFormat (const QSurfaceFormat &format)

Friends
bool	operator!= (const QSurfaceFormat &a, const QSurfaceFormat &b)

bool	operator== (const QSurfaceFormat &a, const QSurfaceFormat &b)

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

Member Typedef Documentation

QSurfaceFormat::FormatOptions

Typedef for QFlags<FormatOption> which contains an OR combination of FormatOption values.

Refer to QSurfaceFormat::FormatOption for the enum documentation.

Member Enumeration Documentation

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 a feature added in OpenGL 3.2 and used in all newer versions. They are used to choose between a restricted core profile and a compatibility profile, which might contain deprecated functionality. For access to the deprecated functionality in the core profile use the QSurfaceFormat format option QSurfaceFormat::DeprecatedFunctions.

Constant	Value	Description
`QSurfaceFormat::NoProfile`	`0`	OpenGL version is lower than 3.2. For version 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`	Default, unspecified rendering method
`QSurfaceFormat::OpenGL`	`0x1`	Desktop OpenGL rendering
`QSurfaceFormat::OpenGLES`	`0x2`	OpenGL ES 2.0 rendering

enum QSurfaceFormat::SwapBehavior

This enum is used by QSurfaceFormat to specify the swap behavior of a surface. The swap behavior 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 behavior 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 behavior 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 behavior 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 behavior. 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.

Constructor & Destructor Documentation

QSurfaceFormat::QSurfaceFormat ( FormatOptions options )

Constructs a QSurfaceFormat with the given format options.

QSurfaceFormat::QSurfaceFormat ( const QSurfaceFormat & other )

Constructs a copy of other.

QSurfaceFormat::~QSurfaceFormat ( )

Destroys the QSurfaceFormat.

Method Documentation

int QSurfaceFormat::alphaBufferSize ( ) const

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

int QSurfaceFormat::blueBufferSize ( ) const

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

QSurfaceFormat QSurfaceFormat::defaultFormat ( )

static

Returns the global default surface format. When setDefaultFormat() is not called, this is a default-constructed QSurfaceFormat.

See also: setDefaultFormat()

int QSurfaceFormat::depthBufferSize ( ) const

Returns the depth buffer size.

See also: setDepthBufferSize()

int QSurfaceFormat::greenBufferSize ( ) const

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

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.

int QSurfaceFormat::majorVersion ( ) const

Returns the major OpenGL version. The default version is 2.0.

int QSurfaceFormat::minorVersion ( ) const

Returns the minnor OpenGL version.

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

Copy assigns from other and returns a reference to this object.

QSurfaceFormat::FormatOptions QSurfaceFormat::options ( ) const

Returns the currently set format options.

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

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.

int QSurfaceFormat::redBufferSize ( ) const

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

QSurfaceFormat::RenderableType QSurfaceFormat::renderableType ( ) const

Returns the renderable type which will be desktop OpenGL or OpenGL ES.

int QSurfaceFormat::samples ( ) const

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

See also: setSamples()

void QSurfaceFormat::setAlphaBufferSize ( int size )

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

void QSurfaceFormat::setBlueBufferSize ( int size )

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.

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 will use the same format.

Note: When setting Qt::AA_ShareOpenGLContexts it is strongly recommended to place the call to this method before the construction of the QApplication. Otherwise format will not be applied to the global share context and therefore issues may arise with context sharing afterwards.

See also: defaultFormat()

void QSurfaceFormat::setDepthBufferSize ( int size )

Set the minimum depth buffer size to size.

See also: depthBufferSize()

void QSurfaceFormat::setGreenBufferSize ( int size )

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.

void QSurfaceFormat::setMajorVersion ( int majorVersion )

Sets the major OpenGL version to majorVersion.

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

void QSurfaceFormat::setMinorVersion(int minorVersion)

Sets the minor OpenGL version to minorVersoin.

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

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

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

Sets the format options to options.

See also: options(), testOption()

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.

void QSurfaceFormat::setRedBufferSize ( int size )

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.

void QSurfaceFormat::setRenderableType ( RenderableType type )

Sets the desired renderable to type.

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

void QSurfaceFormat::setStencilBufferSize ( int size )

Set the preferred stencil buffer size to size bits.

See also: stencilBufferSize()

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

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.

void QSurfaceFormat::setSwapInterval ( int interval )

Sets the preferred swap interval to the passed value of 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. If it is not then the request will be silently ignored.

See also: swapInterval()

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

Sets the desired major and minor OpenGL versions. The default version is 2.0.

int QSurfaceFormat::stencilBufferSize ( ) const

Returns the stencil buffer size in bits.

See also: setStencilBufferSize()

bool QSurfaceFormat::stereo ( ) const

inline

Returns true if stereo buffering is enabled, otherwise returns false. Stereo buffering is disabled by default.

See also: setStereo()

QSurfaceFormat::SwapBehavior QSurfaceFormat::swapBehavior ( ) const

Returns the configured swap behavior.

See also: setSwapBehavior()

int QSurfaceFormat::swapInterval ( ) const

Returns the swap interval.

See also: setSwapInterval()

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

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

See also: options()

QPair< int, int > QSurfaceFormat::version ( ) const

Returns a QPair<int, int> representing the OpenGL version. This is useful for version checks. For example format.version() >= qMakePair(3, 2).

Friends And Related Function Documentation

bool operator!=	(	const QSurfaceFormat &	a,
		const QSurfaceFormat &	b
	)

friend

Returns false if all the options of the two QSurfaceFormat objects a and b are equal, otherwise returns true.

bool operator==	(	const QSurfaceFormat &	a,
		const QSurfaceFormat &	b
	)

friend

Returns true if all the options of the two QSurfaceFormat objects a and b are equal.

Public Typedefs

Public Types

Public Methods