QRhiGles2InitParams Class

OpenGL specific initialization parameters. More...

Header: #include <QRhiGles2InitParams>
qmake: QT += rhi
Inherits: QRhiInitParams

Public Functions

Public Variables

QOffscreenSurface *fallbackSurface
QSurfaceFormat format
QWindow *window

Static Public Members

QSurfaceFormat adjustedFormat(const QSurfaceFormat &format = QSurfaceFormat::defaultFormat())
QOffscreenSurface *newFallbackSurface(const QSurfaceFormat &format = QSurfaceFormat::defaultFormat())

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.

Member Type Documentation

Property Documentation

Member Function Documentation

QRhiGles2InitParams::QRhiGles2InitParams()

Constructs a new QRhiGles2InitParams.

format is set to QSurfaceFormat::defaultFormat().

[static] QSurfaceFormat QRhiGles2InitParams::adjustedFormat(const QSurfaceFormat &format = QSurfaceFormat::defaultFormat())

Returns the QSurfaceFormat that will be set on the QOpenGLContext before calling QOpenGLContext::create(). This format is based on format, but may be adjusted. Applicable only when QRhi creates the context. Applications are advised to set this format on their QWindow in order to avoid potential BAD_MATCH failures.

[static] QOffscreenSurface *QRhiGles2InitParams::newFallbackSurface(const QSurfaceFormat &format = QSurfaceFormat::defaultFormat())

Returns a new QOffscreenSurface that can be used with a QRhi by passing it via a QRhiGles2InitParams.

format is adjusted as appropriate in order to avoid having problems afterwards due to an incompatible context and surface.

Note: This function must only be called on the gui/main thread.

Note: It is the application's responsibility to destroy the returned QOffscreenSurface on the gui/main thread once the associated QRhi has been destroyed. The QRhi will not destroy the QOffscreenSurface.

Member Variable Documentation

Related Non-Members

Macro Documentation