class QQuickWindow#

QQuickWindow类提供了用于显示图形QML场景的窗口。 更多…

Inheritance diagram of PySide6.QtQuick.QQuickWindow

继承于：QQuickView

概要#

属性#

  • activeFocusItem - 当前具有活动焦点或为null nếu không tồn tại mục có tếp carbảng

  • color - 用于在每个画面的开始阶段清除颜色缓冲区

  • contentItem - 场景的无色覆盖根项目

方法#

槽（Slots）...

信号（Signals）...

静态函数#

注意

该文档可能包含从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的详细概述，请参阅 Scene Graph Adaptations 。

注意

图形操作和与场景图的交互必须始终在渲染线程上独家进行，主要在 updatePaintNode() 阶段进行。

注意

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

与加速3D图形API的集成#

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

无加速模式渲染#

也提供了一种有限的、基于软件的渲染路径。使用software后端，一些Qt Quick特性不可用，依赖于这些特性的QML项根本不会渲染。同时，即使在没有3D图形API可用的情况下，这也允许QQuickWindow正常运行。有关更多信息，请参阅Qt Quick软件适配。

重定向渲染#

QQuickWindow（PySide6.QtQuick.QQuickWindow）并不一定在屏幕上由本地窗口支持。渲染可以被重定向到自定义渲染目标，例如特定的本地纹理。这是通过组合QQuickRenderControl（PySide6.QtQuick.QQuickRenderControl）类和函数如setRenderTarget()（PySide6.QtQuick.QQuickWindow.setRenderTarget）、setGraphicsDevice()（PySide6.QtQuick.QQuickWindow.setGraphicsDevice）和setGraphicsConfiguration()（PySide6.QtQuick.QQuickWindow.setGraphicsConfiguration）实现的。

在这种情况下，QQuickWindow（PySide6.QtQuick.QQuickWindow）表示场景，并提供渲染帧的底层结构。它不会被渲染循环和本地窗口支持。相反，在这种情况下，应用程序驱动渲染，有效地替换了渲染循环。这允许生成图像序列，将渲染纹理用于外部3D引擎，或在VR环境中渲染Qt Quick内容。

资源管理#

QML会尝试缓存图像和场景图节点以提高性能，但在某些内存不足的场景中，可能需要积极地释放这些资源。可以使用releaseResources()（PySide6.QtQuick.QQuickWindow.releaseResources）函数来强制清理某些资源，尤其是那些可以重新创建的资源，可以在需要时再次创建。

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

注意

所有以QSG前缀开始的类都应该仅用于场景图渲染线程。有关更多信息，请参阅场景图和渲染。

曝光和可见性#

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

OpenGL上下文和表面格式#

虽然可以通过调用成员函数setFormat()为每个QQuickWindow指定一个QSurfaceFormat，但也可以通过使用Window和ApplicationWindow元素从QML创建窗口。在这种情况下，创建窗口实例不涉及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

纹理将为hasAlphaChannel()返回 false，且不会进行混合。此标志自 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 版本中引入。）

注意

另请参阅

另请参阅

activeFocusItem()#
返回类型：

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()和afterRenderPassRecording()的组合，或者beforeRendering()和beforeRenderPassRecording()，来实现自定义渲染的下层或叠加。

注意

此信号由场景图渲染线程发出。如果您的槽函数需要在继续执行之前完成，您必须确保连接是直接进行的（请参阅 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() 。 However, 连接到此信号在需要记录复制类型命令时仍然很重要，因为这些命令不能在渲染传递中排入队列。

注意

此信号由场景图渲染线程发出。如果您的槽函数需要在继续执行之前完成，您必须确保连接是直接进行的（请参阅 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、Direct3D 11）中，beginExternalCommands()和endExternalCommands() 一起提供Qt 5 resetOpenGLState()函数的替代。

在 render() 的实现中调用此函数以及 endExternalCommands() 是不必要的，因为在 QSGRenderNode 中，场景图隐式地执行了必要的步骤。

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

注意

请注意，在 beginExternalCommands() - endExternalCommands() 期间，CommandListResource 可能返回不同的对象。这可能发生在底层实现提供专用的二级命令缓冲区以在渲染通道中记录外部图形命令时。因此，始终在调用此函数后查询 CommandListResource。不要尝试重用早期查询的对象。

注意

当场景图使用 OpenGL 时，请注意，上下文中的 OpenGL 状态可以有任意设置，并且此函数不会将状态恢复到默认设置。

另请参阅

endExternalCommands() resetOpenGLState()

颜色()#
返回类型：

QColor

另请参阅

color 属性的获取器。

colorChanged(arg__1)#

arg__1 – QColor

color 属性的属性改变通知信号。

contentItem()#
返回类型：

QQuickItem

contentItem 属性的获取器。

createRectangleNode()#
返回类型：

QSGRectangleNode

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

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

另请参阅

QSGRectangleNode

createTextNode()#
返回类型：

QSGTextNode

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

另请参阅

QSGTextNode

createTextureFromImage(image)#

image – QImage

返回类型：

QSGTexture

这是一个重载函数。

createTextureFromImage(image, options)
返回类型：

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()来实现。

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

另请参阅

sceneGraphInitialized() 与 QSGTexture

createTextureFromRhiTexture(texture[, options={}])#
返回类型：

QSGTexture

从提供的texture创建新的QSGTexture。

使用options来自定义纹理属性。此函数只考虑TextureHasAlphaChannel标志。当设置该标志时，生成的QSGTexture总被场景图渲染器视为需要混合。对于完全不透明的纹理，不设置此标志可以节省渲染时的Alpha混合成本。该标志没有直接对应到QRhiTexture的格式，即当纹理格式为常用的QRhiTexture::RGBA8时，不设置该标志是完全正常的。

由于texture已经创建并且其存在或有无Mipmap已经嵌入，所以不由options控制Mipmapping。

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

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

注意

此功能仅在场景图已初始化并使用默认的基于 QRhi 的 适应 时有效。否则返回值是 None。

注意

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

另请参阅

createTextureFromImage() sceneGraphInitialized() QSGTexture

effectiveDevicePixelRatio()#
返回类型：

float

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

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

endExternalCommands()#

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

实际上，此函数通常在连接到beforeRenderPassRecording() 或afterRenderPassRecording() 信号的槽中调用。

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

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

另请参阅

beginExternalCommands() resetOpenGLState()

frameSwapped()#

信号在帧被安排进行呈现时发出。当垂直同步启用时，在持续动画的场景中，该信号在每个 vsync 间隔内最多发出一次。

该信号将来自场景图渲染线程。

grabWindow()#
返回类型：

QImage

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

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

注意

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

注意

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

注意

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

static graphicsApi()#
返回类型：

图形API

返回当前若在此时刻初始化的场景图将使用的图形API。

查询场景图使用的API的标准方法是，在场景图已初始化后（例如，在 sceneGraphInitialized() 信号已发出时）调用 graphicsApi()，这时得到的是真正的、真实的结果，因为那时知道已经正确使用该图形API初始化了所有内容。

这并不总是方便的。如果应用程序需要设置外部框架，或者需要在场景图内置的API选择逻辑依赖的情况下与方法 setGraphicsDevice() 一起工作，则不一定能够在 QQuickWindow 变得可见后或调用 initialize() 后推迟此类操作。

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

注意

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

注意

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

另请参阅

setGraphicsApi()

graphicsConfiguration()#
返回类型：

QQuickGraphicsConfiguration

返回传递给 QQuickGraphicsDevice 的 setGraphicsDevice() 方法，或在没有传递时返回默认构造的实例

graphicsDevice()#
返回类型：

QQuickGraphicsDevice

返回传递给 QQuickGraphicsDevice 的 setGraphicsDevice() 方法，或在没有传递时返回默认构造的实例

静态 hasDefaultAlphaBuffer()#
返回类型：

返回值类型为bool

返回是否在新建窗口中使用透明度 alpha

另请参阅

incubationController()#
返回类型：

QQmlIncubationController

返回用于在窗口帧之间进行孵化控制的对象。 QQuickView 会自动为您安装此控制器，否则您需要使用 QQmlEngine::setIncubationController() 方法自行安装。

控制器属于窗口，当窗口被删除时，控制器也会被销毁。

isPersistentGraphics()#
返回类型：

返回值类型为bool

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

注意

这是一个提示，并不能保证会被考虑到。

另请参阅

设置持续图形资源（setPersistentGraphics()）

isPersistentSceneGraph()#
返回类型：

返回值类型为bool

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

注意

这是一个提示。具体何时以及如何发生取决于具体实现。

isSceneGraphInitialized()#
返回类型：

返回值类型为bool

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

mouseGrabberItem()#
返回类型：

QQuickItem

使用 QPointerEvent::exclusiveGrabber()。返回当前具有鼠标捕获的项。

paletteChanged()#
paletteCreated()#
releaseResources()#

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

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

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

注意

释放缓存的图形资源（如图形管线或着色器程序）不受持久性提示的影响。无论持久图形和场景图提示的值如何，都会释放这些资源。

注意

此函数与《releaseResources()》虚拟函数无关。

另请参阅

sceneGraphInvalidated()《setPersistentGraphics()》《setPersistentSceneGraph()》

renderTarget()#
返回类型：

QQuickRenderTarget

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

另请参阅

setRenderTarget()

rendererInterface()#
返回类型：

QSGRendererInterface

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

注意

此函数可以在构建QQuickWindow之后随时调用，即使在isSceneGraphInitialized()仍为false的情况下也是如此。然而，某些渲染器接口函数，特别是那些特定的getResource()，只有在场景图运行之后才能正常工作。另一方面，后端查询，如graphicsApi()或shaderType()，始终是可用的。

注意

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

另请参阅

QSGRenderNode QSGRendererInterface

rhi()#
返回类型：

QRhi

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

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

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

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

sceneGraphAboutToStop()#

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

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

注意

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

注意

务必确保sceneGraphAboutToStop()的信号处理程序在信号处理程序进入时将图形上下文状态保持不变。未能这样做可能会导致场景无法正确渲染。

另请参阅

sceneGraphInvalidated()

static sceneGraphBackend()#
返回类型：

str

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

注意

此函数的返回值可能仍然会落后于后续对setSceneGraphBackend()的调用，直到应用程序中的第一个QQuickWindow构造完毕。

注意

构造了QQuickWindow之后，此值仅反映了QT_QUICK_BACKEND环境变量的请求。

另请参阅

setSceneGraphBackend()

sceneGraphError(error, message)#

在场景图初始化期间发生错误时发出此信号。

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

此信号将从GUI线程发出。

sceneGraphInitialized()#

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

该信号将来自场景图渲染线程。

sceneGraphInvalidated()#

当场景图失效时发出此信号。

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

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

该信号将来自场景图渲染线程。

scheduleRenderJob(job, schedule)#

当此窗口的渲染达到指定的 阶段 时安排 任务 执行。

这是对 QQuickWindow 中等效信号的便捷操作，用于“单次”任务。

窗口将拥有 任务 的所有权，并在任务完成后将其删除。

如果在 任务 有机会运行之前关闭了渲染，则该任务将会运行并作为场景图清理的一部分被删除。如果窗口从未显示，并且在 QQuickWindow 被销毁之前从未发生渲染，所有待处理的任务都将在它们的 run() 方法未被调用的情况下被销毁。

如果渲染在另一个线程上发生，则任务将在渲染线程上执行。

如果 阶段 是 NoStage，任务 将在渲染线程不忙于渲染帧时尽可能早地运行。如果任务被发布或处理时窗口未被展示且不可渲染，则任务将被删除而不会执行 run() 方法。如果正在使用非线程渲染器，则任务的 run() 方法将同步执行。当使用 OpenGL 渲染时，在执行任何任务（包括 NoStage 任务）之前，将更改 OpenGL 上下文为渲染器的上下文。

注意

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

另请参阅

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

setColor(color)#

颜色 – QColor

另请参阅

属性 color 的设置器。

静态setDefaultAlphaBuffer(useAlpha)#

useAlpha – bool

useAlpha 指定在新建窗口中使用透明白色。

在任意需要创建半透明白色窗口的应用中，在创建第一个 QQuickWindow 之前，必须将其设置为 true。默认值为 false。

静态setGraphicsApi(api)#

api – GraphicsApi

请求指定的图形 api。

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

与只能用于请求特定后端（内置或作为动态加载插件安装）的 setSceneGraphBackend() 相比，此功能与更高级别的图形 API 概念一起使用。它涵盖了与 Qt Quick 一起提供的后端，因此在 GraphicsApi 枚举值中也有对应的值。

如果没有调用此函数，并且也没有设置等价的环境变量 QSG_RHI_BACKEND，场景图将根据平台选择使用的图形 API。

对于仅准备使用特定 API 进行渲染的应用程序，此函数变得非常重要。例如，如果一个应用程序通过应用程序本身执行本地 OpenGL 或 Vulkan 渲染，它将希望确保 Qt Quick 也使用 OpenGL 或 Vulkan 进行渲染。这种应用程序预计会在它们的主函数的早期调用此函数。

注意

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

注意

当与QQuickRenderControl一起使用时，此规则被放宽：在所有现有的QQuickRenderControl和QQuickWindow实例被销毁后，可以更改图形API。

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

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

另请参阅

graphicsApi()

setGraphicsConfiguration(config)#

config – QQuickGraphicsConfiguration

设置本窗口的图形配置。config包含场景图在初始化底层图形设备和上下文时可能考虑的设置。

这样的额外配置，例如指定为Vulkan启用的设备扩展，在集成依赖于某些扩展的本地图形渲染代码时变得相关和关键。当与OpenXR等外部3D或VR引擎集成时也是如此。

注意

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

QQuickGraphicsConfiguration实例默认共享、可复制，并且可以通过值传递。

注意

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

另请参阅

graphicsConfiguration()

setGraphicsDevice(device)#

device – QQuickGraphicsDevice

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

此函数通常与 QQuickRenderControl 和 setRenderTarget() 一起使用，以便将 Qt Quick 渲染重定向到纹理。

默认构造的 QQuickGraphicsDevice 在任何方面都不会改变默认行为。一旦通过其中一个 QQuickGraphicsDevice 工厂函数（例如，fromDeviceObjects()）创建了一个 device，并且场景图使用匹配的图形 API（以从 DeviceObjects() 为例，那就是 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)#

持久化 - bool

设置是否应该保留图形资源（图形设备或上下文、交换链、缓冲区、纹理），直到最后一个窗口被删除后才释放，为 persistent。默认值为 true。

当调用 releaseResources() 时，或当窗口被隐藏（更具体地，不可渲染）时，一些渲染循环有可能释放所有资源，而不仅仅是缓存资源。这可以暂时释放内存，但也意味着渲染引擎需要在窗口再次需要渲染时对资源进行全面、可能耗费较大的重新初始化。

注意

窗口不可渲染的规则是平台和窗口管理器特定的。

注意

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

注意

这是一个提示，并不能保证会被考虑到。

注意

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

另请参阅

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

setPersistentSceneGraph(persistent)#

持久化 - bool

设置场景图节点和资源是否为 persistence。持久意为节点和资源不会被释放。默认值是 true。

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

注意

窗口不可渲染的规则是平台和窗口管理器特定的。

注意

场景图节点和资源会在最后一个 QQuickWindow 被删除时总是被释放，不管这个设置是什么。

注意

这是一个提示，并不能保证会被考虑到。

另请参阅

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

setRenderTarget(target)#

target – 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)#

backend – str

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

这是一个重载函数。

注意

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

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

注意

调用此函数等价于设置 QT_QUICK_BACKEND 或 QMLSCENE_DEVICE 环境变量。但是，对于在应用程序中生成其他进程的应用程序，此API更安全使用，因为不必担心环境继承的问题。

另请参阅

sceneGraphBackend()

static setTextRenderType(renderType)#

renderType – TextRenderType

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

注意

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

另请参阅

textRenderType()

swapChain()#
返回类型：

QRhiSwapChain

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

注意

只有由标准渲染循环（如基本或线程化）支持的屏幕窗口才会有swapchain。否则返回值将为null。例如，当窗口与QQuickRenderControl一起使用时，结果总是null。

静态 textRenderType()#
返回类型：

TextRenderType

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

另请参阅

setTextRenderType()

update()#

调度窗口渲染另一帧。

调用QQuickWindow::update()与调用update()不同，因为它始终触发重绘，无论底层场景图是否发生更改。