Detailed Description
The QOpenGLContext 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.
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 succesfully 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.
Member Function Documentation
QOpenGLContext::QOpenGLContext(QObject * parent = 0)
Creates a new OpenGL context instance.
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 two 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.
Returns true if the native context was successfully created and is ready to be used with makeCurrent(), swapBuffers(), etc.
See also makeCurrent() and destroy().
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().
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::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.
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)
Sets the context to share textures, shaders, and other OpenGL resources with. 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().
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 the given surface.
Call this to finish a frame of OpenGL rendering, and make sure to call makeCurrent() again before you begin a new frame.
If you have bound a non-default framebuffer object, you need to use bindDefaultFramebufferObject() to make sure that the default framebuffer object is bound before calling swapBuffers(), as some Qt platforms assume that the default framebuffer object is bound.
