QOffscreenSurface Class
QOffscreenSurface 类表示底层平台中的一个离屏表面。更多内容...
| 头文件： | #include <QOffscreenSurface> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake： | QT += gui |
| 继承自： | QObject 以及QSurface |
公共函数
| QOffscreenSurface(QScreen *targetScreen = nullptr, QObject *parent = nullptr) | |
| virtual | ~QOffscreenSurface() |
| void | create() |
| void | destroy() |
| bool | isValid() const |
| QNativeInterface * | nativeInterface() const |
| QSurfaceFormat | requestedFormat() const |
| QScreen * | screen() const |
| void | setFormat(const QSurfaceFormat &format) |
| void | setScreen(QScreen *newScreen) |
重新实现的公共函数
| virtual QSurfaceFormat | format() const override |
| virtual QSize | size() const override |
| virtual QSurface::SurfaceType | surfaceType() const override |
信号
| void | screenChanged(QScreen *screen) |
详细说明
QOffscreenSurface 旨在与QOpenGLContext 配合使用，以便在任意线程中使用 OpenGL 进行渲染，而无需创建QWindow 。
尽管该表面通常可进行渲染，但无法访问其像素。QOffscreenSurface 仅应用于创建 OpenGL 资源，例如纹理或帧缓冲区对象。
应用程序通常会使用 QOffscreenSurface 在单独的线程中执行一些耗时的任务，以避免阻塞主渲染线程。在 QOffscreenSurface 上下文中创建的资源可以与主 OpenGL 上下文共享。一些常见的用例包括异步纹理上传或渲染到QOpenGLFramebufferObject 中。
离屏表面的具体实现方式取决于底层平台，但通常会使用像素缓冲区（pbuffer）。如果平台未实现或不支持离屏表面，QOffscreenSurface 将在内部使用一个不可见的QWindow 。
注意：由于在 某些平台上 QOffscreenSurface 由QWindow 作为后端支持，因此跨平台应用程序必须确保仅在主（GUI）线程上调用create()。 这样，QOffscreenSurface 就可以在其他线程上安全地与makeCurrent() 一起使用，但初始化和销毁必须始终在主（GUI）线程上进行。
注意：为了 创建一个保证与给定上下文和窗口兼容的离屏表面，请确保将格式设置为上下文或窗口的实际格式，即上下文或窗口创建后由QOpenGLContext::format()或QWindow::format()返回的QSurfaceFormat 。 将由QWindow::requestedFormat() 返回的格式传递给setFormat() 可能会导致生成不兼容的离屏表面，因为底层窗口系统接口可能为窗口表面和 pbuffer 表面提供不同的配置集。
注意：某些 平台在可用时可能会使用无表面上下文扩展（例如 EGL_KHR_surfaceless_context）。在这种情况下，将不存在底层本机表面。对于 QOffscreenSurface 的使用场景（渲染到 FBO、纹理上传），这不会造成问题。
成员函数文档
[explicit] QOffscreenSurface::QOffscreenSurface(QScreen *targetScreen = nullptr, QObject *parent = nullptr)
使用给定的parent 为targetScreen 创建一个屏外表面。
底层平台绘图表面要等到调用create() 时才会创建。
[virtual noexcept] QOffscreenSurface::~QOffscreenSurface()
销毁屏幕外表面。
void QOffscreenSurface::create()
分配与离屏表面关联的平台资源。
此时，通过setFormat()设置的表面格式将被解析为一个实际的本机表面。
如有必要，请调用destroy() 来释放平台资源。
注意：某些 平台要求在主（GUI）线程上调用此函数。
另请参阅 destroy()。
void QOffscreenSurface::destroy()
释放与该离屏表面关联的本机平台资源。
另请参阅 create()。
[override virtual] QSurfaceFormat QOffscreenSurface::format() const
重新实现了：QSurface::format() const。
返回此离屏表面的实际格式。
在创建完离屏表面后，此函数将返回该表面的实际格式。如果平台无法满足请求的格式，则实际格式可能与请求的格式不同。
另请参阅 setFormat()、create() 和requestedFormat()。
bool QOffscreenSurface::isValid() const
如果该离屏表面有效，则返回true ；否则返回false 。
如果平台资源已成功分配，则该离屏表面有效。
另请参阅 create()。
template <typename QNativeInterface> QNativeInterface *QOffscreenSurface::nativeInterface() const
返回该画面的指定类型的本机接口。
该函数提供了对 QOffScreenSurface 平台特定功能的访问，这些功能在QNativeInterface 命名空间中进行了定义：
Android 系统中离屏表面的本机接口 |
如果请求的接口不可用，则返回一个 `nullptr `。
QSurfaceFormat QOffscreenSurface::requestedFormat() const
返回此离屏表面的请求表面格式。
如果平台实现不支持所请求的格式，则 `requestedFormat` 将与实际的离屏表面格式不同。
这是通过 `setFormat()` 设置的值。
QScreen *QOffscreenSurface::screen() const
返回与该离屏表面关联的屏幕。
另请参阅 setScreen()。
[signal] void QOffscreenSurface::screenChanged(QScreen *screen)
当屏幕外表面的screen 发生变化时，会发出此信号，这种变化可能是通过显式调用setScreen()设置的，也可能是当窗口的屏幕被移除时自动发生的。
void QOffscreenSurface::setFormat(const QSurfaceFormat &format)
设置离屏表面 `format`。
表面格式将在create() 函数中进行解析。在调用create() 之后再次调用此函数，不会重新解析原生表面的表面格式。
另请参阅 format()、create() 和destroy()。
void QOffscreenSurface::setScreen(QScreen *newScreen)
设置与离屏表面关联的屏幕。
如果离屏表面已创建，则将在newScreen 上重新创建该表面。
另请参阅 screen()。
[override virtual] QSize QOffscreenSurface::size() const
重写：QSurface::size() const。
返回离屏表面的大小。
[override virtual] QSurface::SurfaceType QOffscreenSurface::surfaceType() const
重写：QSurface::surfaceType() const。
返回离屏表面的表面类型。
离屏表面的类型始终为QSurface::OpenGLSurface 。
© 2026 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.
