QQuickWindow Class

成员函数文档

[explicit] QQuickWindow::QQuickWindow(QQuickRenderControl *control)

创建一个用于显示 QML 场景的窗口，该场景的渲染将由 `control ` 对象控制。更多信息请参阅QQuickRenderControl 的文档。

[explicit] QQuickWindow::QQuickWindow(QWindow *parent = nullptr)

创建一个用于显示 QML 场景的窗口，其父窗口为parent 。

[override virtual noexcept] QQuickWindow::~QQuickWindow()

关闭该窗口。

[override virtual] QAccessibleInterface *QQuickWindow::accessibleRoot() const

返回该窗口的辅助功能接口；如果无法创建该接口，则返回 0。

[signal] void QQuickWindow::afterAnimating()

该信号在GUI线程上发出，用于在请求渲染线程执行场景图同步之前进行准备。

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

[signal, since 6.0] void QQuickWindow::afterFrameEnd()

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

该函数在 Qt 6.0 中引入。

另请参阅 beforeFrameBegin() 和rendererInterface()。

[signal] void QQuickWindow::afterRenderPassRecording()

该信号在场景图记录完其主渲染阶段的命令后发出，但该渲染阶段在命令缓冲区中尚未最终确定。

该信号的触发时间早于 `afterRendering()`，并保证不仅当前帧，而且场景图的主渲染通道的记录仍处于活动状态。这允许在不需生成一个完整的、独立的渲染通道（这通常会清空关联的图像）的情况下插入命令。可通过 `QSGRendererInterface` 查询原生图形对象。

另请参阅 rendererInterface() 以及QML 中的“场景图 - RHI”。

[signal] void QQuickWindow::afterRendering()

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

另请参阅 rendererInterface()、QML 下的场景图 - RHI、QML 下的场景图 - OpenGL、QML 下的场景图 - Metal、QML 下的场景图 - Vulkan 以及QML 下的场景图 - Direct3D 11。

[signal] void QQuickWindow::afterSynchronizing()

当场景图与 QML 状态同步后，将触发此信号。

该信号可用于在调用 `QQuickItem::updatePaintNode()` 之后执行必要的准备工作，此时 GUI 线程仍处于锁定状态。

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

[signal, since 6.0] void QQuickWindow::beforeFrameBegin()

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

该信号适用于需要在Qt Quick 尚未通过底层渲染硬件接口API启动新帧录制阶段执行特定操作（如资源清理）的低级图形框架。

该函数在 Qt 6.0 中引入。

另请参阅 afterFrameEnd() 和rendererInterface()。

[signal] void QQuickWindow::beforeRenderPassRecording()

该信号在场景图开始记录主渲染通道的命令之前发出。（图层有各自的渲染通道，并在该信号发出时已完成全部记录。）当该信号发出时，渲染通道已在命令缓冲区中处于活动状态。

该信号的触发时间晚于 `beforeRendering()`，它保证不仅当前帧处于活动状态，且场景图的主渲染阶段的记录也处于活动状态。这使得可以在无需生成一个完整的、独立的渲染阶段（这通常会清空关联的图像）的情况下插入命令。可以通过 `QSGRendererInterface` 查询原生图形对象。

另请参阅 rendererInterface() 以及QML 中的“场景图 - RHI”。

[signal] void QQuickWindow::beforeRendering()

该信号在帧的准备工作完成后发出，这意味着（在适用情况下）命令缓冲区已处于录制模式。 如果需要，连接到该信号的插槽函数可以通过 `QSGRendererInterface` 查询原生资源，例如之前的命令。但请注意，此时主渲染通路的录制尚未开始，因此无法在该通路中添加命令。 开始一个渲染通道意味着清空颜色、深度和模板缓冲区，因此仅通过连接此信号无法实现底层渲染。相反，应连接到 `beforeRenderPassRecording()`。不过，如果需要录制“复制”类型的命令，连接此信号仍然很重要，因为此类命令无法在渲染通道内入队。

另请参阅 rendererInterface()、QML 下的场景图 - RHI、QML 下的场景图 - OpenGL、QML 下的场景图 - Metal、QML 下的场景图 - Vulkan 以及QML 下的场景图 - Direct3D 11。

[signal] void QQuickWindow::beforeSynchronizing()

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

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

该信号可用于在调用QQuickItem::updatePaintNode() 之前进行任何必要的准备工作。

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

void QQuickWindow::beginExternalCommands()

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

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

当将命令写入应用程序自身的命令缓冲区（例如，由应用程序创建和管理、而非从场景图获取的 VkCommandBuffer 或 MTLCommandBuffer + MTLRenderCommandEncoder）时，无需调用此函数。 对于未公开原生命令缓冲区概念的图形 API（如 OpenGL、Direct 3D 11），beginExternalCommands() 与endExternalCommands() 共同提供了对 Qt 5 中 resetOpenGLState() 函数的替代方案。

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

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

另请参阅 endExternalCommands() 和QQuickOpenGLUtils::resetOpenGLState()。

[override virtual protected] void QQuickWindow::closeEvent(QCloseEvent *e)

重写了：QWindow::closeEvent(QCloseEvent *ev)。

QSGImageNode *QQuickWindow::createImageNode() const

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

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

另请参阅 QSGImageNode 。

QSGNinePatchNode *QQuickWindow::createNinePatchNode() const

创建一个九宫格节点。如果场景图尚未初始化，则返回值为 null。

QSGRectangleNode *QQuickWindow::createRectangleNode() const

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

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

另请参阅 QSGRectangleNode 。

[since 6.7] QSGTextNode *QQuickWindow::createTextNode() const

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

该函数在 Qt 6.7 中引入。

另请参阅 QSGTextNode 。

QSGTexture *QQuickWindow::createTextureFromImage(const QImage &image, QQuickWindow::CreateTextureOptions options) const

根据提供的image 创建一个新的QSGTexture 。如果图像具有Alpha通道，则对应的纹理也将具有Alpha通道。

函数调用方负责删除返回的纹理。随后，底层原生纹理对象将与QSGTexture 一同销毁。

当 `options ` 包含 `TextureCanUseAtlas` 时，引擎可能会将该图像放入纹理图集。图集中的纹理需要依赖 `QSGTexture::normalizedTextureSubRect()` 来获取其几何信息，且不支持 `QSGTexture::Repeat`。来自 `CreateTextureOption ` 的其他值将被忽略。

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

当options 包含TextureHasMipmaps 时，引擎将创建一个支持 Mipmap 过滤的纹理。支持 Mipmap 的纹理不能包含在纹理图集中。

将TextureHasAlphaChannel 设置为options 对本函数无实际意义，因为默认情况下会假设存在Alpha通道并进行混合。若要禁用此功能，请将TextureIsOpaque 。

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

该函数可在主线程和渲染线程中调用。

另请参见 sceneGraphInitialized() 和QSGTexture 。

QSGTexture *QQuickWindow::createTextureFromImage(const QImage &image) const

[since 6.6] QSGTexture *QQuickWindow::createTextureFromRhiTexture(QRhiTexture *texture, QQuickWindow::CreateTextureOptions options = {}) const

根据提供的texture 创建一个新的QSGTexture 。

使用options 自定义纹理属性。此函数仅考虑TextureHasAlphaChannel 标志。当该标志被设置时，生成的QSGTexture 将始终被场景图渲染器视为需要进行混合处理。对于完全不透明的纹理，不设置该标志可节省渲染过程中执行Alpha混合的开销。 该标志与QRhiTexture 的format 属性并无直接对应关系，即在使用常见纹理格式（如QRhiTexture::RGBA8 ）时，不设置该标志也是完全正常的。

Mipmapping不受options 控制，因为texture 已经创建，且其中已烘焙了Mipmap的存在与否。

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

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

该函数于 Qt 6.6 版本中引入。

另请参阅 createTextureFromImage()、sceneGraphInitialized()，以及QSGTexture 。

[signal, since 6.11] void QQuickWindow::devicePixelRatioChanged()

当有效设备像素比发生变化时，会发出此信号。

该函数在 Qt 6.11 中引入。

另请参阅 effectiveDevicePixelRatio()。

qreal QQuickWindow::effectiveDevicePixelRatio() const

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

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

另请参阅 QQuickRenderControl 、QQuickRenderTarget 、setRenderTarget() 以及QWindow::devicePixelRatio()。

void QQuickWindow::endExternalCommands()

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

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

当将命令写入应用程序自身的命令缓冲区（例如由应用程序创建和管理、而非从场景图获取的 VkCommandBuffer 或 MTLCommandBuffer + MTLRenderCommandEncoder）时，无需调用此函数。 对于未暴露原生命令缓冲区概念的图形 API（如 OpenGL、Direct 3D 11），beginExternalCommands() 和 endExternalCommands() 共同提供了 Qt 5 中 resetOpenGLState() 函数的替代方案。

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

另请参阅 beginExternalCommands()和QQuickOpenGLUtils::resetOpenGLState()。

[override virtual protected] bool QQuickWindow::event(QEvent *event)

重写了：QWindow::event(QEvent *ev)。

[override virtual protected] void QQuickWindow::exposeEvent(QExposeEvent *)

重写了：QWindow::exposeEvent(QExposeEvent *ev)。

[override virtual protected] void QQuickWindow::focusInEvent(QFocusEvent *ev)

重写了：QWindow::focusInEvent(QFocusEvent *ev)。

[override virtual protected] void QQuickWindow::focusOutEvent(QFocusEvent *ev)

重写了：QWindow::focusOutEvent(QFocusEvent *ev)。

[signal] void QQuickWindow::frameSwapped()

当帧被排入渲染队列准备呈现时，会发出此信号。在启用垂直同步的情况下，对于持续动画的场景，该信号在每个垂直同步间隔内最多发出一次。

该信号将由场景图的渲染线程发出。

QImage QQuickWindow::grabWindow()

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

即使窗口不可见，也可以调用 grabWindow() 函数。这要求该窗口为created ，且具有有效尺寸，并且同一进程中没有其他QQuickWindow 实例正在渲染。

[static, since 6.0] QSGRendererInterface::GraphicsApi QQuickWindow::graphicsApi()

返回如果场景图在此时刻初始化，则会使用的图形 API。

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

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

因此，提供了此静态函数作为setGraphicsApi() 的补充：它可在任何时候调用，且结果反映了如果场景图在调用时被初始化，它会选择哪种 API。

该函数在 Qt 6.0 中引入。

另请参阅 setGraphicsApi()。

[since 6.0] QQuickGraphicsConfiguration QQuickWindow::graphicsConfiguration() const

返回传递给 `setGraphicsConfiguration()` 的 `QQuickGraphicsConfiguration `，否则返回一个默认构造的 ` `。

该函数在 Qt 6.0 中引入。

另请参阅 setGraphicsConfiguration()。

[since 6.0] QQuickGraphicsDevice QQuickWindow::graphicsDevice() const

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

该函数在 Qt 6.0 中引入。

另请参阅 setGraphicsDevice()。

const QQuickWindow::GraphicsStateInfo &QQuickWindow::graphicsStateInfo()

返回对GraphicsStateInfo 结构体的引用，该结构体描述了RHI的部分内部状态，特别是后端（例如Vulkan或Metal集成）的双缓冲或三缓冲状态。 当底层图形 API 为 Vulkan 或 Metal 时，如果外部渲染代码希望对其频繁变化的资源（例如统一缓冲区）自行执行双缓冲或三缓冲，以避免管道停滞，则此功能便十分重要。

[static] bool QQuickWindow::hasDefaultAlphaBuffer()

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

另请参阅 setDefaultAlphaBuffer()。

[override virtual protected] void QQuickWindow::hideEvent(QHideEvent *)

重写了：QWindow::hideEvent(QHideEvent *ev)。

QQmlIncubationController *QQuickWindow::incubationController() const

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

该控制器由窗口拥有，并在窗口被删除时被销毁。

bool QQuickWindow::isPersistentGraphics() const

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

另请参阅 setPersistentGraphics()。

bool QQuickWindow::isPersistentSceneGraph() const

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

bool QQuickWindow::isSceneGraphInitialized() const

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

[override virtual protected] void QQuickWindow::keyPressEvent(QKeyEvent *e)

重写了：QWindow::keyPressEvent(QKeyEvent *ev)。

[override virtual protected] void QQuickWindow::keyReleaseEvent(QKeyEvent *e)

重写了：QWindow::keyReleaseEvent(QKeyEvent *ev)。

[override virtual protected] void QQuickWindow::mouseDoubleClickEvent(QMouseEvent *event)

重写了：QWindow::mouseDoubleClickEvent(QMouseEvent *ev)。

[override virtual protected] void QQuickWindow::mouseMoveEvent(QMouseEvent *event)

重写了：QWindow::mouseMoveEvent(QMouseEvent *ev)。

[override virtual protected] void QQuickWindow::mousePressEvent(QMouseEvent *event)

重写了：QWindow::mousePressEvent(QMouseEvent *ev)。

[override virtual protected] void QQuickWindow::mouseReleaseEvent(QMouseEvent *event)

重写了：QWindow::mouseReleaseEvent(QMouseEvent *ev)。

[slot] void QQuickWindow::releaseResources()

该函数试图释放当前由 QML 场景占用的冗余资源。

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

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

另请参阅 sceneGraphInvalidated()、setPersistentGraphics() 和setPersistentSceneGraph()。

[since 6.0] QQuickRenderTarget QQuickWindow::renderTarget() const

返回传递给 `setRenderTarget()` 的 `QQuickRenderTarget `，否则返回一个通过默认构造函数构造的 ` `

该函数于 Qt 6.0 中引入。

另请参阅 setRenderTarget()。

QSGRendererInterface *QQuickWindow::rendererInterface() const

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

另请参阅 QSGRenderNode 和QSGRendererInterface 。

[override virtual protected] void QQuickWindow::resizeEvent(QResizeEvent *ev)

重写了：QWindow::resizeEvent(QResizeEvent *ev)。

[since 6.6] QRhi *QQuickWindow::rhi() const

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

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

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

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

该函数在 Qt 6.6 中引入。

[signal] void QQuickWindow::sceneGraphAboutToStop()

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

应用程序可利用此信号释放资源，但应做好快速重新实例化这些资源的准备。此时，场景图和图形上下文尚未被释放。

另请参阅 sceneGraphInvalidated()。

[static] QString QQuickWindow::sceneGraphBackend()

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

另请参阅 setSceneGraphBackend()。

[signal] void QQuickWindow::sceneGraphError(QQuickWindow::SceneGraphError error, const QString &message)

当场景图初始化过程中发生error 时，会发出此信号。

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

该信号将由 GUI 线程发出。

[signal] void QQuickWindow::sceneGraphInitialized()

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

该信号将由场景图的渲染线程发出。

[signal] void QQuickWindow::sceneGraphInvalidated()

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

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

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

该信号将由场景图渲染线程发出。

void QQuickWindow::scheduleRenderJob(QRunnable *job, QQuickWindow::RenderStage stage)

安排在该窗口的渲染达到指定的stage 时执行job 。

这是针对QQuickWindow 中等效信号的一种便捷写法，适用于“一次性”任务。

该窗口将拥有job 的所有权，并在作业完成后将其删除。

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

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

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

另请参阅 beforeRendering()、afterRendering()、beforeSynchronizing()、afterSynchronizing()、frameSwapped() 以及sceneGraphInvalidated()。

[static] void QQuickWindow::setDefaultAlphaBuffer(bool useAlpha)

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

在任何需要创建半透明窗口的应用程序中，必须在创建第一个 `QQuickWindow` 之前将此参数设置为 `true`。默认值为 `false`。

另请参阅 hasDefaultAlphaBuffer()。

[static, since 6.0] void QQuickWindow::setGraphicsApi(QSGRendererInterface::GraphicsApi api)

请求指定的图形api 。

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

与仅能用于请求特定后端（无论是内置的还是作为动态加载插件安装的）的setSceneGraphBackend() 不同，该函数基于图形 API 这一更高层次的概念。它涵盖了随Qt Quick 一起提供的后端，因此QSGRendererInterface::GraphicsApi 枚举中包含相应的值。

如果完全未调用此函数，且等效的环境变量QSG_RHI_BACKEND 也未设置，则场景图将根据平台选择要使用的图形 API。

在仅支持使用特定 API 进行渲染的应用程序中，此函数尤为重要。例如，如果应用程序执行原生 OpenGL 或 Vulkan 渲染，则需要确保Qt Quick 也使用 OpenGL 或 Vulkan 进行渲染。此类应用程序应在 main() 函数的早期阶段调用此函数。

若要查询场景图正在使用哪种图形 API 进行渲染，请在场景图的has initialized 之后调用QSGRendererInterface::graphicsApi()，这通常发生在窗口首次可见时，或调用QQuickRenderControl::initialize() 时。

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

该函数在 Qt 6.0 中引入。

另请参阅 graphicsApi()。

[since 6.0] void QQuickWindow::setGraphicsConfiguration(const QQuickGraphicsConfiguration &config)

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

此类附加配置（例如指定为 Vulkan 启用哪些设备扩展）在集成依赖特定扩展的原生图形渲染代码时尤为重要且必不可少。与外部 3D 或 VR 引擎（如 OpenXR）集成时亦是如此。

QQuickGraphicsConfiguration 实例默认是共享的、可复制的，并且可以按值传递。

该函数在 Qt 6.0 中引入。

另请参阅 graphicsConfiguration()。

[since 6.0] void QQuickWindow::setGraphicsDevice(const QQuickGraphicsDevice &device)

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

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

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

以 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）。

该函数在 Qt 6.0 中引入。

另请参阅 graphicsDevice()、QQuickRenderControl 、setRenderTarget() 以及setGraphicsApi()。

void QQuickWindow::setPersistentGraphics(bool persistent)

用于设置图形资源（图形设备或上下文、交换链、缓冲区、纹理）是否应被保留，且在最后一个窗口被删除之前无法释放，该设置通过调用 `persistent` 实现。默认值为 `true`。

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

另请参阅 isPersistentGraphics()、setPersistentSceneGraph()、sceneGraphInitialized()、sceneGraphInvalidated() 以及releaseResources()。

void QQuickWindow::setPersistentSceneGraph(bool persistent)

设置场景图节点和资源是否为persistent 。Persistent 表示这些节点和资源无法被释放。默认值为true 。

调用releaseResources()时，当窗口被隐藏（更准确地说，处于不可渲染状态）时，某些渲染循环可能会释放场景图节点及相关图形资源。这虽能暂时释放内存，但也意味着下次窗口渲染时，必须重建场景图。

另请参阅 isPersistentSceneGraph()、setPersistentGraphics()、sceneGraphInvalidated()、sceneGraphInitialized() 以及releaseResources()。

[since 6.0] void QQuickWindow::setRenderTarget(const QQuickRenderTarget &target)

将此窗口的渲染目标设置为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 设置为新的原生对象或其他数据，可能会导致初始化步骤的开销增加。 因此，仅在必要时更改目标。

该函数在 Qt 6.0 中引入。

另请参阅 renderTarget()、QQuickRenderControl 、setGraphicsDevice() 以及setGraphicsApi()。

[static] void QQuickWindow::setSceneGraphBackend(const QString &backend)

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

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

另请参阅 sceneGraphBackend()。

[static] void QQuickWindow::setTextRenderType(QQuickWindow::TextRenderType renderType)

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

另请参阅 textRenderType()。

[override virtual protected] void QQuickWindow::showEvent(QShowEvent *)

重写了：QWindow::showEvent(QShowEvent *ev)。

[since 6.6] QRhiSwapChain *QQuickWindow::swapChain() const

返回该窗口使用的QRhiSwapChain （如有）。

该函数在 Qt 6.6 中引入。

[override virtual protected] void QQuickWindow::tabletEvent(QTabletEvent *event)

重写了：QWindow::tabletEvent(QTabletEvent *ev)。

[static] QQuickWindow::TextRenderType QQuickWindow::textRenderType()

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

另请参阅 setTextRenderType()。

[slot] void QQuickWindow::update()

安排窗口渲染下一帧。

调用 QQuickWindow::update() 与调用QQuickItem::update() 的区别在于，前者无论底层场景图是否发生变化，都会触发重绘。

[override virtual protected] void QQuickWindow::wheelEvent(QWheelEvent *event)

重写了：QWindow::wheelEvent(QWheelEvent *ev)。