class QSurfaceFormat#

QSurfaceFormat 类代表了一个 QSurface 的格式。更多...

摘要#

方法#

静态函数

注意

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

详细描述

格式包括颜色缓冲区、红、绿、蓝的大小；alpha缓冲区的大小；深度和模板缓冲区的大小；以及每个像素多采样的样本数。此外，格式还包括表面配置参数，例如用于渲染的OpenGL配置文件和版本，是否启用立体缓冲区以及交换行为。

注意

在排查上下文或窗口格式问题时，启用日志类别qt.qpa.gl可能会有所帮助。根据平台，这可能会在OpenGL初始化和原生视觉或帧缓冲区配置时打印出有用的调试信息，这对于QSurfaceFormat的映射很有用。

class FormatOption#

(继承自 enum.Flag) 此枚举包含与<_codes="xref py py-class docutils literal notranslate">QSurfaceFormat一起使用的格式选项。

常量

描述

QSurfaceFormat.StereoBuffers

用于在表面格式中请求立体缓冲区。

QSurfaceFormat.DebugContext

用于请求具有额外调试信息的调试上下文。

QSurfaceFormat.DeprecatedFunctions

用于请求在OpenGL上下文配置文件中包含已弃用的函数。如果不指定，您应该获取一个向前兼容的上下文，其中标记为已弃用的功能没有任何支持。这需要OpenGL版本3.0或更高。

QSurfaceFormat.ResetNotification

启用OpenGL上下文重置的提醒。然后可以通过上下文的isValid()函数查询其状态。注意，不设置此标志不能保证不会发生上下文状态丢失。另外，某些实现可能会选择无论此标志如何都报告上下文丢失。支持动态启用对上下文丢失进行监控的平台（如带有WGL的Windows或带有GLX的Linux/X11（xcb）），将在每个makeCurrent()调用中监控状态。有关更多信息，请参阅isValid()。

QSurfaceFormat.ProtectedContent

启用对受保护内容的访问。这允许 GPU 在受保护资源（表面、缓冲区、纹理）上操作，例如DRM受保护的视频内容。目前仅对EGL实现。
class SwapBehavior#

此枚举由QSurfaceFormat使用，以指定表面的交换行为。交换行为对应用程序来说通常是透明的，但它影响渲染延迟和吞吐量等因素。

常量

描述

QSurfaceFormat.DefaultSwapBehavior

平台默认、未指定的交换行为。

QSurfaceFormat.SingleBuffer

用于请求单缓冲区，这可能导致在将OpenGL渲染直接绘制到屏幕而无需中间离屏缓冲区时出现闪烁。

QSurfaceFormat.DoubleBuffer

这是桌面平台上典型的默认交换行为，由一个后缓冲区和前缓冲区组成。渲染是在后缓冲区进行的，然后后缓冲区和前缓冲区进行交换，或者后缓冲区的内容复制到前缓冲区，具体取决于实现。

QSurfaceFormat.TripleBuffer

有时使用这种交换行为来降低渲染速率仅略高于屏幕刷新率时跳帧的风险。根据平台的不同，它可能还会由于改进的流水线操作而略微提高GPU的效率。三缓冲区以额外一帧内存使用和延迟为代价，并且可能不支持某些底层平台。
class RenderableType#

此枚举指定表面的渲染后端。

常量

描述

QSurfaceFormat.DefaultRenderableType

默认、未指定的渲染方法

QSurfaceFormat.OpenGL

桌面OpenGL渲染

QSurfaceFormat.OpenGLES

OpenGL ES 2.0渲染

QSurfaceFormat.OpenVG

Open Vector Graphics渲染
class OpenGLContextProfile#

此枚举用于指定OpenGL上下文配置文件，与setMajorVersion()和setMinorVersion()配合使用。

配置文件在OpenGL 3.2及以上版本中公开，用于在受限制的核心配置文件和可能包含已废弃支持功能的兼容性配置文件之间进行选择。

请注意，核心配置文件可能仍然包含已废弃的功能，并在更高版本中删除。要获取设置OpenGL版本的core配置文件的废弃功能，可以使用QSurfaceFormat的格式选项DeprecatedFunctions 。

常量

描述

QSurfaceFormat.NoProfile

OpenGL版本低于3.2。对于3.2和更高版本，这是与CoreProfile相同的。

QSurfaceFormat.CoreProfile

OpenGL版本3.0中废弃的功能不可用。

QSurfaceFormat.CompatibilityProfile

OpenGL早期版本的功能可用。
class ColorSpace#

此枚举用于指定首选的颜色空间，控制窗口关联的默认帧缓冲区是否能够使用指定的编码进行更新和混合，而不是标准的线性操作。

常量

描述

QSurfaceFormat.DefaultColorSpace

默认的，未指定的颜色空间。

QSurfaceFormat.sRGBColorSpace

当平台支持GL_ARB_framebuffer_sRGB或GL_EXT_framebuffer_sRGB，且此值被设置时，窗口将被创建为具有sRGB能力的默认帧缓冲区。注意，某些平台即使在未明确请求的情况下，也可能返回具有sRGB能力的默认帧缓冲区的窗口。
__init__(options)#
参数：

options – FormatOption的组合

使用给定的格式options构建一个QSurfaceFormat。

__init__()

构建一个默认初始化的QSurfaceFormat。

注意

默认情况下，请求OpenGL 2.0，因为这样可以提供最高等级的平台和OpenGL实现之间的可移植性。

__init__(other)
参数：

other – QSurfaceFormat

构建other的副本。

alphaBufferSize()#
返回类型：

int

获取颜色缓冲区中alpha通道的位数。

另请参阅

setAlphaBufferSize()

blueBufferSize()#
返回类型：

int

获取颜色缓冲区中蓝通道的位数。

另请参阅

setBlueBufferSize()

colorSpace()#
返回类型：

QColorSpace

返回颜色空间。

另请参阅

setColorSpace()

static defaultFormat()#
返回类型：

QSurfaceFormat

返回全局默认表面格式。

当未调用setDefaultFormat()时，这是一个默认构造的QSurfaceFormat .

另请参阅

setDefaultFormat()

depthBufferSize()#
返回类型：

int

返回深度缓冲区大小。

另请参阅

setDepthBufferSize()

greenBufferSize()#
返回类型：

int

获取颜色缓冲区中绿通道的位数。

另请参阅

setGreenBufferSize()

hasAlpha()#
返回类型：

bool

如果alpha缓冲区大小大于零，返回true。

这意味着表面可能会用于每个像素的不透明度效果。

majorVersion()#
返回类型：

int

返回主要OpenGL版本。

默认版本是2.0。

另请参阅

setMajorVersion()

minorVersion()#
返回类型：

int

返回次要OpenGL版本。

另请参阅

setMinorVersion()

__ne__(rhs)#
参数：

rhs – QSurfaceFormat

返回类型：

bool

如果两个QSurfaceFormat对象lhs和rhs的选项都相等，则返回false；否则返回true。

__eq__(rhs)#
参数：

rhs – QSurfaceFormat

返回类型：

bool

如果两个 QSurfaceFormat 对象 lhs 和 rhs 的所有选项都相等，则返回 true。

options()#
返回类型：

组合了 FormatOption

返回当前设置的格式选项。

profile()#
返回类型：

OpenGL上下文配置文件

获取配置的OpenGL上下文配置文件。

如果请求的OpenGL版本小于3.2，则忽略该设置。

另请参阅

setProfile()

redBufferSize()#
返回类型：

int

获取颜色缓冲区红色通道的位大小。

另请参阅

setRedBufferSize()

renderableType()#
返回类型：

可渲染类型

获取可渲染类型。

在桌面OpenGL、OpenGL ES和 OpenVG 之间进行选择。

另请参阅

setRenderableType()

samples()#
返回类型：

int

在启用多采样时返回每像素的样本数，或者在禁用多采样时返回 -1。默认返回值为 -1。

另请参阅

setSamples()

setAlphaBufferSize(size)#
参数：

size – int

设置颜色缓冲区alpha通道期望的位大小。

另请参阅

alphaBufferSize()

setBlueBufferSize(size)#
参数：

size – int

设置颜色缓冲区蓝色通道期望的位大小。

另请参阅

blueBufferSize()

setColorSpace(colorSpace)#
参数：

colorSpace – QColorSpace

设置首选的 colorSpace。

例如，这可以在支持的平台请求默认具有sRGB功能的光栅窗口。

注意

当请求的色域不被平台支持时，请求将被忽略。创建窗口后在 QSurfaceFormat 中进行查询，以验证色域请求是否可能被接受。

注意

此设置控制窗口的默认帧缓冲区是否能够在给定的色域中更新和合并。这本身不会改变应用程序的输出。应用程序的渲染代码仍然需要通过适当的OpenGL调用来选择进入，以便在给定的色域中执行更新和合并，而不是使用标准线性操作。

另请参阅

colorSpace()

setColorSpace(colorSpace)
参数：

colorSpace – ColorSpace

注意

此函数已弃用。

这是一个重载函数。

使用 setColorSpace ( QColorSpace ) Instead。

将色域设置为预定义值之一。

另请参阅

colorSpace()

static setDefaultFormat(format)#
参数：

format – QSurfaceFormat

设置全局默认表面 format。

此格式默认用于 QOpenGLContext，QWindow，QOpenGLWidget 等类似类。

可以使用相关类的 own setFormat() 函数按实例基础覆盖它。然而，通常在应用程序启动时设置所有窗口的格式更加方便。这也保证了在需要共享上下文的情况下正确行为，因为通过此函数设置格式可以保证所有上下文和表面，甚至是 Qt 内部创建的表面，都将使用相同的格式。

注意

当设置 Qt::AA_ShareOpenGLContexts 时，强烈建议在构造 QGuiApplication 或 QApplication 之前调用此函数。否则 format 不会被应用于全局共享上下文，并且可能引发后续的上下文共享问题。

另请参阅

defaultFormat()

setDepthBufferSize(size)#
参数：

size – int

设置最小深度缓冲区大小为 size。

另请参阅

depthBufferSize()

setGreenBufferSize(size)#
参数：

size – int

设置颜色缓冲区绿色通道期望的 size 位。

另请参阅

greenBufferSize()

setMajorVersion(majorVersion)#
参数：

majorVersion – int

设置期望的 major OpenGL 版本。

另请参阅

majorVersion()

setMinorVersion(minorVersion)#
参数：

minorVersion – int

设置期望的 minor OpenGL 版本。

默认版本是2.0。

另请参阅

minorVersion()

setOption(option[, on=true])#
参数：

如果 on 是 true，则设置格式选项 option；否则，清除选项。

为了验证是否遵守了选项，在创建表面/上下文后，对比实际情况与请求的格式。

setOptions(options)#
参数：

options – FormatOption的组合

将格式选项设置为 options。

为了验证是否遵守了选项，在创建表面/上下文后，对比实际情况与请求的格式。

另请参阅

options() testOption()

setProfile(profile)#
参数：

profile – OpenGLContextProfile

设置期望的 OpenGL 上下文 profile。

如果请求的OpenGL版本小于3.2，则忽略该设置。

另请参阅

profile()

setRedBufferSize(size)#
参数：

size – int

设置颜色缓冲区红色通道的期望位数大小。

另请参阅

redBufferSize()

setRenderableType(type)#
参数：

type – RenderableType

设置预期的可渲染 type。

在桌面OpenGL、OpenGL ES和 OpenVG 之间进行选择。

另请参阅

renderableType()

setSamples(numSamples)#
参数：

numSamples – int

当启用多采样时，设置每个像素期望的样本数为 numSamples。默认情况下，多采样是禁用的。

另请参阅

samples()

setStencilBufferSize(size)#
参数：

size – int

设置期望的模板缓冲区大小为 size 位。

另请参阅

stencilBufferSize()

setStereo(enable)#
参数：

enable – bool

如果 enable 为true则启用立体缓冲；否则禁用立体缓冲。

默认情况下，立体缓冲是禁用的。

立体缓冲提供了额外的颜色缓冲区，用于生成左眼和右眼图像。

另请参阅

stereo()

setSwapBehavior(behavior)#
参数：

behavior – SwapBehavior

设置表面的交换 behavior。

交换行为指定是否需要单缓冲、双缓冲或三缓冲。默认值，DefaultSwapBehavior ，给出了平台的默认交换行为。

另请参阅

swapBehavior()

setSwapInterval(interval)#
参数：

interval – int

设置首选的交换间隔。交换间隔指定在缓冲区交换发生前所需显示的最小视频帧数。这可以用来自动将GL绘图与屏幕的垂直刷新同步。

将 interval 的值设置为0将关闭垂直刷新同步，任何大于0的值将开启垂直同步。将 interval 设置为一个更高的值，例如10，将在每次缓冲区交换之间产生10次垂直重绘。

默认间隔为1。

修改交换间隔可能不支持底层平台。在这种情况下，请求将被静默忽略。

另请参阅

swapInterval()

setVersion(major, minor)#
参数：

  • major – int

  • minor – int

设置所需的 major 和 minor OpenGL 版本。

默认版本是2.0。

另请参阅

version()

stencilBufferSize()#
返回类型：

int

返回位图大小。

另请参阅

setStencilBufferSize()

stereo()#
返回类型：

bool

如果启用了立体缓冲，则返回 true；否则返回 false。默认情况下禁用立体缓冲。

另请参阅

setStereo()

swapBehavior()#
返回类型：

交换行为

返回配置的交换行为。

另请参阅

setSwapBehavior()

swapInterval()#
返回类型：

int

返回交换间隔。

另请参阅

setSwapInterval()

testOption(option)#
参数：

option – FormatOption

返回类型：

bool

如果格式选项 option 已设置，则返回 true；否则返回 false。

另请参阅

options()

version()#
返回类型：

.std.pairint,int

返回表示 OpenGL 版本的 QPair<int, int>。

用于版本检查，例如 format.version() >= qMakePair(3, 2)

另请参阅

setVersion()