Represents a native OpenGL context which is used to render OpenGL content on a QSurface. More...

Inheritance diagram for QOpenGLContext:

Public Types
enum	OpenGLModuleType

Public Signals
void	aboutToBeDestroyed ()

Public Signals inherited from QObject
void	destroyed (QObject *obj=nullptr)

void	objectNameChanged (const QString &objectName)

Public Methods
	QOpenGLContext (QObject *parent=nullptr)

	~QOpenGLContext ()

bool	create ()

GLuint	defaultFramebufferObject () const

void	doneCurrent ()

QSet< QByteArray >	extensions () const

QOpenGLExtraFunctions *	extraFunctions () const

QSurfaceFormat	format () const

QOpenGLFunctions *	functions () const

FP_Void	getProcAddress (const QByteArray &procName) const

bool	hasExtension (const QByteArray &extension) const

bool	isOpenGLES () const

bool	isValid () const

bool	makeCurrent (QSurface *surface)

QVariant	nativeHandle () const

QScreen *	screen () const

void	setFormat (const QSurfaceFormat &format)

void	setNativeHandle (const QVariant &handle)

void	setScreen (QScreen *screen)

void	setShareContext (QOpenGLContext *shareContext)

QOpenGLContext *	shareContext () const

QOpenGLContextGroup *	shareGroup () const

QSurface *	surface () const

void	swapBuffers (QSurface *surface)

template<class TYPE >
TYPE *	versionFunctions () const

QAbstractOpenGLFunctions *	versionFunctions (const QOpenGLVersionProfile &versionProfile=QOpenGLVersionProfile ()) const

Public Methods inherited from QObject
	QObject (QObject *parent=nullptr)

	~QObject ()

bool	blockSignals (bool block)

const QList< QObject * > &	children () const

bool	connect (const QObject *sender, const QString &signalMethod, const QString &location, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

bool	connect (const QObject *sender, const QString &signalMethod, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

bool	disconnect (const QObject *receiver, const QString &slotMethod=QString ()) const

bool	disconnect (const QString &signalMethod, const QString &location, const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const

bool	disconnect (const QString &signalMethod=QString (), const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const

void	dumpObjectInfo ()

void	dumpObjectTree ()

QList< QString >	dynamicPropertyNames () const

virtual bool	event (QEvent *event)

virtual bool	eventFilter (QObject watched, QEvent event)

template<typename T >
T	findChild (const QString &childName=QString ()) const

template<class T >
QList< T >	findChildren (const QRegularExpression &regExp, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const

template<class T >
QList< T >	findChildren (const QString &childName=QString (), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const

bool	inherits (const QString &className) const

void	installEventFilter (QObject *filterObj)

bool	isWidgetType () const

bool	isWindowType () const

void	killTimer (int id)

const QMetaObject *	metaObject () const

void	moveToThread (QThread *targetThread)

QString	objectName () const

QObject *	parent () const

template<class T = QVariant>
T	property (const QString &name) const

void	removeEventFilter (QObject *obj)

void	setObjectName (const QString &name)

void	setParent (QObject *parent)

bool	setProperty (const QString &name, const QVariant &value)

bool	signalsBlocked () const

int	startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)

QThread *	thread () const

Static Public Methods
static bool	areSharing (QOpenGLContext first, QOpenGLContext second)

static QOpenGLContext *	currentContext ()

static QOpenGLContext *	globalShareContext ()

static void *	openGLModuleHandle ()

static OpenGLModuleType	openGLModuleType ()

static bool	supportsThreadedOpenGL ()

Static Public Methods inherited from QObject
static bool	connect (const QObject sender, const QMetaMethod &signalMethod, const QObject receiver, const QMetaMethod &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

static bool	connect (const QObject sender, const QString &signalMethod, const QObject receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection, const QString &location=QString ())

static bool	connect (const QObject sender, const QString &signalMethod, const QString &location, const QObject receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool	connect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver receiver, SlotReturn (SlotClass::slotMethod)(SlotArgs...), Qt::ConnectionType type=Qt::AutoConnection)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool	connect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver *receiver, T slotLambda, Qt::ConnectionType type=Qt::AutoConnection)

static bool	disconnect (const QObject sender, const QMetaMethod &signalMethod, const QObject receiver, const QMetaMethod &slotMethod)

static bool	disconnect (const QObject sender, const QString &signalMethod, const QObject receiver, const QString &slotMethod)

static bool	disconnect (const QObject sender, const QString &signalMethod, const QString &location, const QObject receiver, const QString &slotMethod)

static bool	disconnect (const QObject sender, std::nullptr_t, const QObject receiver, std::nullptr_t)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool	disconnect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver receiver, SlotReturn (SlotClass::slotMethod)(SlotArgs...))

template<class Sender , class SignalClass , class... SignalArgs, class Receiver >
static bool	disconnect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver *receiver, std::nullptr_t slotMethod=nullptr)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool	disconnect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver *receiver, T slotMethod)

static QMetaObject &	staticMetaObject ()

static QString	tr (const char text, const char comment=nullptr, std::optional< int > numArg=std::optional< int >())

Friends
class	QGLContext

class	QGLPixelBuffer

class	QOpenGLFramebufferObject

Additional Inherited Members
Public Slots inherited from QObject
void	deleteLater ()

Protected Methods inherited from QObject
virtual void	childEvent (QChildEvent *event)

virtual void	connectNotify (const QMetaMethod &signalMethod) const

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const QMetaMethod &signalMethod) const

bool	isSignalConnected (const QMetaMethod &signalMethod) const

int	receivers (const QString &signal) const

QObject *	sender () const

int	senderSignalIndex () const

virtual void	timerEvent (QTimerEvent *event)

Properties inherited from QObject
	objectName

Related Functions inherited from QObject
T	qobject_cast (QObject *object)

	QObjectList

Detailed Description

The QOpenGLContext class represents a native OpenGL context which is used to render OpenGL content on a QSurface.

This class represents the OpenGL state of an underlying OpenGL context. To configure a context set the screen and format to match the target surface. A surface is a specific region of the screen where OpenGL content will be displayed. It may be necessary to share resources by calling setShareContext(). Once the context has been configured then call create(). Check the return value or call isValid() to determine if the context was successfully initialized.

A context can be activated for a given surface by calling makeCurrent(). When OpenGL rendering is complete call swapBuffers() to swap the front and back buffers of the surface. At this point the new content becomes visible to the user. QOpenGLContext requires calling makeCurrent() one more time before rendering a new frame.

If the context is temporarily unused it can be useful to delete the context to free resources. Your application should connect to the aboutToBeDestroyed() signal to clean up any resources which have been allocated.

Once a QOpenGLContext is marked activated your application can render to the context using the CopperSpice OpenGL classes like QOpenGLFunctions, QOpenGLBuffer, QOpenGLShaderProgram, and QOpenGLFramebufferObject. Another option is to call functions in the C OpenGL API directly. The latter is necessary when using OpenGL 1.x or OpenGL ES 1.x.

Member Enumeration Documentation

enum QOpenGLContext::OpenGLModuleType

This enum defines the type of the underlying OpenGL implementation.

Constant	Value	Description
QOpenGLContext::LibGL	0	OpenGL
QOpenGLContext::LibGLES	1	OpenGL ES 2.0 or higher

Constructor & Destructor Documentation

QOpenGLContext::QOpenGLContext ( QObject * parent = nullptr )

explicit

Creates a new OpenGL context with the given parent. Before the context can be used call setFormat() and then create().

See also: create(), makeCurrent()

QOpenGLContext::~QOpenGLContext ( )

Destroys the QOpenGLContext object. If this QOpenGLContext is active for the current thread then doneCurrent() will be called.

Method Documentation

void QOpenGLContext::aboutToBeDestroyed ( )

signal

This signal is emitted before the underlying native OpenGL context is destroyed so applications can release OpenGL resources.

bool QOpenGLContext::areSharing	(	QOpenGLContext *	first,
		QOpenGLContext *	second
	)

static

Returns true if the first and second contexts are sharing OpenGL resources.

bool QOpenGLContext::create ( )

Attempts to create the OpenGL context with the current configuration. The current configuration includes the format, share context, and the screen. Returns true if the native context was successfully created and is ready to be used. If the context already exists this method will destroy the existing context and then create a new one.

If the OpenGL implementation on your system does not support the requested version of OpenGL context, then QOpenGLContext will try to create the closest matching version. The actual created context properties can be queried using the QSurfaceFormat returned by the format() function. For example, if you request a context which supports OpenGL 4.3 Core profile but the driver and/or hardware only support version 3.2 Core profile contexts, then you will get a 3.2 Core profile context.

See also: format(), makeCurrent()

QOpenGLContext * QOpenGLContext::currentContext ( )

static

Returns the last context which called makeCurrent() in the current thread or a nullptr if no context is active.

GLuint QOpenGLContext::defaultFramebufferObject ( ) const

This method returns the default framebuffer object for the current surface.

On some platforms the default framebuffer object depends on the surface being rendered to and might not have an index of 0. Instead of calling glBindFramebuffer(0) call glBindFramebuffer(ctx->defaultFramebufferObject()). If you use the glBindFramebuffer() in QOpenGLFunctions the context frame buffer object will be set correctly.

Widgets which render via framebuffer objects like QOpenGLWidget will override the value returned from this method when painting is active. At that time the correct "default" framebuffer is the widget associated backing framebuffer, not the platform specific one belonging to the top level window surface. This ensures the expected behavior for this method and other classes relying on it.

See also: QOpenGLFramebufferObject

void QOpenGLContext::doneCurrent ( )

Equivalent to calling makeCurrent() with a null surface. Calling this method results in there being no current context in the running thread.

See also: currentContext()

QSet< QByteArray > QOpenGLContext::extensions ( ) const

Returns the set of OpenGL extensions supported by this context. The context or a sharing context must be current.

See also: hasExtension()

QOpenGLExtraFunctions * QOpenGLContext::extraFunctions ( ) const

Returns the QOpenGLExtraFunctions instance for this context. The context or a sharing context must be current. The returned QOpenGLExtraFunctions instance is ready to be used and it does not need initializeOpenGLFunctions() to be called.

QOpenGLExtraFunctions contains functionality that is not guaranteed to be available at runtime. Runtime availability depends on the platform, graphics driver, and the OpenGL version requested by the application.

See also: QOpenGLFunctions, QOpenGLExtraFunctions

QSurfaceFormat QOpenGLContext::format ( ) const

Returns the format of the underlying platform context if create() has been called. Otherwise, returns the requested format.

The requested and the actual format may differ. Requesting a given OpenGL version does not mean the resulting context will target exactly the requested version. It is only guaranteed that the version/profile/options combination for the created context is compatible with the request, as long as the driver is able to provide such a context.

For example, requesting an OpenGL version 3.x core profile context may result in an OpenGL 4.x core profile context. Similarly, a request for OpenGL 2.1 may result in an OpenGL 3.0 context with deprecated functions enabled. Finally, depending on the driver, unsupported versions may result in either a context creation failure or in a context for the highest supported version.

Similar differences are possible in the buffer sizes, for example, the resulting context may have a larger depth buffer than requested.

See also: setFormat()

QOpenGLFunctions * QOpenGLContext::functions ( ) const

Returns the QOpenGLFunctions instance for this context. The context or a sharing context must be current. The returned QOpenGLFunctions instance is ready to be used and it does not need initializeOpenGLFunctions() to be called.

FP_Void QOpenGLContext::getProcAddress ( const QByteArray & procName ) const

Resolves the function pointer to an OpenGL extension function identified by procName. Returns a nullptr if no such function can be found.

QOpenGLContext * QOpenGLContext::globalShareContext ( )

static

Returns the shared OpenGL context for the application, if one is available. Otherwise, this method will return a nullptr. This is useful if you need to upload OpenGL objects (buffers, textures, etc.) before creating or showing a QOpenGLWidget.

You must set the Qt::AA_ShareOpenGLContexts flag on QApplication before creating the QApplication object, otherwise CopperSpice may not create a global shared context. Do not attempt to make the context returned by this method current on any surface. Instead, create a new context which shares with the global one and then make the new context current.

See also: makeCurrent(), setShareContext()

bool QOpenGLContext::hasExtension ( const QByteArray & extension ) const

Returns true if this OpenGL context supports the specified OpenGL extension, otherwise returns false. The context or a sharing context must be current.

See also: extensions()

bool QOpenGLContext::isOpenGLES ( ) const

Returns true if the context is an OpenGL ES context. If the context has not been created, the result will be based on the requested format set via setFormat().

See also: create(), format(), setFormat()

bool QOpenGLContext::isValid ( ) const

Returns true if this context is valid and was successfully created. On some platforms, the return value of false for a context which was successfully created indicates the OpenGL context was lost.

The typical way to handle context loss scenarios in applications is to check via this method whenever makeCurrent() fails and returns false. If this method then returns false, recreate the underlying native OpenGL context by calling create(), call makeCurrent() again and then reinitialize all OpenGL resources.

On some platforms context loss situations is not something that can avoided. On others, they may need to be opted-in to. This can be done by enabling ResetNotification in the QSurfaceFormat. This will lead to setting RESET_NOTIFICATION_STRATEGY_EXT to LOSE_CONTEXT_ON_RESET_EXT in the underlying native OpenGL context. QOpenGLContext will then monitor the status via glGetGraphicsResetStatusEXT() in every makeCurrent().

See also: create()

bool QOpenGLContext::makeCurrent ( QSurface * surface )

Sets the current context in the current thread to render to the given surface. Returns true if successful otherwise returns false. The latter may happen if the surface is not exposed or the graphics hardware is not available due to the application being suspended.

If surface is a nullptr then calling this method is equivalent to calling doneCurrent().

Avoid calling this method from a different thread than the one the QOpenGLContext instance lives in. If you wish to use QOpenGLContext from a different thread you should first make sure it is not current in the current thread, by calling doneCurrent() if necessary. Then call moveToThread(otherThread) before using it in the other thread.

See also: doneCurrent(), functions()

QVariant QOpenGLContext::nativeHandle ( ) const

Returns the native handle for the context. This method provides access to the QOpenGLContext underlying native context. The returned variant contains a platform-specific value type.

On platforms where retrieving the native handle is not supported or if neither create() nor setNativeHandle() was called, a null variant is returned.

See also: setNativeHandle()

void * QOpenGLContext::openGLModuleHandle ( )

static

Returns the platform specific handle for the OpenGL implementation that is currently in use. For example, a HMODULE on Windows. On platforms which do not use dynamic GL the return value is a nullptr. The library might be GL only, meaning the windowing system interface functions (for example EGL) may live in another or separate library.

This method can only be called after a QApplication has been created.

See also: openGLModuleType()

QOpenGLContext::OpenGLModuleType QOpenGLContext::openGLModuleType ( )

static

Returns the underlying OpenGL implementation type. On platforms where the OpenGL implementation is not dynamically loaded, the return value is determined during compile time and never changes. A desktop OpenGL implementation may be capable of creating ES-compatible contexts. In most cases it is better to check QSurfaceFormat::renderableType() or use the method isOpenGLES().

This method can only be called after a QApplication has been created.

QScreen * QOpenGLContext::screen ( ) const

Returns the screen this context is displayed on.

See also: setScreen()

void QOpenGLContext::setFormat ( const QSurfaceFormat & format )

Sets the format the OpenGL context should be compatible with. Call create() so the new format will take effect.

When the format is not explicitly set via this method, the format returned by QSurfaceFormat::defaultFormat() will be used. This means when using multiple contexts, individual calls to this method can be replaced by one single call to QSurfaceFormat::setDefaultFormat() before creating the first context.

See also: format()

void QOpenGLContext::setNativeHandle ( const QVariant & handle )

Set the native handle for this context. When create() is called and a native handle is set, configuration settings, like format(), are ignored since this QOpenGLContext will wrap an already created native context instead of creating a new one from scratch.

On some platforms the native context handle is not sufficient and other related handles (for example, for a window or display) have to be provided in addition. Therefore handle is variant containing a platform specific value type.

When create() is called with native handles set, QOpenGLContext does not take ownership of the handles, so destroying the QOpenGLContext does not destroy the native context.

See also: nativeHandle()

void QOpenGLContext::setScreen ( QScreen * screen )

Sets the screen this context will be displayed on.

See also: screen()

void QOpenGLContext::setShareContext ( QOpenGLContext * shareContext )

Configures this context to share textures, shaders, and other OpenGL resources with the given shareContext.

See also: shareContext()

QOpenGLContext * QOpenGLContext::shareContext ( ) const

Returns the share context this context was created with. If the underlying platform was not able to support the requested sharing this method will return a nullptr.

See also: setShareContext()

QOpenGLContextGroup * QOpenGLContext::shareGroup ( ) const

Returns the share group this context belongs to.

bool QOpenGLContext::supportsThreadedOpenGL ( )

static

Returns true if the platform supports OpenGL rendering outside the main (gui) thread. The value is controlled by the platform plugin in use and may also depend on the graphics drivers.

QSurface * QOpenGLContext::surface ( ) const

Returns the surface the context has been made current with. This is the surface passed as an argument to makeCurrent().

void QOpenGLContext::swapBuffers ( QSurface * surface )

Swap the back and front buffers of surface. Call this method to finish a frame of OpenGL rendering and make sure to call makeCurrent() again before issuing any further OpenGL commands. For example, as part of drawing a new frame.

template<class TYPE >

TYPE * QOpenGLContext::versionFunctions ( ) const

inline

Returns a pointer to an object which provides access to all functions for the version and profile of this context. The return value is owned by the QOpenGLContext.

There is no need to call QAbstractOpenGLFunctions::initializeOpenGLFunctions() as long as this context is current. This method can be called when the context is not current, however in that case it is the caller's responsibility to ensure proper initialization by calling QAbstractOpenGLFunctions::initializeOpenGLFunctions().

QOpenGLFunctions_3_3_Core* funcs = 0;
funcs = context->versionFunctions<QOpenGLFunctions_3_3_Core>();
 
if (! funcs) {
    qWarning() << "Could not obtain required OpenGL context version";
    exit(1);
}

QAbstractOpenGLFunctions * QOpenGLContext::versionFunctions ( const QOpenGLVersionProfile & versionProfile = QOpenGLVersionProfile() ) const

Returns a pointer to an object which provides access to all functions for the versionProfile of this context. The return value is owned by the QOpenGLContext.

There is no need to call QAbstractOpenGLFunctions::initializeOpenGLFunctions() as long as this context is current. This method can be called when the context is not current, however in that case it is the caller's responsibility to ensure proper initialization by calling QAbstractOpenGLFunctions::initializeOpenGLFunctions().

The templated version of this method is preferred since the result will be cast to the correct data type.

Public Types

Public Signals

Public Methods

Static Public Methods

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Method Documentation