QWGLNativeContext Class

Detailed Description

QWGLNativeContext is a value class that can be passed to QOpenGLContext::setNativeHandle(). When creating a QOpenGLContext with the native handle set, no new context will get created. Instead, the provided handles are used, without taking ownership. This allows wrapping a context created by an external framework or rendering engine. The typical usage will be similar to the following snippet:

 #include <QtPlatformSupport/QWGLNativeContext>
 ...create and retrieve the WGL context and the corresponding window...
 QOpenGLContext *context = new QOpenGLContext;
 QWGLNativeContext nativeContext(hglrc, hwnd);
 context->setNativeHandle(QVariant::fromValue(nativeContext));
 context->create();
 ...

The window is needed because the its pixel format will be queried. When the adoption is successful, QOpenGLContext::format() will return a QSurfaceFormat describing this pixel format.

It is recommended to restrict the usage of QOpenGLContexts created this way. Various platform-specific behavior and issues may prevent such contexts to be made current with windows (surfaces) created by Qt due to non-matching pixel formats for example. A potentially safer solution is to use the wrapped context only to set up sharing and perform Qt-based rendering offscreen, using a separate, dedicated QOpenGLContext. The resulting textures are then accessible in the foreign context too.

 ...like above...
 QOpenGLContext *qtcontext = new QOpenGLContext;
 qtcontext->setShareContext(context);
 qtcontext->setFormat(context->format());
 qtcontext->create();
 ...use qtcontext for rendering with Qt...

In addition to being used with QOpenGLContext::setNativeHandle(), this class is used also to retrieve the native context handle, that is, a HGLRC value, from a QOpenGLContext. Calling QOpenGLContext::nativeHandle() returns a QVariant which, on Windows with opengl32.dll at least, will contain a QWGLNativeContext:

 QVariant nativeHandle = context->nativeHandle();
 if (!nativeHandle.isNull() && nativeHandle.canConvert<QWGLNativeContext>()) {
     QWGLNativeContext nativeContext = nativeHandle.value<QWGLNativeContext>();
     HGLRC hglrc = nativeContext.context();
     ...
 }