PySide6.QtGui.QOpenGLContext

class QOpenGLContext

QOpenGLContext 类代表一个原生的 OpenGL 上下文，使得在 QSurface 上进行 OpenGL 渲染成为可能。更多…

PySide6.QtGui.QOpenGLContext的继承图

概要

方法

信号

静态函数

注意

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

详细描述

QOpenGLContext 表示底层 OpenGL 上下文的 OpenGL 状态。要设置上下文，请设置其屏幕和格式，使其与上下文要使用的表面或表面的屏幕和格式匹配，如果需要，使用 setShareContext() 使其与其他上下文共享资源，最后调用 create()。使用返回值或 isValid() 来检查上下文是否成功初始化。

可以通过调用makeCurrent()使上下文针对给定表面变为当前状态。当OpenGL渲染完成后，调用swapBuffers()来交换表面的前后缓冲区，以便新渲染的内容变得可见。为了能够支持某些平台，QOpenGLContext要求你在调用swapBuffers()后，在开始渲染新帧之前再次调用makeCurrent()。

如果上下文暂时不需要，例如当应用程序没有渲染时，删除它以释放资源可能是有用的。您可以连接到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内部跟踪一个QOpenGLContextGroup对象，可以通过shareGroup()访问，该对象可用于查找给定共享组中的所有上下文。共享组由所有已成功初始化并与共享组中现有上下文共享的上下文组成。非共享上下文的共享组仅包含一个上下文。

默认帧缓冲

在某些平台上，根据当前表面，默认的帧缓冲可能不是0。建议您使用glBindFramebuffer(ctx-> defaultFramebufferObject() )，而不是调用glBindFramebuffer(0)，以确保您的应用程序在不同平台之间具有可移植性。然而，如果您使用glBindFramebuffer()，这将自动为您完成。

警告

WebAssembly

我们建议在整个QSurface的生命周期内，只有一个QOpenGLContext与QSurface保持当前状态。如果使用多个上下文，重要的是要理解在WebAssembly平台下，多个QOpenGLContext实例可能由相同的本地上下文支持。因此，在两个QOpenGLContext对象上使用相同的QSurface调用makeCurrent()可能不会在第二次调用时切换到不同的本地上下文。结果，第二次makeCurrent()之后所做的任何OpenGL状态更改也可能改变第一个QOpenGLContext的状态，因为它们都由相同的本地上下文支持。

注意

这意味着在使用现有的基于OpenGL的Qt代码针对WebAssembly时，可能需要一些移植工作以适应这些限制。

另请参阅

QOpenGLFunctions QOpenGLBufferQOpenGLShaderProgramQOpenGLFramebufferObject

class OpenGLModuleType

此枚举定义了底层OpenGL实现的类型。

常量

描述

QOpenGLContext.LibGL

OpenGL

QOpenGLContext.LibGLES

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

父对象 – QObject

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

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

另请参阅

create() makeCurrent()

aboutToBeDestroyed()

在底层的原生OpenGL上下文被销毁之前，会发出此信号，以便用户可以清理OpenGL资源，这些资源在共享OpenGL上下文的情况下可能会被遗留下来。

如果您希望使上下文成为当前上下文以进行清理，请确保仅使用直接连接连接到信号。

注意

在Qt for Python中，当从QOpenGLWidget或QOpenGLWindow的析构函数中发出此信号时，由于Python实例已被销毁，因此不会接收到该信号。我们建议在QWidget::hideEvent()中进行清理操作。

static areSharing(first, second)
Parameters:
Return type:

布尔

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

create()
Return type:

布尔

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

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

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

如果原生上下文成功创建并准备好与makeCurrent()、swapBuffers()等一起使用，则返回true。

注意

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

另请参阅

makeCurrent() format()

static currentContext()
Return type:

QOpenGLContext

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

defaultFramebufferObject()
Return type:

整数

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

在某些平台（例如，iOS）上，默认的帧缓冲对象取决于正在渲染的表面，并且可能与0不同。因此，如果您希望您的应用程序在不同的Qt平台上工作，您应该调用glBindFramebuffer(ctx->defaultFramebufferObject())，而不是调用glBindFramebuffer(0)。

如果你在QOpenGLFunctions中使用glBindFramebuffer()，你不需要担心这个问题，因为当传递0时，它会自动绑定当前上下文的defaultFramebufferObject()。

注意

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

另请参阅

QOpenGLFramebufferObject

doneCurrent()

方便函数，用于调用带有0表面的makeCurrent。

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

extensions()
Return type:

.QSetQByteArray

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

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

另请参阅

hasExtension()

extraFunctions()
Return type:

QOpenGLExtraFunctions

获取此上下文的QOpenGLExtraFunctions实例。

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

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

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

注意

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

另请参阅

QOpenGLFunctions QOpenGLExtraFunctions

format()
Return type:

QSurfaceFormat

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

否则，返回请求的格式。

请求的格式和实际的格式可能有所不同。请求一个特定的OpenGL版本并不意味着生成的上下文将完全针对所请求的版本。只要驱动程序能够提供这样的上下文，就可以保证创建的上下文的版本/配置文件/选项组合与请求兼容。

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

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

另请参阅

setFormat()

functions()
Return type:

QOpenGLFunctions

获取此上下文的QOpenGLFunctions实例。

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

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

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

getProcAddress(procName)
Parameters:

procName – QByteArray

Return type:

QFunctionPointer

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

如果没有找到这样的函数，则返回 None。

getProcAddress(procName)
Parameters:

procName – 字符串

Return type:

QFunctionPointer

这是一个重载函数。

static globalShareContext()
Return type:

QOpenGLContext

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

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

注意

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

警告

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

另请参阅

setShareContext() makeCurrent()

hasExtension(extension)
Parameters:

扩展 – QByteArray

Return type:

布尔

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

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

另请参阅

extensions()

isOpenGLES()
Return type:

布尔

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

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

isValid()
Return type:

布尔

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

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

表面 – QSurface

Return type:

布尔

在当前线程中使上下文针对给定的surface变为当前状态。如果成功，则返回true；否则返回false。后者可能发生在表面未暴露，或者由于应用程序被挂起等原因导致图形硬件不可用的情况下。

如果 surface 是 None，这相当于调用 doneCurrent()。

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

默认情况下，Qt 会强制执行上述线程亲和性检查。仍然可以通过设置 Qt::AA_DontCheckOpenGLContextThreadAffinity 应用程序属性来禁用此检查。请务必理解从对象所在线程之外使用 QObjects 的后果，如 QObject 线程亲和性文档中所述。

另请参阅

functions() doneCurrent() AA_DontCheckOpenGLContextThreadAffinity

static openGLModuleType()
Return type:

OpenGLModuleType

返回底层的OpenGL实现类型。

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

注意

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

注意

此函数要求QGuiApplication实例已经创建。

resolveInterface(name, revision)
Parameters:

  • name – str

  • revision – int

Return type:

void

screen()
Return type:

QScreen

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

另请参阅

setScreen()

setFormat(format)
Parameters:

格式 – QSurfaceFormat

设置OpenGL上下文应兼容的format。您需要在生效之前调用create()。

当未通过此函数明确设置格式时，将使用defaultFormat()返回的格式。这意味着在拥有多个上下文时，可以在创建第一个上下文之前，通过一次调用setDefaultFormat()来替换对此函数的单独调用。

另请参阅

format()

setScreen(screen)
Parameters:

屏幕 – QScreen

设置OpenGL上下文应有效的screen。在生效之前，您需要调用create()。

另请参阅

screen()

setShareContext(shareContext)
Parameters:

shareContext – QOpenGLContext

使此上下文与shareContext共享纹理、着色器和其他OpenGL资源。您需要调用create()才能使其生效。

另请参阅

shareContext()

shareContext()
Return type:

QOpenGLContext

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

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

另请参阅

setShareContext()

shareGroup()
Return type:

QOpenGLContextGroup

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

static supportsThreadedOpenGL()
Return type:

布尔

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

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

surface()
Return type:

QSurface

返回上下文已与之成为当前的表面。

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

swapBuffers(surface)
Parameters:

表面 – QSurface

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

调用此函数以完成一帧OpenGL渲染，并确保在发出任何进一步的OpenGL命令之前再次调用makeCurrent()，例如作为新帧的一部分。