QRhiGles2InitParams Struct

Detailed Description

An OpenGL-based QRhi needs an already created QSurface that can be used in combination with QOpenGLContext. Most commonly, this is a QOffscreenSurface in practice. Additionally, while optional, it is recommended that the QWindow the first QRhiSwapChain will target is passed in as well.

QOffscreenSurface *fallbackSurface = QRhiGles2InitParams::newFallbackSurface();
QRhiGles2InitParams params;
params.fallbackSurface = fallbackSurface;
params.window = window;
rhi = QRhi::create(QRhi::OpenGLES2, &params);

By default QRhi creates a QOpenGLContext on its own. This approach works well in most cases, included threaded scenarios, where there is a dedicated QRhi for each rendering thread. As there will be a QOpenGLContext for each QRhi, the OpenGL context requirements (a context can only be current on one thread) are satisfied. The implicitly created context is destroyed automatically together with the QRhi.

The QSurfaceFormat for the context is specified in format. The constructor sets this to QSurfaceFormat::defaultFormat() so applications that call QSurfaceFormat::setDefaultFormat() with the appropriate settings before the constructor runs will not need to change value of format.

A QSurface has to be specified in fallbackSurface. In order to prevent mistakes in threaded situations, this is never created automatically by the QRhi because, like QWindow, instances of QSurface subclasses can often be created on the gui/main thread only.

As a convenience, applications can use newFallbackSurface() which creates and returns a QOffscreenSurface that is compatible with the QOpenGLContext that is going to be created by the QRhi afterwards. Note that the ownership of the returned QOffscreenSurface is transferred to the caller and the QRhi will not destroy it.

In case resource sharing with an existing QOpenGLContext is desired, shareContext can be set to an existing QOpenGLContext. Alternatively, Qt::AA_ShareOpenGLContexts is honored as well, when enabled.

Working with existing OpenGL contexts

When interoperating with another graphics engine, it may be necessary to get a QRhi instance that uses the same OpenGL context. This can be achieved by passing a pointer to a QRhiGles2NativeHandles to QRhi::create(). The QRhiGles2NativeHandles::context must be set to a non-null value then.

An alternative approach is to create a QOpenGLContext that shares resources with the other engine's context and passing in that context via QRhiGles2NativeHandles.

The QRhi does not take ownership of the QOpenGLContext passed in via QRhiGles2NativeHandles.