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

© 2021 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.