class QOpenGLContext#

QOpenGLContext 类代表了本地 OpenGL 上下文，允许在 QSurface 上进行 OpenGL 渲染。 更多信息…

Inheritance diagram of PySide6.QtGui.QOpenGLContext

概述#

方法#

信号#

静态函数#

注解

该文档可能包含从 C++ 到 Python 自动翻译的代码片段。我们始终欢迎对片段翻译的贡献。如果您发现翻译问题，也可以通过在 https:/bugreports.qt.io/projects/PYSIDE 上创建票据来告知我们。

详细描述#

QOpenGLContext 表示底层OpenGL上下文的OpenGL状态。要设置上下文，设置屏幕和格式以匹配即将与之一起使用的表面或多个表面（如果需要，使用 setShareContext() 使它与其它上下文共享资源），然后调用 create() 。使用返回值或调用 isValid() 检查上下文是否成功初始化。

通过调用 makeCurrent() 可以为给定表面创建一个当前上下文。当OpenGL渲染完成后，调用 swapBuffers() 来交换表面的前后缓冲区，使新渲染的内容变得可见。为了支持某些平台，需要在开始渲染新帧之前再次调用 makeCurrent() ，在调用 swapBuffers() 之后。

如果上下文暂时不需要（例如，当应用程序未进行渲染时），删除它以释放资源可能很有用。您可以连接到 aboutToBeDestroyed() 信号来清理由 QOpenGLContext 本身以外的拥有权分配的资源。

一旦 QOpenGLContext 被设置为当前上下文，您可以通过使用Qt的OpenGL启用器（如 QOpenGLFunctions 、 QOpenGLBuffer、 QOpenGLShaderProgram和QOpenGLFramebufferObject）以平台无关的方式向其渲染。还可以直接使用平台的OpenGL API，而不使用Qt启用器，尽管这可能会牺牲可移植性。后者在需要使用OpenGL 1.x或OpenGL ES 1.x时是必要的。

有关OpenGL API的更多信息，请参阅官方的 OpenGL文档。

有关如何使用QOpenGLContext的示例，请参阅OpenGL窗口示例。

线程亲和性#

QOpenGLContext 可以通过 moveToThread() 方法移动到不同的线程。请不要从不属于 QOpenGLContext 对象的线程中调用 makeCurrent() 方法。一个上下文一次只能在一个线程和一个表面中有效，一个线程一次只能有一个上下文有效。

上下文资源共享#

如纹理和顶点缓冲区对象之类的资源可以在上下文之间共享。在调用 create() 之前使用 setShareContext() 指定上下文应共享这些资源。 QOpenGLContext 内部维护了一个可使用 shareGroup() 获取的 QOpenGLContextGroup 对象，可以用来找到给定共享组中的所有上下文。共享组由所有成功初始化并与其他共享组的现有上下文共享的上下文组成。非共享上下文有一个仅由一个上下文构成的共享组。

默认帧缓冲区#

在某些平台上，当前表面可能会使除 0 以外的帧缓冲区成为默认帧缓冲区。建议您使用 glBindFramebuffer(ctx->defaultFramebufferObject()) 而不是调用 glBindFramebuffer(0)，以确保您应用程序可以在不同平台上移植。但是，如果使用 glBindFramebuffer()，则会自动为您完成。

另请参阅

QOpenGLFunctions QOpenGLBufferQOpenGLShaderProgramQOpenGLFramebufferObject

class OpenGLModuleType#

此枚举定义了基本 OpenGL 实现的类型。

常量

描述

QOpenGLContext.LibGL

OpenGL

QOpenGLContext.LibGLES

OpenGL ES 2.0 或更高版本
__init__([parent=None])#
参数:

parent – QObject

使用父对象 parent 创建一个新的 OpenGL 上下文实例。

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

另请参阅

create() makeCurrent()

aboutToBeDestroyed()#

此信号在底层原生OpenGL上下文被销毁之前发出，以便用户可以清理OpenGL资源，这样在共享OpenGL上下文中就可以防止出现悬挂资源。

如果您想进行清理，请确保仅使用直接连接连接到信号。

注解

由于Python实例已经销毁，当它从QOpenGLWidget或QOpenGLWindow的析构函数中发出时，在Python中的Qt，这个信号将不会收到。我们建议在QWidget::hideEvent()中进行清理。

static areSharing(first, second)#
参数:
返回类型:

bool

如果第一个和第二个上下文正在共享OpenGL资源，则返回 true。

create()#
返回类型:

bool

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

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

如果您系统上的OpenGL实现不支持请求的OpenGL上下文版本，则 QOpenGLContext 将尝试创建最接近的匹配版本。实际创建的上下文属性可以通过QSurfaceFormat 函数返回的当前值进行查询。例如，如果您请求支持OpenGL 4.3 Core profile的上下文，但驱动程序和/或硬件只能支持版本3.2 Core profile的上下文，则您将得到一个3.2 Core profile的上下文。

如果原生上下文创建成功并且可以与 makeCurrent() ，swapBuffers() 等，则返回 true。

注解

如果上下文已经存在，此函数会先销毁现有的上下文，然后创建一个新的上下文。

另请参阅

makeCurrent() format()

static currentContext()#
返回类型:

QOpenGLContext

返回调用 makeCurrent() 的最后上下文，或者在当前线程中没有上下文时返回 None。

defaultFramebufferObject()#
返回类型:

int

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

在某些平台（例如，iOS）上，默认帧缓冲区对象取决于要渲染的表面，可能不是 0。因此，您应该调用 ctx->defaultFramebufferObject() 而不是调用 glBindFramebuffer(0)，这样您的应用程序才能在不同的 Qt 平台之间正常工作。

如果您在 QOpenGLFunctions 中使用 glBindFramebuffer()，您不需要担心这个问题，因为当传入 0 时，它将自动绑定当前上下文的默认帧缓冲区对象。

注解

渲染通过帧缓冲区对象的控件，如 QOpenGLWidget 和 QQuickWidget，在绘画活动时将覆盖此函数返回的值，因为那时“默认”帧缓冲区是控件相关联的背衬帧缓冲区，而不是顶层窗口表面的平台特定帧缓冲区。这确保了该函数和其他依赖于它的类的预期行为（例如，QOpenGLFramebufferObject::bindDefault() 或 QOpenGLFramebufferObject::release()）。

另请参阅

QOpenGLFramebufferObject

doneCurrent()#

用于调用 makeCurrent() 并且 0 表面作为参数的方便函数。

这会导致当前线程中没有上下文。

extensions()#
返回类型:

.QSetQByteArray

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

共享上下文或上下文必须是当前的。

另请参阅

hasExtension()

extraFunctions()#
返回类型:

QOpenGLExtraFunctions

获取此上下文的QOpenGLExtraFunctions实例。

QOpenGLContext提供了一种方便的方式来访问QOpenGLExtraFunctions，无需手动管理。

共享上下文或上下文必须是当前的。

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

注解

QOpenGLExtraFunctions包含运行时不一定存在的功能。运行时可用性取决于平台、图形驱动程序以及应用程序请求的OpenGL版本。

另请参阅

QOpenGLFunctions QOpenGLExtraFunctions

format()#
返回类型:

QSurfaceFormat

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

否则，返回请求的格式。

请求的格式和实际格式可能不同。请求一个给定的OpenGL版本并不意味着生成的上下文将正好指向请求的版本。只要驱动程序能够提供此类上下文，可以保证的是创建的上下文版本/配置文件/选项组合与请求兼容。

例如，请求OpenGL 3.x核心配置文件上下文可能生成OpenGL 4.x核心配置文件上下文。类似地，请求OpenGL 2.1可能生成启用弃用功能的OpenGL 3.0上下文。最后，根据驱动程序的不同，可能不支持版本，导致上下文创建失败或使用最高支持版本。

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

另请参阅

setFormat()

functions()#
返回类型:

QOpenGLFunctions

获取此上下文的QOpenGLFunctions实例。

QOpenGLContext提供了一种方便的方式来访问QOpenGLFunctions，无需手动管理。

共享上下文或上下文必须是当前的。

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

getProcAddress(procName)#
参数:

procName – QByteArray

返回类型:

QFunctionPointer

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

如果找不到该函数，则返回 None

getProcAddress(procName)
参数:

procName – str

返回类型:

QFunctionPointer

此函数是重载的。

static globalShareContext()#
返回类型:

QOpenGLContext

返回应用程序范围内的共享 OpenGL 上下文，如果存在则返回；否则返回 None。

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

注解

在创建 QGuiApplication 对象之前，必须在 QGuiApplication 上设置 Qt::AA_ShareOpenGLContexts 标志，否则 Qt 可能不会创建全局共享上下文。

警告

不要尝试在此函数返回的上下文中创建任何表面的当前上下文。相反，您可以创建一个与全局上下文共享的新上下文，然后使新上下文成为当前上下文。

另请参阅

setShareContext() makeCurrent()

hasExtension(extension)#
参数:

extension – QByteArray

返回类型:

bool

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

共享上下文或上下文必须是当前的。

另请参阅

extensions()

isOpenGLES()#
返回类型:

bool

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

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

isValid()#
返回类型:

bool

返回此上下文是否有效，即是否已成功创建。

在某些平台上，对于先前成功创建的上下文，返回值为 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()

makeCurrent(surface)#
参数:

surface – QSurface

返回类型:

bool

在当前线程中，针对指定的 surface 使上下文成为当前上下文。如果成功，则返回 true；否则返回 false。后者可能发生，例如，如果表面没有公开，或者由于应用程序被挂起等原因，图形硬件不可用。

如果 surface 是 None，这等价于调用 doneCurrent()。

避免从 QOpenGLContext 实例所在之外的线程调用此函数。如果您希望从不同线程使用 QOpenGLContext，您应首先确保它在当前线程中不是当前的，如果没有必要，可以通过调用 doneCurrent()。然后在使用它之前调用 moveToThread(otherThread)。

默认情况下，Qt会在线程亲和性上执行一个检查，以强制执行上述条件。仍然可以通过设置应用程序属性 Qt::AA_DontCheckOpenGLContextThreadAffinity 来禁用这个检查。在使用 QObjects 超出它们生活线程的情况之前，务必了解如 QObject 线程亲和性文档中解释的后果。

另请参阅

functions() doneCurrent() AA_DontCheckOpenGLContextThreadAffinity

static openGLModuleType()#
返回类型:

OpenGLModuleType

返回底层 OpenGL 实现类型。

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

注解

桌面 OpenGL 实现也可能能够创建 ES 兼容的上下文。因此，在大多数情况下，更合适的是检查 renderableType() 或使用方便函数 isOpenGLES()。

注解

此函数需要 QGuiApplication 实例已创建。

resolveInterface(name, revision)#
参数:

  • name – str

  • revision – int

返回类型:

void

screen()#
返回类型:

QScreen

返回创建上下文的屏幕。

另请参阅

setScreen()

setFormat(format)#
参数:

format – QSurfaceFormat

设置OpenGL上下文应兼容的格式。在它生效之前，你需要调用create()方法。

当格式不是通过此函数显式设置时，将使用defaultFormat()返回的格式。这意味着在存在多个上下文的情况下，单个对这一函数的调用可以通过创建第一个上下文之前对setDefaultFormat()的单个调用来替换。

另请参阅

format()

setScreen(screen)#
参数:

screen – QScreen

设置OpenGL上下文应有效的屏幕。在它生效之前，你需要调用create()方法。

另请参阅

screen()

setShareContext(shareContext)#
参数:

shareContext – QOpenGLContext

使此上下文与shareContext共享纹理、着色器和其他OpenGL资源。在它生效之前，你需要调用create()方法。

另请参阅

shareContext()

shareContext()#
返回类型:

QOpenGLContext

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

如果底层平台无法支持请求的共享，这将返回0。

另请参阅

setShareContext()

shareGroup()#
返回类型:

QOpenGLContextGroup

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

静态supportsThreadedOpenGL()#
返回类型:

bool

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

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

surface()#
返回类型:

QSurface

返回上下文中已激活的表面。

这是传给makeCurrent()方法的参数。

swapBuffers(surface)#
参数:

surface – QSurface

交换surface的前后缓冲区。

调用此方法完成一帧的OpenGL渲染，并且在发出任何进一步的OpenGL命令之前，务必再次调用makeCurrent()，例如作为新帧的一部分。