PySide6.QtQuick.QQuickWindow

class QQuickWindow

QQuickWindow 类提供了一个用于显示图形化 QML 场景的窗口。More_…

PySide6.QtQuick.QQuickWindow 的继承图

继承者： QQuickView

概要

属性

  • activeFocusItemᅟ - 当前具有活动焦点的项目，如果没有具有活动焦点的项目，则为null

  • colorᅟ - 用于在每帧开始时清除颜色缓冲区

  • contentItemᅟ - 场景的不可见根项目

方法

插槽

信号

静态函数

注意

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

详细描述

QQuickWindow 提供了与QQuickItems场景交互和显示所需的图形场景管理。

一个 QQuickWindow 总是有一个不可见的根项目。要将项目添加到此窗口中，请将项目重新父级到根项目或场景中的现有项目。

为了轻松显示来自QML文件的场景，请参见QQuickView。

渲染

QQuickWindow 使用场景图来表示需要渲染的内容。这个场景图与 QML 场景是分离的，并且可能存在于另一个线程中，具体取决于平台的实现。由于渲染场景图独立于 QML 场景存在，它也可以完全释放而不影响 QML 场景的状态。

在QML场景首次渲染到屏幕之前，sceneGraphInitialized()信号会在渲染线程上发出。如果渲染场景图已被释放，该信号将在下一帧渲染之前再次发出。一个可见的、屏幕上的QQuickWindow由render loop内部驱动，场景图中提供了多种实现。有关场景图渲染过程的详细信息，请参阅Qt Quick Scene Graph。

默认情况下，QQuickWindow 使用加速的3D图形API（如OpenGL或Vulkan）进行渲染。有关场景图后端和受支持的图形API的详细概述，请参见场景图适配。

警告

至关重要的是，图形操作和与场景图的交互必须仅在渲染线程上进行，主要是在updatePaintNode()阶段。

警告

由于许多与渲染相关的信号是从渲染线程发出的，因此应使用Qt::DirectConnection进行连接。

与加速3D图形API的集成

可以直接将OpenGL、Vulkan、Metal或Direct3D 11调用集成到QQuickWindow中，只要QQuickWindow和底层场景图使用相同的API进行渲染。要访问本机图形对象，例如设备或上下文对象句柄，请使用QSGRendererInterface。可以通过调用rendererInterface()从QQuickWindow查询QSGRendererInterface的实例。这种集成的使能器是beforeRendering()、beforeRenderPassRecording()、afterRenderPassRecording()以及相关的信号。这些信号允许渲染底层或覆盖层。或者，QSGOpenGLTexture、QSGVulkanTexture和其他类似类允许将现有的本机纹理或图像对象包装在QSGTexture中，然后可以与场景图一起使用。

无加速渲染

还提供了一种有限的、基于纯软件的渲染路径。使用software后端时，许多Qt Quick功能不可用，依赖这些功能的QML项目将完全无法渲染。同时，这使得QQuickWindow在没有3D图形API的系统上也能正常工作。更多详情请参见Qt Quick Software Adaptation。

重定向渲染

一个QQuickWindow不一定由屏幕上的原生窗口支持。渲染可以被重定向到目标自定义渲染目标，例如给定的原生纹理。这是通过与QQuickRenderControl类以及诸如setRenderTarget()、setGraphicsDevice()和setGraphicsConfiguration()等函数结合实现的。

在这种情况下，QQuickWindow 代表场景，并提供了渲染帧的基础设施。它不会被渲染循环和原生窗口所支持。相反，在这种情况下，应用程序驱动渲染，有效地替代了渲染循环。这允许生成图像序列，渲染到纹理中以供外部3D引擎使用，或在VR环境中渲染Qt Quick内容。

资源管理

QML 会尝试缓存图像和场景图节点以提高性能，但在一些低内存情况下，可能需要积极释放这些资源。releaseResources() 函数可用于强制清理某些资源，特别是那些被缓存且可以在需要时重新创建的资源。

此外，调用releaseResources()可能会导致释放整个场景图及其相关的图形资源。当这种情况发生时，sceneGraphInvalidated()信号将被发出。这种行为由setPersistentGraphics()和setPersistentSceneGraph()函数控制。

注意

所有带有QSG前缀的类应仅在场景图的渲染线程上使用。有关更多信息，请参见场景图和渲染。

曝光与可见性

当一个QQuickWindow实例被故意隐藏使用hide()或setVisible(false)时，它将停止渲染，并且其场景图和图形上下文也可能被释放。这取决于setPersistentGraphics()和setPersistentSceneGraph()配置的设置。这方面的行为与显式调用releaseResources()函数相同。窗口也可能通过其他方式变得不可见，换句话说，不可渲染。这取决于平台和窗口系统。例如，在Windows上最小化窗口会使其停止渲染。在macOS上，完全被其他窗口遮挡的窗口也会触发相同的情况。在Linux/X11上，行为取决于窗口管理器。

OpenGL 上下文和表面格式

虽然可以通过调用成员函数setFormat()为每个QQuickWindow指定一个QSurfaceFormat，但窗口也可以通过使用QML中的Window和ApplicationWindow元素来创建。在这种情况下，窗口实例的创建不涉及C++代码，但应用程序可能仍然希望设置某些表面格式值，例如请求给定的OpenGL版本或配置文件。此类应用程序可以在启动时调用静态函数QSurfaceFormat::setDefaultFormat()。指定的格式将用于之后创建的所有Quick窗口。

Vulkan 实例

在使用Vulkan时，QQuickWindow会自动与由场景图内部创建和管理的QVulkanInstance关联。这样大多数应用程序不需要担心是否有VkInstance可用，因为这一切都是自动发生的。在高级情况下，应用程序可能希望创建自己的QVulkanInstance，以便以特定方式配置它。这也是可能的。在构造后立即调用QQuickWindow上的setVulkanInstance()，在使其可见之前，会导致使用应用程序提供的QVulkanInstance（以及底层的VkInstance）。当通过QQuickRenderControl重定向时，没有自动提供的QVulkanInstance，而是期望应用程序提供自己的并将其与QQuickWindow关联。

图形上下文和设备

当场景图初始化时，通常发生在窗口暴露或重定向渲染的情况下，初始化通过QQuickRenderControl执行，渲染所需的上下文或设备对象会自动创建。这包括OpenGL上下文、Direct3D设备和设备上下文、Vulkan和Metal设备。这些也可以通过应用程序代码通过QSGRendererInterface进行查询。当使用basic渲染循环时，所有渲染都在GUI线程上执行，所有可见的QQuickWindows使用相同的上下文或设备。threaded渲染循环为每个渲染线程使用专用的上下文或设备对象，因此每个QQuickWindow都有一个。对于某些图形API，通过setGraphicsConfiguration()提供了一定程度的可定制性。例如，这使得可以指定要在VkDevice上启用的Vulkan扩展列表。或者，也可以提供一组现有的上下文或设备对象供QQuickWindow使用，而不是让它自己构造。这是通过setGraphicsDevice()实现的。

class CreateTextureOption

(继承自 enum.Flag) CreateTextureOption 枚举用于自定义纹理的包裹方式。

常量

描述

QQuickWindow.TextureHasAlphaChannel

纹理具有alpha通道，应使用混合绘制。

QQuickWindow.TextureHasMipmaps

纹理具有mipmaps，并且可以在启用mipmapping的情况下绘制。

QQuickWindow.TextureOwnsGLTexture

自 Qt 6.0 起，此标志在实际中未使用并被忽略。原生图形资源的所有权不可转移给包装的 QSGTexture，因为 Qt Quick 可能没有关于如何释放此类对象及相关内存的必要详细信息。

QQuickWindow.TextureCanUseAtlas

图像可以上传到纹理图集中。

QQuickWindow.TextureIsOpaque

纹理将返回 false 给 hasAlphaChannel() 并且不会被混合。此标志在 Qt 5.6 中添加。
class RenderStage

常量

描述

QQuickWindow.BeforeSynchronizingStage

同步之前。

QQuickWindow.AfterSynchronizingStage

同步之后。

QQuickWindow.BeforeRenderingStage

渲染之前。

QQuickWindow.AfterRenderingStage

渲染后。

QQuickWindow.AfterSwapStage

在帧交换之后。

QQuickWindow.NoStage

尽快。此值在Qt 5.6中添加。

另请参阅

场景图和渲染

class SceneGraphError

此枚举描述了sceneGraphError()信号中的错误。

常量

描述

QQuickWindow.ContextNotAvailable

图形上下文创建失败。这通常意味着没有找到合适的OpenGL实现，例如因为没有安装图形驱动程序，因此没有OpenGL 2支持。在使用OpenGL ES的移动和嵌入式板上，此类错误可能表明窗口系统集成存在问题，可能是Qt配置不正确。
class TextRenderType

此枚举描述了Qt Quick中类似文本元素的默认渲染类型（Text、TextInput等）。

如果您希望文本在目标平台上看起来更原生，并且不需要诸如文本变换等高级功能，请选择NativeTextRendering。将此类功能与NativeTextRendering渲染类型结合使用会导致效果不佳，有时甚至会出现像素化的情况。

无论是QtTextRendering还是CurveTextRendering都是硬件加速技术。QtTextRendering是两者中较快的，但会使用更多的内存，并且在大尺寸时会出现渲染伪影。在QtTextRendering无法提供良好视觉效果或减少图形内存消耗是优先考虑的情况下，应考虑使用CurveTextRendering作为替代方案。

常量

描述

QQuickWindow.QtTextRendering

使用Qt自己的光栅化算法。

QQuickWindow.NativeTextRendering

使用操作系统的原生光栅化器进行文本渲染。

QQuickWindow.CurveTextRendering

文本使用直接在图形硬件上运行的曲线光栅化器进行渲染。（在Qt 6.7.0中引入。）

注意

当使用from __feature__ import true_property时，属性可以直接使用，否则通过访问器函数使用。

property activeFocusItemᅟ: QQuickItem

此属性保存当前具有活动焦点的项目，如果没有具有活动焦点的项目，则为null。

Access functions:
property colorᅟ: QColor

此属性保存用于在每帧开始时清除颜色缓冲区的颜色。

默认情况下，清除颜色为白色。

Access functions:
property contentItemᅟ: QQuickItem

此属性保存场景的不可见根项目。

一个 QQuickWindow 总是有一个包含所有内容的不可见根项目。要将项目添加到此窗口，请将项目重新父级到 contentItem 或场景中的现有项目。

Access functions:
__init__(renderControl)
Parameters:

renderControl – QQuickRenderControl

构造一个用于显示QML场景的窗口，其渲染将由control对象控制。请参阅QQuickRenderControl的文档以获取更多信息。

__init__([parent=None])
Parameters:

父窗口 – QWindow

构造一个窗口，用于显示带有父窗口 parent 的 QML 场景。

activeFocusItem()
Return type:

QQuickItem

属性 activeFocusItemᅟ 的获取器。

activeFocusItemChanged()

属性 activeFocusItemᅟ 的通知信号。

afterAnimating()

在请求渲染线程执行场景图的同步之前，此信号在GUI线程上发出。

与其他类似的信号不同，这个信号是在GUI线程而不是渲染线程上发出的。它可以用于将外部动画系统与QML内容同步。同时，这也意味着这个信号不适合用于触发图形操作。

afterFrameEnd()

当场景图提交了一帧时，会发出此信号。这是在所有其他相关信号（如afterRendering()）之后发出的。它是场景图渲染线程在渲染一帧时发出的最后一个信号。

注意

与frameSwapped()不同，当Qt Quick输出通过QQuickRenderControl重定向时，此信号也保证会被发出。

警告

此信号从场景图渲染线程发出。如果你的槽函数需要在继续执行之前完成，你必须确保连接是直接的（参见Qt::ConnectionType）。

另请参阅

beforeFrameBegin() rendererInterface()

afterRenderPassRecording()

此信号在场景图记录其主渲染通道的命令后发出，但该通道尚未在命令缓冲区上最终确定。

这个信号比afterRendering()更早发出，它保证了不仅帧还在活动，而且场景图的主渲染通道的记录也仍然有效。这允许插入命令而不必生成整个单独的渲染通道（这通常会清除附加的图像）。可以通过QSGRendererInterface查询本地图形对象。

注意

资源更新（上传、复制）通常无法在渲染过程中排队。因此，更复杂的用户渲染需要同时连接到beforeRendering()和此信号。

警告

此信号从场景图渲染线程发出。如果你的槽函数需要在继续执行之前完成，你必须确保连接是直接的（参见Qt::ConnectionType）。

另请参阅

rendererInterface() 场景图 - QML下的RHI

afterRendering()

信号在场景图将其命令添加到命令缓冲区后发出，此时命令尚未提交到图形队列。如果需要，连接到该信号的槽函数可以通过QSGRendererInterface查询原生资源，如命令缓冲区。但请注意，此时渲染通道（或多个通道）已经记录，无法在场景图的通道中添加更多命令。相反，使用afterRenderPassRecording()来实现这一点。因此，在Qt 6中，此信号的用途有限，与Qt 5不同。通常使用beforeRendering()和beforeRenderPassRecording()，或beforeRendering()和afterRenderPassRecording()的组合来实现自定义渲染的底层或覆盖。

警告

此信号从场景图渲染线程发出。如果你的槽函数需要在继续执行之前完成，你必须确保连接是直接的（参见Qt::ConnectionType）。

注意

在使用OpenGL时，请注意，设置OpenGL 3.x或4.x特定的状态并在从连接的槽返回时保持这些状态启用或设置为非默认值可能会干扰场景图的渲染。当信号发出时，场景图用于渲染的QOpenGLContext将被绑定。

另请参阅

rendererInterface() 场景图 - QML下的RHI 场景图 - QML下的OpenGL 场景图 - QML下的Metal 场景图 - QML下的Vulkan 场景图 - QML下的Direct3D 11

afterSynchronizing()

此信号在场景图与QML状态同步后发出。

此信号可用于在调用updatePaintNode()后执行所需的准备工作，同时GUI线程仍处于锁定状态。

在使用OpenGL时，场景图用于渲染的QOpenGLContext将在此处绑定。

警告

此信号从场景图渲染线程发出。如果你的槽函数需要在继续执行之前完成，你必须确保连接是直接的（参见Qt::ConnectionType）。

警告

使用OpenGL时，请注意，设置OpenGL 3.x或4.x特定状态并在从连接的槽返回时保持这些状态启用或设置为非默认值可能会干扰场景图的渲染。

beforeFrameBegin()

此信号在场景图开始准备帧之前发出。它先于像beforeSynchronizing()或beforeRendering()这样的信号。这是场景图渲染线程在开始准备新帧时发出的最早信号。

此信号与需要执行某些操作的低级图形框架相关，例如在Qt Quick尚未通过底层渲染硬件接口API启动新帧记录的阶段进行资源清理。

警告

此信号从场景图渲染线程发出。如果你的槽函数需要在继续执行之前完成，你必须确保连接是直接的（参见Qt::ConnectionType）。

另请参阅

afterFrameEnd() rendererInterface()

beforeRenderPassRecording()

此信号在场景图开始记录主渲染通道的命令之前发出。（图层有自己的通道，并且在此信号发出时已经完全记录。）当信号发出时，渲染通道已经在命令缓冲区上激活。

这个信号在beforeRendering()之后发出，它保证不仅帧是活动的，而且场景图的主渲染通道的记录也是活动的。这允许插入命令而不必生成整个单独的渲染通道（这通常会清除附加的图像）。可以通过QSGRendererInterface查询本地图形对象。

注意

资源更新（上传、复制）通常无法在渲染过程中排队。因此，更复杂的用户渲染需要同时连接到beforeRendering()和此信号。

警告

此信号从场景图渲染线程发出。如果你的槽函数需要在继续执行之前完成，你必须确保连接是直接的（参见Qt::ConnectionType）。

另请参阅

rendererInterface() 场景图 - QML下的RHI

beforeRendering()

此信号在帧的准备工作完成后发出，这意味着在适用的情况下，有一个命令缓冲区处于记录模式。如果需要，连接到该信号的槽函数可以通过QSGRendererInterface查询本地资源，如命令。但请注意，此时主渲染通道的记录尚未开始，因此无法在该通道内添加命令。启动一个通道意味着清除颜色、深度和模板缓冲区，因此仅通过连接到此信号无法实现底层类型的渲染。相反，应连接到beforeRenderPassRecording()。然而，如果需要记录复制类型的命令，连接到此信号仍然很重要，因为这些命令无法在渲染通道内排队。

警告

此信号从场景图渲染线程发出。如果你的槽函数需要在继续执行之前完成，你必须确保连接是直接的（参见Qt::ConnectionType）。

注意

在使用OpenGL时，请注意，设置OpenGL 3.x或4.x特定的状态并在从连接的槽返回时保持这些状态启用或设置为非默认值可能会干扰场景图的渲染。当信号发出时，场景图用于渲染的QOpenGLContext将被绑定。

另请参阅

rendererInterface() 场景图 - QML下的RHI 场景图 - QML下的OpenGL 场景图 - QML下的Metal 场景图 - QML下的Vulkan 场景图 - QML下的Direct3D 11

beforeSynchronizing()

在场景图与QML状态同步之前发出此信号。

尽管信号是从场景图渲染线程发出的，但GUI线程保证会被阻塞，就像在updatePaintNode()中一样。因此，在与Qt::DirectConnection连接的槽或lambda中访问GUI线程数据是安全的。

此信号可用于在调用updatePaintNode()之前进行任何所需的准备工作。

在使用OpenGL时，场景图用于渲染的QOpenGLContext将在此处绑定。

警告

此信号从场景图渲染线程发出。如果你的槽函数需要在继续执行之前完成，你必须确保连接是直接的（参见Qt::ConnectionType）。

警告

使用OpenGL时，请注意，设置OpenGL 3.x或4.x特定状态并在从连接的槽返回时保持这些状态启用或设置为非默认值可能会干扰场景图的渲染。

beginExternalCommands()

当将原始图形（OpenGL、Vulkan、Metal等）命令与场景图渲染混合使用时，必须在记录命令到场景图用于渲染其主渲染通道的命令缓冲区之前调用此函数。这是为了避免状态冲突。

在实践中，这个函数通常从连接到beforeRenderPassRecording()或afterRenderPassRecording()信号的槽中调用。

当记录命令到应用程序自己的命令缓冲区时（例如，由应用程序创建和管理的VkCommandBuffer或MTLCommandBuffer + MTLRenderCommandEncoder，而不是从场景图中检索的），不需要调用该函数。对于没有暴露原生命令缓冲区概念的图形API（OpenGL，Direct 3D 11），beginExternalCommands()和endExternalCommands()一起提供了Qt 5 resetOpenGLState()函数的替代方案。

在QSGRenderNode的render()实现中调用此函数和endExternalCommands()是不必要的，因为场景图会隐式地为渲染节点执行必要的步骤。

原生图形对象（例如，图形设备、命令缓冲区或编码器）可以通过getResource()访问。

警告

请注意，CommandListResource 在 beginExternalCommands() 和 endExternalCommands() 之间可能会返回不同的对象。当底层实现为在渲染过程中记录外部图形命令提供专用的辅助命令缓冲区时，可能会发生这种情况。因此，在调用此函数后，始终查询 CommandListResource。不要尝试重用早期查询中的对象。

注意

当场景图使用OpenGL时，请注意上下文中的OpenGL状态可能具有任意设置，并且此函数不会将状态重置为默认值。

另请参阅

endExternalCommands() resetOpenGLState()

color()
Return type:

QColor

另请参阅

setColor()

属性 colorᅟ 的获取器。

colorChanged(arg__1)
Parameters:

arg__1 – QColor

属性 colorᅟ 的通知信号。

contentItem()
Return type:

QQuickItem

属性 contentItemᅟ 的获取器。

createImageNode()
Return type:

QSGImageNode

创建一个简单的图像节点。当场景图未初始化时，返回值为null。

这是直接构造QSGSimpleTextureNode的跨后端替代方案。

另请参阅

QSGImageNode

createNinePatchNode()
Return type:

QSGNinePatchNode

创建一个九宫格节点。当场景图未初始化时，返回值为null。

createRectangleNode()
Return type:

QSGRectangleNode

创建一个简单的矩形节点。当场景图未初始化时，返回值为null。

这是直接构造QSGSimpleRectNode的跨后端替代方案。

另请参阅

QSGRectangleNode

createTextNode()
Return type:

QSGTextNode

创建一个文本节点。当场景图未初始化时，返回值为null。

另请参阅

QSGTextNode

createTextureFromImage(image)
Parameters:

图像 – QImage

Return type:

QSGTexture

这是一个重载函数。

createTextureFromImage(image, options)
Parameters:
Return type:

QSGTexture

从提供的image创建一个新的QSGTexture。如果图像具有alpha通道，相应的纹理也将具有alpha通道。

函数的调用者负责删除返回的纹理。底层的原生纹理对象将与QSGTexture一起被销毁。

当options包含TextureCanUseAtlas时，引擎可能会将图像放入纹理图集中。图集中的纹理需要依赖normalizedTextureSubRect()来确定其几何形状，并且不支持Repeat。来自CreateTextureOption的其他值将被忽略。

当options包含TextureIsOpaque时，引擎将创建一个RGB纹理，该纹理对于hasAlphaChannel()返回false。不透明纹理在大多数情况下渲染速度更快。当未设置此标志时，纹理将根据图像的格式具有一个alpha通道。

当 options 包含 TextureHasMipmaps 时，引擎将创建一个可以使用mipmap过滤的纹理。带有mipmap的纹理不能位于图集中。

在options中设置TextureHasAlphaChannel对此函数没有意义，因为默认情况下会假设存在alpha通道并进行混合。要取消此行为，请设置TextureIsOpaque。

当场景图使用OpenGL时，返回的纹理将使用GL_TEXTURE_2D作为纹理目标，并使用GL_RGBA作为内部格式。对于其他图形API，纹理格式通常为RGBA8。重新实现QSGTexture以创建具有不同参数的纹理。

警告

如果场景图尚未初始化，此函数将返回0。

警告

返回的纹理不受场景图的内存管理，必须由调用者在渲染线程上显式删除。这可以通过从QSGNode析构函数中删除纹理或使用deleteLater()来实现，如果纹理已经与渲染线程有亲和性。

此函数可以从主线程和渲染线程调用。

createTextureFromRhiTexture(texture[, options={}])
Parameters:
Return type:

QSGTexture

从提供的texture创建一个新的QSGTexture。

使用options来自定义纹理属性。此函数仅考虑TextureHasAlphaChannel标志。当设置此标志时，生成的QSGTexture始终被场景图渲染器视为需要混合。对于完全不透明的纹理，不设置此标志可以节省渲染期间执行alpha混合的成本。该标志与QRhiTexture的格式没有直接对应关系，即在不设置标志的情况下，使用诸如常用的QRhiTexture::RGBA8等纹理格式是完全正常的。

Mipmapping 不受 options 控制，因为 texture 已经创建，并且已经包含了是否存在 mipmaps 的信息。

返回的QSGTexture拥有QRhiTexture，意味着texture会与返回的QSGTexture一起被销毁。

如果 texture 拥有其底层原生图形资源（OpenGL 纹理对象、Vulkan 图像等），这取决于 QRhiTexture 的创建方式（QRhiTexture::create() 或 QRhiTexture::createFrom()），并且此函数不会控制或更改这一点。

注意

这仅在场景图已经初始化并且正在使用默认的、基于QRhi的适配时有效。否则返回值为None。

注意

此函数只能在场景图渲染线程上调用。

另请参阅

createTextureFromImage() sceneGraphInitialized() QSGTexture

effectiveDevicePixelRatio()
Return type:

浮点数

返回此窗口的设备像素比。

这与QWindow::devicePixelRatio()不同，因为它支持通过QQuickRenderControl和QQuickRenderTarget进行重定向渲染。当使用QQuickRenderControl时，QQuickWindow通常不会完全创建，这意味着它永远不会显示，并且在窗口系统中没有创建底层原生窗口。因此，查询像设备像素比这样的属性无法给出正确的结果。此函数考虑了renderWindowFor()和devicePixelRatio()。当没有重定向生效时，结果与QWindow::devicePixelRatio()相同。

endExternalCommands()

当将原始图形（OpenGL、Vulkan、Metal等）命令与场景图渲染混合使用时，在将命令记录到场景图用于渲染其主渲染通道的命令缓冲区后，必须调用此函数。这是为了避免破坏状态。

在实践中，这个函数通常从连接到beforeRenderPassRecording()或afterRenderPassRecording()信号的槽中调用。

当记录命令到应用程序自己的命令缓冲区时（例如，由应用程序创建和管理的VkCommandBuffer或MTLCommandBuffer + MTLRenderCommandEncoder，而不是从场景图中检索的），不需要调用该函数。对于没有暴露本地命令缓冲区概念的图形API（OpenGL，Direct 3D 11），beginExternalCommands()和endExternalCommands()一起提供了Qt 5 resetOpenGLState()函数的替代方案。

在QSGRenderNode的render()实现中调用此函数和beginExternalCommands()是不必要的，因为场景图会隐式地为渲染节点执行必要的步骤。

另请参阅

beginExternalCommands() resetOpenGLState()

frameSwapped()

当一帧被排队等待呈现时，会发出此信号。在启用垂直同步的情况下，在连续动画的场景中，每个垂直同步间隔最多发出一次信号。

此信号将从场景图渲染线程发出。

grabWindow()
Return type:

QImage

抓取窗口的内容并将其作为图像返回。

可以在窗口不可见时调用grabWindow()函数。这要求窗口已创建并具有有效大小，并且在同一进程中没有其他QQuickWindow实例正在渲染。

注意

当将此窗口与QQuickRenderControl结合使用时，除非使用software后端，否则此函数的结果是一个空图像。这是因为当通过使用QQuickRenderControl和setRenderTarget()将输出重定向到应用程序管理的图形资源（例如，纹理）时，应用程序更适合管理和执行最终的读取操作，因为它从一开始就完全控制资源。

警告

调用此函数会导致性能问题。

警告

此函数只能从GUI线程调用。

static graphicsApi()
Return type:

GraphicsApi

返回场景图如果在此时间点初始化时将使用的图形API。

查询场景图使用的API的标准方法是在场景图初始化后使用graphicsApi()，例如在sceneGraphInitialized()信号发出时或之后。在这种情况下，可以获得真实的结果，因为那时已知所有内容都已正确初始化使用该图形API。

这并不总是方便。如果应用程序需要设置外部框架，或者需要以依赖于场景图内置API选择逻辑的方式与setGraphicsDevice()一起工作，那么将此类操作推迟到QQuickWindow可见或initialize()被调用之后并不总是可行的。

因此，这个静态函数作为setGraphicsApi()的对应物提供：它可以在任何时候调用，结果反映了如果场景图在调用时初始化，它将选择什么API。

注意

此静态函数仅应在主（GUI）线程上调用。在渲染时查询API时，请使用QSGRendererInterface，因为该对象存在于渲染线程上。

注意

此函数不考虑场景图后端。

另请参阅

setGraphicsApi()

graphicsConfiguration()
Return type:

QQuickGraphicsConfiguration

返回传递给setGraphicsConfiguration()的QQuickGraphicsConfiguration，否则返回默认构造的配置。

graphicsDevice()
Return type:

QQuickGraphicsDevice

返回传递给setGraphicsDevice()的QQuickGraphicsDevice，否则返回默认构造的

另请参阅

setGraphicsDevice()

graphicsStateInfo()
Return type:

GraphicsStateInfo

返回一个指向GraphicsStateInfo结构的引用，该结构描述了RHI的一些内部状态，特别是后端（如Vulkan或Metal集成）的双缓冲或三缓冲状态。这在底层图形API是Vulkan或Metal时尤为重要，外部渲染代码希望对其经常变化的资源（如统一缓冲区）进行双缓冲或三缓冲，以避免管道停滞。

static hasDefaultAlphaBuffer()
Return type:

布尔

返回是否在新创建的窗口上使用alpha透明度。

incubationController()
Return type:

QQmlIncubationController

返回一个孵化控制器，该控制器在此窗口的帧之间拼接孵化。QQuickView 会自动为您安装此控制器，否则您需要使用 QQmlEngine::setIncubationController() 自行安装。

控制器由窗口拥有，当窗口被删除时，控制器将被销毁。

isPersistentGraphics()
Return type:

布尔

返回在QQuickWindow的生命周期内是否可以释放必要的图形资源。

注意

这是一个提示，并不保证它会被考虑进去。

另请参阅

setPersistentGraphics()

isPersistentSceneGraph()
Return type:

布尔

返回在此QQuickWindow的生命周期内是否可以释放场景图节点和资源。

注意

这是一个提示。这种情况何时以及如何发生是具体实现相关的。

isSceneGraphInitialized()
Return type:

布尔

如果场景图已初始化，则返回 true；否则返回 false。

mouseGrabberItem()
Return type:

QQuickItem

使用 QPointerEvent::exclusiveGrabber()。返回当前拥有鼠标抓取的项目。

paletteChanged()
paletteCreated()
releaseResources()

此函数尝试释放当前由QML场景持有的冗余资源。

调用此函数请求场景图释放缓存的图形资源，例如图形管道对象、着色器程序或图像数据。

此外，根据所使用的渲染循环，此函数还可能导致场景图和所有与窗口相关的渲染资源被释放。如果发生这种情况，将发出sceneGraphInvalidated()信号，允许用户清理自己的图形资源。如果应用程序中处理清理不可行，可以使用setPersistentGraphics()和setPersistentSceneGraph()函数来防止这种情况发生，但代价是更高的内存使用。

注意

缓存的图形资源（如图形管道或着色器程序）的释放不依赖于持久性提示。无论持久性图形和场景图提示的值如何，这些资源的释放都会发生。

注意

此函数与releaseResources()虚函数无关。

另请参阅

sceneGraphInvalidated() setPersistentGraphics() setPersistentSceneGraph()

renderTarget()
Return type:

QQuickRenderTarget

返回传递给setRenderTarget()的QQuickRenderTarget，否则返回默认构造的对象

另请参阅

setRenderTarget()

rendererInterface()
Return type:

QSGRendererInterface

返回当前的渲染器接口。该值始终有效且永远不会为空。

注意

此函数可以在构造QQuickWindow之后的任何时间调用，即使isSceneGraphInitialized()仍然为false。然而，一些渲染器接口函数，特别是getResource()，在场景图启动并运行之前将无法使用。另一方面，后端查询，如graphicsApi()或shaderType()，将始终可用。

注意

返回的指针的所有权归Qt所有。返回的实例可能会在不同的QQuickWindow实例之间共享，也可能不会共享，这取决于所使用的场景图后端。因此，应用程序应查询每个QQuickWindow的接口对象，而不是重用已经查询过的指针。

另请参阅

QSGRenderNode QSGRendererInterface

rhi()
Return type:

QRhi

返回此窗口用于渲染的QRhi对象。

仅当窗口使用Qt的3D API和着色语言抽象时可用，这意味着在使用software适配时结果始终为null。

结果仅在渲染初始化后有效，这由sceneGraphInitialized()信号的发出指示。在此之前，返回的值为null。对于常规的屏幕上的QQuickWindow，场景图初始化通常在原生窗口首次暴露（显示）时发生。当使用QQuickRenderControl时，初始化在显式的initialize()调用中完成。

实际上，这个函数是通过QSGRendererInterface查询QRhi的快捷方式。

sceneGraphAboutToStop()

当场景图即将停止渲染时，此信号在渲染线程上发出。这通常是因为窗口已被隐藏。

应用程序可以使用此信号来释放资源，但应准备好快速重新实例化它们。此时场景图和图形上下文不会被释放。

警告

此信号从场景图渲染线程发出。如果你的槽函数需要在继续执行之前完成，你必须确保连接是直接的（参见Qt::ConnectionType）。

警告

请确保sceneGraphAboutToStop()的信号处理程序在退出时，图形上下文的状态与进入信号处理程序时的状态相同。否则，可能会导致场景无法正确渲染。

另请参阅

sceneGraphInvalidated()

static sceneGraphBackend()
Return type:

字符串

返回请求的Qt Quick场景图后端。

注意

此函数的返回值可能仍然会被后续调用setSceneGraphBackend()所过时，直到应用程序中的第一个QQuickWindow被构建。

注意

该值仅反映在QQuickWindow构建后QT_QUICK_BACKEND环境变量中的请求。

另请参阅

setSceneGraphBackend()

sceneGraphError(error, message)
Parameters:

当场景图初始化期间发生error时，会发出此信号。

如果应用程序希望以自定义方式处理错误（如图形上下文创建失败），则应连接到此信号。当没有插槽连接到信号时，行为将有所不同：Quick将打印message，或显示消息框，并终止应用程序。

此信号将从GUI线程发出。

sceneGraphInitialized()

当场景图初始化时，会发出此信号。

此信号将从场景图渲染线程发出。

sceneGraphInvalidated()

当场景图无效时，会发出此信号。

此信号表示所使用的图形渲染上下文已失效，应释放与该上下文相关的所有用户资源。

在使用OpenGL渲染时，调用此函数时，此窗口的QOpenGLContext将被绑定。唯一的例外是如果原生OpenGL在Qt的控制之外被销毁，例如通过EGL_CONTEXT_LOST。

此信号将从场景图渲染线程发出。

scheduleRenderJob(job, schedule)
Parameters:

当此窗口的渲染达到给定的stage时，安排job运行。

这是为了方便在QQuickWindow中执行“一次性”任务的等效信号。

窗口将接管job的所有权，并在作业完成后删除它。

如果在job有机会运行之前渲染被关闭，该任务将运行，然后作为场景图清理的一部分被删除。如果窗口从未显示并且在QQuickWindow被销毁之前没有发生任何渲染，所有挂起的任务将在未调用其run()方法的情况下被销毁。

如果渲染发生在不同的线程上，那么任务将在渲染线程上执行。

如果 stage 是 NoStage，job 将在渲染线程不忙于渲染帧时尽早运行。如果窗口在作业发布或处理时未暴露且不可渲染，则作业将在不执行 run() 方法的情况下被删除。如果使用非线程渲染器，作业的 run() 方法将同步执行。在使用 OpenGL 渲染时，OpenGL 上下文在执行任何作业（包括 NoStage 作业）之前会切换到渲染器的上下文。

注意

此函数不会触发渲染；针对除NoStage之外的任何其他阶段的任务将被存储运行，直到在其他地方触发渲染。要强制任务提前运行，请调用update()；

另请参阅

beforeRendering() afterRendering() beforeSynchronizing() afterSynchronizing() frameSwapped() sceneGraphInvalidated()

setColor(color)
Parameters:

颜色 – QColor

另请参阅

color()

属性 colorᅟ 的设置器。

static setDefaultAlphaBuffer(useAlpha)
Parameters:

useAlpha – 布尔值

useAlpha 指定是否在新创建的窗口上使用透明度。

在任何期望创建半透明窗口的应用程序中，必须在创建第一个QQuickWindow之前将其设置为true。默认值为false。

static setGraphicsApi(api)
Parameters:

api – GraphicsApi

请求指定的图形 api。

当使用内置的默认图形适配时，api 指定场景图应使用哪种图形 API（OpenGL、Vulkan、Metal 或 Direct3D）进行渲染。此外，software 后端也是内置的，可以通过将 api 设置为 Software 来请求使用。

与setSceneGraphBackend()不同，后者只能用于请求给定的后端（内置或作为动态加载插件安装），此函数适用于更高级别的图形API概念。它涵盖了与Qt Quick一起发布的后端，因此在GraphicsApi枚举中有相应的值。

当此函数未被调用时，且等效的环境变量 QSG_RHI_BACKEND 也未设置，场景图将根据平台选择使用的图形API。

此函数在仅准备使用给定API进行渲染的应用程序中变得重要。例如，如果应用程序使用原生OpenGL或Vulkan进行渲染，它将希望确保Qt Quick也使用OpenGL或Vulkan进行渲染。此类应用程序应在其main()函数的早期调用此函数。

注意

调用该函数必须在应用程序中构造第一个QQuickWindow之前进行。之后无法更改图形API。

注意

当与QQuickRenderControl结合使用时，此规则有所放宽：可以更改图形API，但只有在所有现有的QQuickRenderControl和QQuickWindow实例都被销毁后才能进行。

要查询场景图使用什么图形API进行渲染，在场景图初始化后调用graphicsApi()，这通常发生在窗口首次可见时，或者当调用initialize()时。

要切换回默认行为，即场景图根据平台和其他条件选择图形API，请将api设置为Unknown。

另请参阅

graphicsApi()

setGraphicsConfiguration(config)
Parameters:

config – QQuickGraphicsConfiguration

设置此窗口的图形配置。config 包含各种设置，这些设置可能在初始化底层图形设备和上下文时被场景图考虑。

这种额外的配置，例如指定要为Vulkan启用的设备扩展，在集成依赖于某些扩展的本机图形渲染代码时变得相关且至关重要。在与外部3D或VR引擎（如OpenXR）集成时也是如此。

注意

当通过setGraphicsDevice()采用现有图形设备时，配置将被忽略，因为场景图不再控制这些对象的实际构建。

QQuickGraphicsConfiguration 实例是隐式共享的，可复制的，并且可以通过值传递。

警告

在QQuickWindow上设置QQuickGraphicsConfiguration必须足够早，在该窗口的场景图首次初始化之前完成。对于屏幕上的窗口，这意味着必须在调用QQuickWindow或QQuickView的show()之前完成此调用。对于QQuickRenderControl，配置必须在调用initialize()之前完成。

另请参阅

graphicsConfiguration()

setGraphicsDevice(device)
Parameters:

设备 – QQuickGraphicsDevice

设置此窗口的图形设备对象。场景图将使用由device指定的现有设备、物理设备和其他对象，而不是创建新的对象。

此函数经常与QQuickRenderControl和setRenderTarget()结合使用，以便将Qt Quick渲染重定向到纹理中。

默认构造的QQuickGraphicsDevice不会以任何方式改变默认行为。一旦通过QQuickGraphicsDevice工厂函数（例如fromDeviceObjects()）创建的device被传入，并且场景图使用匹配的图形API（以fromDeviceObjects()为例，那将是Vulkan），场景图将使用由QQuickGraphicsDevice封装的现有设备对象（例如，在Vulkan的情况下，VkPhysicalDevice、VkDevice和图形队列族索引）。这允许使用相同的设备，从而在Qt Quick和本地渲染引擎之间共享资源，例如缓冲区和纹理。

警告

此函数只能在初始化场景图之前调用，如果在之后调用将不会产生任何效果。实际上，这通常意味着在initialize()之前立即调用它。

作为一个例子，这次使用Direct3D，典型的预期用法如下：

// native graphics resources set up by a custom D3D rendering engine
ID3D11Device *device;
ID3D11DeviceContext *context;
ID3D11Texture2D *texture;
...
// now to redirect Qt Quick content into 'texture' we could do the following:
QQuickRenderControl *renderControl = new QQuickRenderControl;
QQuickWindow *window = new QQuickWindow(renderControl); // this window will never be shown on-screen
...
window->setGraphicsDevice(QQuickGraphicsDevice::fromDeviceAndContext(device, context));
renderControl->initialize();
window->setRenderTarget(QQuickRenderTarget::fromD3D11Texture(texture, textureSize);
...

使用此函数的关键方面是确保资源或资源句柄，例如上述示例中的texture，对外部渲染引擎和场景图渲染器都是可见且可用的。这需要使用相同的图形设备（或使用OpenGL时，相同的OpenGL上下文）。

QQuickGraphicsDevice 实例是隐式共享的、可复制的，并且可以通过值传递。它们不拥有相关的原生对象（例如，示例中的 ID3D11Device）。

注意

使用 QQuickRenderControl 并不总是意味着必须调用此函数。当不需要采用现有的设备或上下文时，不应调用此函数，场景图将正常初始化自己的设备和上下文，就像使用屏幕上的 QQuickWindow 一样。

另请参阅

graphicsDevice() QQuickRenderControl setRenderTarget() setGraphicsApi()

setPersistentGraphics(persistent)
Parameters:

persistent – 布尔值

设置图形资源（图形设备或上下文、交换链、缓冲区、纹理）是否应保留，并且在最后一个窗口删除之前不能释放，设置为persistent。默认值为true。

当调用releaseResources()时，或者当窗口被隐藏（更具体地说，不可渲染）时，一些渲染循环有可能释放所有图形资源，而不仅仅是缓存的资源。这可以暂时释放内存，但也意味着当窗口需要再次渲染时，渲染引擎将不得不进行完整的、可能代价高昂的资源重新初始化。

注意

窗口不可渲染的规则取决于平台和窗口管理器的具体实现。

注意

无论此设置如何，当最后一个QQuickWindow被删除时，所有图形资源都会被释放。

注意

这是一个提示，并不保证它会被考虑进去。

注意

此提示不适用于缓存的资源，这些资源相对便宜，可以丢弃然后稍后重新创建。因此，调用releaseResources()通常会释放这些资源，而不管此提示的值如何。

另请参阅

isPersistentGraphics() setPersistentSceneGraph() sceneGraphInitialized() sceneGraphInvalidated() releaseResources()

setPersistentSceneGraph(persistent)
Parameters:

persistent – 布尔值

设置场景图节点和资源是否为persistent。持久性意味着节点和资源不能被释放。默认值为true。

当调用releaseResources()时，当窗口被隐藏（更具体地说，不可渲染）时，一些渲染循环有可能释放场景图节点和相关的图形资源。这会暂时释放内存，但也意味着下次窗口渲染时场景图必须重新构建。

注意

窗口不可渲染的规则取决于平台和窗口管理器的具体实现。

注意

无论此设置如何，当最后一个QQuickWindow被删除时，场景图节点和资源总是会被释放。

注意

这是一个提示，并不保证它会被考虑进去。

另请参阅

isPersistentSceneGraph() setPersistentGraphics() sceneGraphInvalidated() sceneGraphInitialized() releaseResources()

setRenderTarget(target)
Parameters:

目标 – QQuickRenderTarget

将此窗口的渲染目标设置为 target。

一个QQuickRenderTarget作为一个可渲染的本地对象的不透明句柄，最常见的是一个2D纹理，以及相关的元数据，例如像素大小。

默认构造的QQuickRenderTarget意味着没有重定向。另一方面，通过静态QQuickRenderTarget工厂函数之一创建的有效target，可以启用Qt Quick场景的渲染重定向：它将不再针对与窗口关联的表面的颜色缓冲区，而是针对target中指定的纹理或其他图形对象。

例如，假设场景图使用Vulkan进行渲染，可以将其输出重定向到VkImage。对于像Vulkan这样的图形API，还必须提供图像布局。QQuickRenderTarget实例是隐式共享的，可以复制并按值传递。然而，它们并不拥有相关的本地对象（例如，示例中的VkImage）。

QQuickRenderTarget rt = QQuickRenderTarget::fromVulkanImage(vulkanImage, VK_IMAGE_LAYOUT_PREINITIALIZED, pixelSize);
quickWindow->setRenderTarget(rt);

此函数经常与QQuickRenderControl和一个不可见的QQuickWindow结合使用，以便将Qt Quick内容渲染到纹理中，而无需为此QQuickWindow创建屏幕上的原生窗口。

当所需的目标或相关数据（如大小）发生变化时，使用新的QQuickRenderTarget调用此函数。构建QQuickRenderTarget实例并调用此函数是廉价的，但请注意，当场景图即将渲染下一帧时，设置一个具有不同本地对象或其他数据的新target可能会导致潜在的昂贵初始化步骤。因此，仅在必要时更改目标。

注意

窗口不会获取target中引用的任何本地对象的所有权。

注意

调用者有责任确保target中引用的本地对象对场景图渲染器也是有效的。例如，对于Vulkan、Metal和Direct3D，这意味着纹理或图像是在场景图内部使用的同一图形设备上创建的。因此，当涉及到在已存在的设备或上下文上创建的纹理对象时，此函数通常与setGraphicsDevice()结合使用。

注意

在使用相关的图形API时，应用程序必须注意由场景图执行的图像布局转换。例如，一旦通过调用此函数将VkImage与场景图关联，在渲染帧时，其布局将转换为VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL。

警告

此函数只能从执行渲染的线程中调用。

另请参阅

renderTarget() QQuickRenderControl setGraphicsDevice() setGraphicsApi()

static setSceneGraphBackend(backend)
Parameters:

backend – str

请求一个Qt Quick场景图backend。后端可以是内置的，也可以以动态加载插件的形式安装。

这是一个重载函数。

注意

调用函数必须在应用程序中构造第一个QQuickWindow之前进行。之后无法更改。

有关后端列表的更多信息，请参见在应用程序中切换适配。如果backend无效或发生错误，请求将被忽略。

注意

调用此函数相当于设置QT_QUICK_BACKEND或QMLSCENE_DEVICE环境变量。然而，在生成其他进程的应用程序中使用此API更安全，因为无需担心环境继承问题。

另请参阅

sceneGraphBackend()

static setTextRenderType(renderType)
Parameters:

renderType – TextRenderType

将Qt Quick中类似文本元素的默认渲染类型设置为renderType。

注意

设置渲染类型只会影响之后创建的元素；现有元素的渲染类型不会被修改。

另请参阅

textRenderType()

swapChain()
Return type:

QRhiSwapChain

返回此窗口使用的QRhiSwapChain（如果有的话）。

注意

只有由标准渲染循环（例如，basic 或 threaded）支持的屏幕窗口才会有交换链。否则返回的值为空。例如，当窗口与 QQuickRenderControl 一起使用时，结果始终为空。

static textRenderType()
Return type:

TextRenderType

返回Qt Quick中类似文本元素的渲染类型。默认是QtTextRendering。

另请参阅

setTextRenderType()

update()

安排窗口渲染另一帧。

调用 QQuickWindow::update() 与 update() 的不同之处在于，它总是会触发重绘，无论底层场景图是否有变化。

class GraphicsStateInfo

注意

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

详细描述

PySide6.QtQuick.QQuickWindow.GraphicsStateInfo.currentFrameSlot
PySide6.QtQuick.QQuickWindow.GraphicsStateInfo.framesInFlight