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