QOpenGLContext Class

The QOpenGLContext class represents a native OpenGL context, enabling OpenGL rendering on a QSurface. More...

Header: #include <QOpenGLContext>
qmake: QT += gui
Since: Qt 5.0
Inherits: QObject.

Public Functions

QOpenGLContext(QObject * parent = 0)
~QOpenGLContext()
bool create()
GLuint defaultFramebufferObject() const
void doneCurrent()
QSet<QByteArray> extensions() const
QSurfaceFormat format() const
QOpenGLFunctions * functions() const
QFunctionPointer getProcAddress(const QByteArray & procName) const
bool hasExtension(const QByteArray & extension) const
bool isValid() const
bool makeCurrent(QSurface * surface)
QScreen * screen() const
void setFormat(const QSurfaceFormat & format)
void setScreen(QScreen * screen)
void setShareContext(QOpenGLContext * shareContext)
QOpenGLContext * shareContext() const
QOpenGLContextGroup * shareGroup() const
QSurface * surface() const
void swapBuffers(QSurface * surface)
QAbstractOpenGLFunctions * versionFunctions(const QOpenGLVersionProfile & versionProfile = QOpenGLVersionProfile()) const
TYPE * versionFunctions() const
  • 31 public functions inherited from QObject

Signals

void aboutToBeDestroyed()

Static Public Members

bool areSharing(QOpenGLContext * first, QOpenGLContext * second)
QOpenGLContext * currentContext()
  • 10 static public members inherited from QObject

Additional Inherited Members

  • 1 property inherited from QObject
  • 1 public slot inherited from QObject
  • 1 public variable inherited from QObject
  • 9 protected functions inherited from QObject
  • 2 protected variables inherited from QObject

Detailed Description

The QOpenGLContext class represents a native OpenGL context, enabling OpenGL rendering on a QSurface.

QOpenGLContext represents the OpenGL state of an underlying OpenGL context. To set up a context, set its screen and format such that they match those of the surface or surfaces with which the context is meant to be used, if necessary make it share resources with other contexts with setShareContext(), and finally call create(). Use isValid() to check if the context was successfully initialized.

A context can be made current against a given surface by calling makeCurrent(). When OpenGL rendering is done, call swapBuffers() to swap the front and back buffers of the surface, so that the newly rendered content becomes visible. To be able to support certain platforms, QOpenGLContext requires that you call makeCurrent() again before starting rendering a new frame, after calling swapBuffers().

If the context is temporarily not needed, such as when the application is not rendering, it can be useful to call destroy() to free resources. However, if you do so you will need to call create() again before the context can be used, and you might need to recreate any OpenGL resources and reinitialize the OpenGL state. You can connect to the aboutToBeDestroyed() signal to clean up any resources that have been allocated with different ownership from the QOpenGLContext itself.

Once a QOpenGLContext has been made current, you can render to it in a platform independent way by using Qt's OpenGL enablers such as QOpenGLFunctions, QOpenGLBuffer, QOpenGLShaderProgram, and QOpenGLFramebufferObject. It is also possible to use the platform's OpenGL API directly, without using the Qt enablers, although potentially at the cost of portability. The latter is necessary when wanting to use OpenGL 1.x or OpenGL ES 1.x.

For more information about the OpenGL API, refer to the official OpenGL documentation.

For an example of how to use QOpenGLContext see the OpenGL Window example.

Thread affinity

QOpenGLContext can be moved to a different thread with moveToThread(). Do not call makeCurrent() from a different thread than the one to which the QOpenGLContext object belongs. A context can only be current in one thread and against one surface at a time, and a thread only has one context current at a time.

Context resource sharing

Resources, such as framebuffer objects, textures, and vertex buffer objects can be shared between contexts. Use setShareContext() before calling create() to specify that the contexts should share these resources. QOpenGLContext internally keeps track of a QOpenGLContextGroup object which can be accessed with shareGroup(), and which can be used to find all the contexts in a given share group. A share group consists of all contexts that have been successfully initialized and are sharing with an existing context in the share group. A non-sharing context has a share group consisting of a single context.

Default framebuffer

On certain platforms, a framebuffer other than 0 might be the default frame buffer depending on the current surface. Instead of calling glBindFramebuffer(0), it is recommended that you use glBindFramebuffer(ctx->defaultFramebufferObject()), to ensure that your application is portable between different platforms. However, if you use QOpenGLFunctions::glBindFramebuffer(), this is done automatically for you.

See also QOpenGLFunctions, QOpenGLBuffer, QOpenGLShaderProgram, and QOpenGLFramebufferObject.

Member Function Documentation

QOpenGLContext::QOpenGLContext(QObject * parent = 0)

Creates a new OpenGL context instance with parent object parent.

Before it can be used you need to set the proper format and call create().

See also create() and makeCurrent().

QOpenGLContext::~QOpenGLContext()

Destroys the QOpenGLContext object.

This implicitly calls destroy(), so if this is the current context for the thread, doneCurrent() is also called.

See also destroy().

void QOpenGLContext::aboutToBeDestroyed() [signal]

This signal is emitted before the underlying native OpenGL context is destroyed, such that users may clean up OpenGL resources that might otherwise be left dangling in the case of shared OpenGL contexts.

If you wish to make the context current in order to do clean-up, make sure to only connect to the signal using a direct connection.

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, the share context, and the screen.

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 that supports OpenGL 4.3 Core profile but the driver and/or hardware only supports version 3.2 Core profile contexts then you will get a 3.2 Core profile context.

Returns true if the native context was successfully created and is ready to be used with makeCurrent(), swapBuffers(), etc.

See also makeCurrent(), destroy(), and format().

QOpenGLContext * QOpenGLContext::currentContext() [static]

Returns the last context which called makeCurrent in the current thread, or 0, if no context is current.

GLuint QOpenGLContext::defaultFramebufferObject() const

Call this to get the default framebuffer object for the current surface.

On some platforms the default framebuffer object depends on the surface being rendered to, and might be different from 0. Thus, instead of calling glBindFramebuffer(0), you should call glBindFramebuffer(ctx->defaultFramebufferObject()) if you want your application to work across different Qt platforms.

If you use the glBindFramebuffer() in QOpenGLFunctions you do not have to worry about this, as it automatically binds the current context's defaultFramebufferObject() when 0 is passed.

void QOpenGLContext::doneCurrent()

Convenience function for calling makeCurrent with a 0 surface.

This results in no context being current in the current thread.

See also makeCurrent() and 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().

QSurfaceFormat QOpenGLContext::format() const

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

Otherwise, returns the requested format.

See also setFormat().

QOpenGLFunctions * QOpenGLContext::functions() const

Get the QOpenGLFunctions instance for this context.

QOpenGLContext offers this as a convenient way to access QOpenGLFunctions without having to manage it manually.

The context or a sharing context must be current.

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

Resolves the function pointer to an OpenGL extension function, identified by procName

Returns 0 if no such function can be found.

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

Returns true if this OpenGL context supports the specified OpenGL extension, false otherwise.

The context or a sharing context must be current.

See also extensions().

bool QOpenGLContext::isValid() const

Returns if this context is valid, i.e. has been successfully created.

See also create().

bool QOpenGLContext::makeCurrent(QSurface * surface)

Makes the context current in the current thread, against the given surface. Returns true if successful.

If surface is 0 this is equivalent to calling doneCurrent().

Do not call this function 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 call make sure it's not current in the current thread, by calling doneCurrent() if necessary. Then call moveToThread(otherThread) before using it in the other thread.

See also functions() and doneCurrent().

QScreen * QOpenGLContext::screen() const

Returns the screen the context was created for.

See also setScreen().

void QOpenGLContext::setFormat(const QSurfaceFormat & format)

Sets the format the OpenGL context should be compatible with. You need to call create() before it takes effect.

See also format().

void QOpenGLContext::setScreen(QScreen * screen)

Sets the screen the OpenGL context should be valid for. You need to call create() before it takes effect.

See also screen().

void QOpenGLContext::setShareContext(QOpenGLContext * shareContext)

Makes this context share textures, shaders, and other OpenGL resources with shareContext. You need to call create() before it takes effect.

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 will return 0.

See also setShareContext().

QOpenGLContextGroup * QOpenGLContext::shareGroup() const

Returns the share group this context belongs to.

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 to finish a frame of OpenGL rendering, and make sure to call makeCurrent() again before you begin a new frame.

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

Returns a pointer to an object that provides access to all functions for the version of the current context. Before using any of the functions they must be initialized by calling QAbstractOpenGLFunctions::initializeOpenGLFunctions().

Usually one would use the template version of this function to automatically have the result cast to the correct type.

TYPE * QOpenGLContext::versionFunctions() const

This function overloads versionFunctions().

Returns a pointer to an object that provides access to all functions for the version and profile of this context. Before using any of the functions they must be initialized by calling QAbstractOpenGLFunctions::initializeOpenGLFunctions().

Usually one would use the template version of this function to automatically have the result cast to the correct type.

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);
}
funcs->initializeOpenGLFunctions(context);

It is possible to request a functions object for a different version and profile than that for which the context was created. To do this either use the template version of this function specifying the desired functions object type as the template parameter or by passing in a QOpenGLVersionProfile object as an argument to the non-template function.

Note that requests for function objects of other versions or profiles can fail and in doing so will return a null pointer. Situations in which creation of the functions object can fail are if the request cannot be satisfied due to asking for functions that are not in the version or profile of this context. For example:

  • Requesting a 3.3 core profile functions object would succeed.
  • Requesting a 3.3 compatibility profile functions object would fail. We would fail to resolve the deprecated functions.
  • Requesting a 4.3 core profile functions object would fail. We would fail to resolve the new core functions introduced in versions 4.0-4.3.
  • Requesting a 3.1 functions object would succeed. There is nothing in 3.1 that is not also in 3.3 core.

Note that if creating a functions object via this method that the QOpenGLContext retains ownership of the object. This is to allow the object to be cached and shared.