QRhiGles2InitParams Class

Detailed Description

OpenGL specific initialization parameters.

An OpenGL-based QRhi needs an already created QOffscreenSurface at minimum. 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 use QSurfaceFormat::setDefaultFormat() do not need to set the format again.

Note: The depth and stencil buffer sizes are set automatically to 24 and 8 when no size was explicitly set for these buffers in format. As there are possible adjustments to format, applications can use adjustedFormat() to query the effective format that is passed to QOpenGLContext::setFormat() internally.

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

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.

Note: QRhiSwapChain can only target QWindow instances that have their surface type set to QSurface::OpenGLSurface.

Note: window is optional. It is recommended to specify it whenever possible, in order to avoid problems on multi-adapter and multi-screen systems. When window is not set, the very first QOpenGLContext::makeCurrent() happens with fallbackSurface which may be an invisible window on some platforms (for example, Windows) and that may trigger unexpected problems in some cases.

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 context must be set to a non-null value.

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.