QOpenGLContext Class

成员函数文档

[explicit] QOpenGLContext::QOpenGLContext(QObject *parent = nullptr)

创建一个以父对象 `parent` 为父的新 OpenGL 上下文实例。

在能够使用它之前，您需要设置正确的格式并调用create()。

另请参阅 create() 和makeCurrent()。

[virtual noexcept] QOpenGLContext::~QOpenGLContext()

销毁QOpenGLContext 对象。

如果这是线程的当前上下文，则还会调用 `doneCurrent()`。

[signal] void QOpenGLContext::aboutToBeDestroyed()

该信号在底层原生 OpenGL 上下文被销毁之前发出，以便用户能够清理 OpenGL 资源——否则在共享 OpenGL 上下文的情况下，这些资源可能会处于悬空状态。

如果您希望将该上下文设为当前上下文以进行清理，请确保仅通过直接连接来订阅该信号。

[static] bool QOpenGLContext::areSharing(QOpenGLContext *first, QOpenGLContext *second)

如果first 和second 上下文共享OpenGL资源，则返回true 。

bool QOpenGLContext::create()

尝试使用当前配置创建 OpenGL 上下文。

当前配置包括格式、共享上下文和屏幕。

如果系统上的 OpenGL 实现不支持所请求的 OpenGL 上下文版本，则QOpenGLContext 将尝试创建最接近的匹配版本。 可以使用format() 函数返回的QSurfaceFormat 来查询实际创建的上下文属性。例如，如果您请求一个支持 OpenGL 4.3 核心配置文件的上下文，但驱动程序和/或硬件仅支持 3.2 核心配置文件上下文，那么您将获得一个 3.2 核心配置文件上下文。

如果原生上下文已成功创建且可与makeCurrent()、swapBuffers() 等函数配合使用，则返回true 。

另请参阅 makeCurrent() 和format()。

[static] QOpenGLContext *QOpenGLContext::currentContext()

返回当前线程中最后一次调用makeCurrent 的上下文；如果没有当前上下文，则返回nullptr 。

GLuint QOpenGLContext::defaultFramebufferObject() const

调用此函数可获取当前渲染面的默认帧缓冲区对象。

在某些平台（例如 iOS）上，默认帧缓冲区对象取决于要渲染到的绘制表面，因此可能不为 0。 因此，如果您希望应用程序在不同的 Qt 平台上都能正常运行，则不应调用 glBindFramebuffer(0)，而应调用 glBindFramebuffer(ctx->defaultFramebufferObject())。

如果您在QOpenGLFunctions 中使用glBindFramebuffer()，则无需担心此问题，因为当传入0时，它会自动绑定当前上下文的defaultFramebufferObject()。

另请参阅 QOpenGLFramebufferObject 。

void QOpenGLContext::doneCurrent()

用于调用makeCurrent 并传入0表面值的便捷函数。

这将导致当前线程中不存在任何有效上下文。

另请参阅 makeCurrent() 和currentContext()。

QSet<QByteArray> QOpenGLContext::extensions() const

返回该上下文所支持的 OpenGL 扩展集。

当前上下文或共享上下文必须处于活动状态。

另请参阅 hasExtension()。

QOpenGLExtraFunctions *QOpenGLContext::extraFunctions() const

获取此上下文对应的QOpenGLExtraFunctions 实例。

QOpenGLContext 提供此方法，以便于访问QOpenGLExtraFunctions ，而无需手动管理它。

上下文或共享上下文必须为当前上下文。

返回的QOpenGLExtraFunctions 实例已准备就绪，无需调用 initializeOpenGLFunctions()。

另请参阅 QOpenGLFunctions 和QOpenGLExtraFunctions 。

QSurfaceFormat QOpenGLContext::format() const

如果已调用create()，则返回底层平台上下文的格式。

否则，返回请求的格式。

请求的格式与实际格式可能存在差异。请求特定的 OpenGL 版本并不意味着生成的上下文会完全针对该请求的版本。仅保证所创建上下文的版本/配置文件/选项组合与请求兼容，前提是驱动程序能够提供此类上下文。

例如，请求 OpenGL 3.x 核心配置文件上下文可能会得到一个 OpenGL 4.x 核心配置文件上下文。同样，请求 OpenGL 2.1 可能会得到一个启用了已弃用函数的 OpenGL 3.0 上下文。 最后，根据驱动程序的不同，不支持的版本可能会导致上下文创建失败，或者生成最高支持版本的上下文。

缓冲区大小方面也可能存在类似的差异，例如，生成的上下文的深度缓冲区可能比请求的更大。这是完全正常的。

另请参阅 setFormat()。

QOpenGLFunctions *QOpenGLContext::functions() const

获取此上下文对应的QOpenGLFunctions 实例。

QOpenGLContext 提供此方法作为访问 `QOpenGLFunctions ` 的便捷方式，无需手动管理它。

上下文或共享上下文必须为当前上下文。

返回的QOpenGLFunctions 实例已准备就绪，无需调用 initializeOpenGLFunctions()。

QFunctionPointer QOpenGLContext::getProcAddress(const QByteArray &procName) const

解析由procName 标识的OpenGL扩展函数的函数指针。

使用此函数可访问 OpenGL 扩展函数或核心函数，这些函数在某些平台上可能无法作为链接符号提供。

返回的指针可能因平台而异。某些系统即使该函数无效或不受支持，也可能返回一个非nullptr 的指针。

要可靠地检查函数的可用性，请通过调用QOpenGLContext::hasExtension() 来测试扩展的支持情况。对于核心函数，请通过QOpenGLContext::format() 返回的QSurfaceFormat 中的version() 检查当前上下文的版本。

QFunctionPointer QOpenGLContext::getProcAddress(const char *procName) const

[static] QOpenGLContext *QOpenGLContext::globalShareContext()

如果存在，则返回全局共享的 OpenGL 上下文；否则，返回 `nullptr`。

如果您需要在创建或显示QOpenGLWidget 或QQuickWidget 之前上传OpenGL对象（缓冲区、纹理等），此函数将非常有用。

另请参阅 Qt::AA_ShareOpenGLContexts 、setShareContext() 和makeCurrent()。

bool QOpenGLContext::hasExtension(const QByteArray &extension) const

如果该 OpenGL 上下文支持指定的 OpenGLextension ，则返回true ；否则返回false 。

上下文或共享上下文必须为当前上下文。

另请参阅 extensions()。

bool QOpenGLContext::isOpenGLES() const

如果上下文是 OpenGL ES 上下文，则返回 true。

如果上下文尚未创建，则结果基于通过setFormat() 设置的请求格式。

另请参阅 create()、format() 和setFormat()。

bool QOpenGLContext::isValid() const

如果该上下文有效（即已成功创建），则返回真。

在某些平台上，对于先前已成功创建的上下文，false 的返回值会表明该 OpenGL 上下文已丢失。

应用程序中处理上下文丢失情况的典型方法是，每当makeCurrent() 失败并返回false 时，通过此函数进行检查。如果该函数返回false ，则通过调用create() 重新创建底层本机 OpenGL 上下文，再次调用makeCurrent()，然后重新初始化所有 OpenGL 资源。

在某些平台上，上下文丢失的情况无法避免。但在其他平台上，可能需要主动启用该功能。这可以通过在QSurfaceFormat 中启用ResetNotification 来实现。这将导致在底层原生OpenGL上下文中将RESET_NOTIFICATION_STRATEGY_EXT 设置为LOSE_CONTEXT_ON_RESET_EXT 。随后，QOpenGLContext 将在每次调用makeCurrent()时通过glGetGraphicsResetStatusEXT() 监控状态。

另请参阅 create()。

bool QOpenGLContext::makeCurrent(QSurface *surface)

将上下文设为当前线程中的活动上下文，并基于给定的surface 。成功时返回true ；否则返回false 。后者可能发生在表面未暴露，或者由于应用程序被挂起等原因导致图形硬件不可用时。

如果surface 为nullptr ，则这等同于调用doneCurrent()。

请避免从与QOpenGLContext 实例所在线程不同的线程调用此函数。若需在其他线程中使用QOpenGLContext ，应先通过调用doneCurrent()（如有必要）确保该对象在当前线程中并非活动状态，然后在其他线程中使用前调用 moveToThread(otherThread)。

默认情况下，Qt 会进行一项检查，以确保线程亲和性符合上述条件。您仍可通过设置Qt::AA_DontCheckOpenGLContextThreadAffinity 应用程序属性来禁用此检查。请务必了解在所属线程之外使用 QObject 可能带来的后果，具体说明请参见QObject thread affinity 文档。

另请参阅 functions()、doneCurrent() 以及Qt::AA_DontCheckOpenGLContextThreadAffinity 。

template <typename QNativeInterface> QNativeInterface *QOpenGLContext::nativeInterface() const

返回该上下文中指定类型的本机接口。

该函数提供了对 `QOpenGLContext` 的平台特定功能的访问，这些功能在 `QNativeInterface ` 命名空间中定义：

如果请求的接口不可用，则返回一个 `nullptr ` 对象。

[static] QOpenGLContext::OpenGLModuleType QOpenGLContext::openGLModuleType()

返回底层的 OpenGL 实现类型。

在 OpenGL 实现未被动态加载的平台上，返回值在编译时确定且永远不会改变。

QScreen *QOpenGLContext::screen() const

返回该上下文所创建的屏幕。

另请参阅 setScreen()。

void QOpenGLContext::setFormat(const QSurfaceFormat &format)

设置 OpenGL 上下文应兼容的format 。需先调用create() 才能生效。

如果未通过此函数显式设置格式，则将使用QSurfaceFormat::defaultFormat()返回的格式。这意味着，当存在多个上下文时，可以在创建第一个上下文之前，通过一次调用QSurfaceFormat::setDefaultFormat()来替代对本函数的多次单独调用。

另请参阅 format()。

void QOpenGLContext::setScreen(QScreen *screen)

设置OpenGL上下文应适用的screen 。需先调用create()，该设置才会生效。

另请参阅 screen()。

void QOpenGLContext::setShareContext(QOpenGLContext *shareContext)

使该上下文与shareContext 共享纹理、着色器及其他OpenGL资源。您需要先调用create()，该设置才会生效。

另请参阅 shareContext()。

QOpenGLContext *QOpenGLContext::shareContext() const

返回创建此上下文时所使用的共享上下文。

如果底层平台无法支持所请求的共享操作，则返回 0。

另请参阅 setShareContext()。

QOpenGLContextGroup *QOpenGLContext::shareGroup() const

返回该上下文所属的共享组。

[static] bool QOpenGLContext::supportsThreadedOpenGL()

如果平台支持在主（GUI）线程之外进行 OpenGL 渲染，则返回true 。

该值由所使用的平台插件控制，也可能取决于图形驱动程序。

QSurface *QOpenGLContext::surface() const

返回当前上下文所关联的曲面。

这是作为参数传递给makeCurrent() 的表面。

void QOpenGLContext::swapBuffers(QSurface *surface)

交换surface 的后缓冲区和前缓冲区。

调用此函数以完成一帧 OpenGL 渲染，并在发出任何后续 OpenGL 命令之前（例如作为新帧的一部分），务必再次调用makeCurrent()。