PySide6.QtGui.QSurfaceFormat

class QSurfaceFormat

QSurfaceFormat 类表示 QSurface 的格式。更多…

概要

方法

静态函数

注意

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

详细描述

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

注意

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

class FormatOption

(继承自 enum.Flag) 此枚举包含用于 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

开放矢量图形渲染
class OpenGLContextProfile

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

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

请注意，核心配置文件可能仍然包含已弃用并计划在更高版本中移除的功能。要访问在设置的OpenGL版本中核心配置文件的已弃用功能，您可以使用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__()

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

注意

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

__init__(options)
Parameters:

options – FormatOption 的组合

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

__init__(other)
Parameters:

其他 – QSurfaceFormat

构造other的副本。

alphaBufferSize()
Return type:

整数

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

另请参阅

setAlphaBufferSize()

blueBufferSize()
Return type:

整数

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

另请参阅

setBlueBufferSize()

colorSpace()
Return type:

QColorSpace

返回颜色空间。

另请参阅

setColorSpace()

static defaultFormat()
Return type:

QSurfaceFormat

返回全局默认的表面格式。

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

另请参阅

setDefaultFormat()

depthBufferSize()
Return type:

整数

返回深度缓冲区的大小。

另请参阅

setDepthBufferSize()

greenBufferSize()
Return type:

整数

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

另请参阅

setGreenBufferSize()

hasAlpha()
Return type:

布尔

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

这意味着表面可能会用于每像素半透明效果。

majorVersion()
Return type:

整数

返回主要的OpenGL版本。

默认版本是2.0。

另请参阅

setMajorVersion()

minorVersion()
Return type:

整数

返回次要的OpenGL版本。

另请参阅

setMinorVersion()

__ne__(rhs)
Parameters:

rhs – QSurfaceFormat

Return type:

布尔

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

__eq__(rhs)
Parameters:

rhs – QSurfaceFormat

Return type:

布尔

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

options()
Return type:

FormatOption的组合

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

profile()
Return type:

OpenGLContextProfile

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

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

另请参阅

setProfile()

redBufferSize()
Return type:

整数

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

另请参阅

setRedBufferSize()

renderableType()
Return type:

RenderableType

获取可渲染类型。

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

另请参阅

setRenderableType()

samples()
Return type:

整数

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

另请参阅

setSamples()

setAlphaBufferSize(size)
Parameters:

size – int

设置颜色缓冲区的alpha通道所需的size位数。

另请参阅

alphaBufferSize()

setBlueBufferSize(size)
Parameters:

size – int

设置颜色缓冲区蓝色通道所需的size位数。

另请参阅

blueBufferSize()

setColorSpace(colorSpace)
Parameters:

colorSpace – ColorSpace

注意

此函数已弃用。

这是一个重载函数。

请使用 setColorSpace ( QColorSpace ) 代替。

将色彩空间设置为预定义值之一。

另请参阅

colorSpace()

setColorSpace(colorSpace)
Parameters:

colorSpace – QColorSpace

设置首选的colorSpace。

例如，这允许在支持的平台上请求具有默认帧缓冲区的窗口，这些窗口能够支持sRGB。

注意

当请求的颜色空间不被平台支持时，请求将被忽略。在窗口创建后查询QSurfaceFormat以验证颜色空间请求是否被接受。

注意

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

另请参阅

colorSpace()

static setDefaultFormat(format)
Parameters:

格式 – QSurfaceFormat

设置全局默认表面format。

此格式在QOpenGLContext、QWindow、QOpenGLWidget及类似类中默认使用。

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

注意

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

另请参阅

defaultFormat()

setDepthBufferSize(size)
Parameters:

size – int

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

另请参阅

depthBufferSize()

setGreenBufferSize(size)
Parameters:

size – int

设置颜色缓冲区绿色通道的期望size（以位为单位）。

另请参阅

greenBufferSize()

setMajorVersion(majorVersion)
Parameters:

majorVersion – int

设置所需的major OpenGL版本。

另请参阅

majorVersion()

setMinorVersion(minorVersion)
Parameters:

minorVersion – int

设置所需的 minor OpenGL 版本。

默认版本是2.0。

另请参阅

minorVersion()

setOption(option[, on=true])
Parameters:

如果on为真，则设置格式选项option；否则，清除该选项。

要验证是否遵守了某个选项，请在表面/上下文创建后，将实际格式与请求的格式进行比较。

setOptions(options)
Parameters:

options – FormatOption 的组合

将格式选项设置为 options。

要验证是否遵守了某个选项，请在表面/上下文创建后，将实际格式与请求的格式进行比较。

另请参阅

options() testOption()

setProfile(profile)
Parameters:

配置文件 – OpenGLContextProfile

设置所需的OpenGL上下文profile。

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

另请参阅

profile()

setRedBufferSize(size)
Parameters:

size – int

设置颜色缓冲区红色通道的所需size（以位为单位）。

另请参阅

redBufferSize()

setRenderableType(type)
Parameters:

类型 – RenderableType

设置所需的可渲染type。

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

另请参阅

renderableType()

setSamples(numSamples)
Parameters:

numSamples – int

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

另请参阅

samples()

setStencilBufferSize(size)
Parameters:

size – int

将首选模板缓冲区大小设置为 size 位。

另请参阅

stencilBufferSize()

setStereo(enable)
Parameters:

enable – 布尔值

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

立体声缓冲默认是禁用的。

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

另请参阅

stereo()

setSwapBehavior(behavior)
Parameters:

行为 – SwapBehavior

设置表面的交换行为。

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

另请参阅

swapBehavior()

setSwapInterval(interval)
Parameters:

interval – 整数

设置首选的交换间隔。交换间隔指定在发生缓冲区交换之前显示的最少视频帧数。这可以用于将GL绘图同步到窗口的屏幕垂直刷新。

将interval值设置为0将关闭垂直刷新同步，任何大于0的值将开启垂直同步。将interval设置为更高的值，例如10，将在每次缓冲区交换之间进行10次垂直回扫。

默认间隔为1。

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

另请参阅

swapInterval()

setVersion(major, minor)
Parameters:

  • major – int

  • minor – int

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

默认版本是2.0。

另请参阅

version()

stencilBufferSize()
Return type:

整数

返回模板缓冲区的位大小。

另请参阅

setStencilBufferSize()

stereo()
Return type:

布尔

如果启用了立体声缓冲，则返回true；否则返回false。立体声缓冲默认是禁用的。

另请参阅

setStereo()

swapBehavior()
Return type:

SwapBehavior

返回配置的交换行为。

另请参阅

setSwapBehavior()

swapInterval()
Return type:

整数

返回交换间隔。

另请参阅

setSwapInterval()

testOption(option)
Parameters:

选项 – FormatOption

Return type:

布尔

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

另请参阅

options()

version()
Return type:

.std.pairint,int

返回一个表示OpenGL版本的QPair。

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

另请参阅

setVersion()