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.
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.
For a list of all available interfaces, see the QNativeInterface namespace.
Accessed through QOpenGLContext::nativeInterface().
Native interface to an NSOpenGLContext on macOS
Native interface to an EGL context
Native interface to a GLX context
Native interface to a WGL context on Windows
Accessed through QOffscreenSurface::nativeInterface().
Native interface to a offscreen surface on Android
Accessed through QSGTexture::nativeInterface().
Provides access to and enables adopting Direct3D 11 texture objects
Provides access to and enables adopting Metal texture objects
Provides access to and enables adopting OpenGL texture objects
Provides access to and enables adopting Vulkan image objects
© 2023 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.