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() 一起使用，但初始化和销毁必须始终在主（图形用户界面）线程上进行。
注意： 为了创建与给定上下文和窗口兼容的屏幕外表面，请确保将格式设置为上下文或窗口的实际格式，即创建上下文或窗口后从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() 释放平台资源。
注： 某些平台要求在主（图形用户界面）线程上调用此函数。
另请参阅 destroy()。
void QOffscreenSurface::destroy()
释放与该离屏曲面相关的本地平台资源。
另请参阅 create().
[override virtual] QSurfaceFormat QOffscreenSurface::format() const
重实现：QSurface::format() 常量。
返回此屏幕外曲面的实际格式。
创建屏幕外曲面后，此函数将返回曲面的实际格式。如果平台无法满足所请求的格式，它可能与所请求的格式不同。
另请参阅 setFormat()、create() 和requestedFormat()。
bool QOffscreenSurface::isValid() const
如果屏幕外表面有效，则返回true ；否则返回false 。
如果平台资源已成功分配，则屏幕外表面有效。
另请参阅 create() 。
template <typename QNativeInterface> QNativeInterface *QOffscreenSurface::nativeInterface() const
返回曲面的给定类型的本地接口。
该函数可访问QNativeInterface 命名空间中定义的 QOffScreenSurface 的特定平台功能：
Android 上屏幕外表面的本地接口 |
如果请求的接口不可用，则返回nullptr 。
QSurfaceFormat QOffscreenSurface::requestedFormat() const
返回此屏幕外表面所请求的表面格式。
如果平台实现不支持请求的格式，则请求的表面格式将与实际的屏幕外表面格式不同。
这是用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() 常量。
返回屏幕外表面的尺寸。
[override virtual] QSurface::SurfaceType QOffscreenSurface::surfaceType() const
重实现：QSurface::surfaceType() 常量。
返回离屏曲面的曲面类型。
非屏幕表面的表面类型总是QSurface::OpenGLSurface 。
© 2025 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.
