Native Interfaces▲
The native interfaces provide access to native or platform specific APIs of the classes they extend.
The interfaces live in the QNativeInterface namespace, and cover use-cases such as accessing underlying native handles, adopting existing native handles, or providing platform specific APIs.
Example Usage▲
Accessing underlying native handles▲
In situations where a feature of the native platform is not exposed in Qt, it can be helpful to access the native handles maintained by Qt, and use those to call the native APIs instead.
For example, to access the underlying NSOpenGLContext of an QOpenGLContext on macOS, via the QNativeInterface::QCocoaGLContext native interface:
using namespace QNativeInterface;
if (auto *cocoaGLContext = glContext->nativeInterface<QCocoaGLContext>())
[cocoaGLContext->nativeContext() makeCurrentContext];The native interface is accessed through the QOpenGLContext::nativeInterface() accessor, which ensures that the requested interface is available, and otherwise returns nullptr. The underlying NSOpenGLContext is then accessed through the nativeContext() accessor.
Adopting existing native handles▲
Similarly to the window embedding use-case, there are situations where the native platform, or another toolkit, has created a native handle that you would like to pass on to Qt — wrapping the existing handle instead of creating a new one.
For example, to adopt an existing NSOpenGLContext, and use that to share resources with a context created by Qt:
using namespace QNativeInterface;
QOpenGLContext *adoptedContext = QCocoaGLContext::fromNativeContext(nsOpenGLContext);
anotherContext->setShareContext(adoptedContext);The adopted context is created by a platform specific factory function in the QNativeInterface::QCocoaGLContext native interface.
Accessing platform specific APIs▲
In some cases an API is too platform specific to be included in the cross platform Qt classes, but is still useful to include. These APIs are available either in the same way as when accessing the underlying native handles, through the nativeInterface() accessor, or directly as static function in the native interface.
For example, to pull out the OpenGL module handle on Windows:
using namespace QNativeInterface;
HMODULE moduleHandle = QWGLContext::openGLModuleHandle();Source and Binary Compatibility▲
There are no source or binary compatibility guarantees for the native interface APIs, meaning that an application using these interfaces is only guaranteed to work with the Qt version it was developed against.
Available Interfaces▲
For a list of all available interfaces, see the QNativeInterface namespace.
QOpenGLContext▲
Accessed through QOpenGLContext::nativeInterface().
-
QNativeInterface::QCocoaGLContext: Native interface to an NSOpenGLContext on macOS.
-
QNativeInterface::QEGLContext: Native interface to an EGL context.
-
QNativeInterface::QGLXContext: Native interface to a GLX context.
-
QNativeInterface::QWGLContext: Native interface to a WGL context on Windows.
QOffscreenSurface▲
Accessed through QOffscreenSurface::nativeInterface().
-
QNativeInterface::QAndroidOffscreenSurface: Native interface to a offscreen surface on Android.
QSGTexture▲
Accessed through QSGTexture::nativeInterface().
-
QNativeInterface::QSGD3D11Texture: Provides access to and enables adopting Direct3D 11 texture objects.
-
QNativeInterface::QSGMetalTexture: Provides access to and enables adopting Metal texture objects.
-
QNativeInterface::QSGOpenGLTexture: Provides access to and enables adopting OpenGL texture objects.
-
QNativeInterface::QSGVulkanTexture: Provides access to and enables adopting Vulkan image objects.