QQuickWindow 类

成员函数文档

[显式] QQuickWindow::QQuickWindow(QWindow *parent = nullptr)

使用指定的父窗口parent构建用于显示QML场景的窗口。

[显式] QQuickWindow::QQuickWindow(QQuickRenderControl *control)

构建用于显示QML场景的窗口，其渲染将由control对象控制。有关更多信息，请参阅QQuickRenderControl的文档。

[重写虚函数 noexcept] QQuickWindow::~QQuickWindow()

销毁窗口。

[覆盖虚函数] QAccessibleInterface *QQuickWindow::accessibleRoot() const

返回此窗口的可访问性接口，如果无法创建此接口，则返回0。

[信号] void QQuickWindow::afterAnimating()

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

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

[信号，自6.0起] void QQuickWindow::afterFrameEnd()

在场景图提交帧时发出此信号。在afterRendering等其他相关信号之后发出。这是在渲染帧时场景图渲染线程发出的最后一个信号。

此函数是在Qt 6.0中引入的。

另请参阅：beforeFrameBegin() 和 rendererInterface。

[信号] void QQuickWindow::afterRenderPassRecording()

此信号在场景图记录其主要渲染通道的命令之后发出，但此通道尚未在命令缓冲区中最终完成。

此信号在afterRendering之前发出，并保证帧以及场景图主要渲染通道的记录仍然活跃。这允许在不生成单独的完整渲染通道的情况下插入命令（通常会清除附加的图像）。可以通过QSGRendererInterface查询原生图形对象。

另请参阅：rendererInterface() 和 场景图 - RHI 在 QML 下。

[信号] void QQuickWindow::afterRendering()

信号在场景图将其命令添加到命令缓冲区之后发出，该命令缓冲区尚未提交到图形队列。如果需要，连接到此信号的槽功能可以通过 QSGRendererInterface 在之前查询原生资源，例如命令缓冲区。请注意，渲染通道（或通道）在此点已经被记录，无法在场景图通道内部添加更多命令。相反，请使用 afterRenderPassRecording()。因此，与Qt 5相比，在Qt 6中此信号的使用有限。相反，通常使用 beforeRendering() 和 beforeRenderPassRecording()，或者 beforeRendering() 和 afterRenderPassRecording() 来实现自定义渲染的下层或叠加。

另请参阅 rendererInterface()，Scene Graph - RHI Under QML，Scene Graph - OpenGL Under QML，Scene Graph - Metal Under QML，Scene Graph - Vulkan Under QML，以及 Scene Graph - Direct3D 11 Under QML。

[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() 和 场景图 - RHI 在 QML 下。

[信号] void QQuickWindow::beforeRendering()

该信号在完成帧的准备后发出，这意味着存在一个处于记录模式中的命令缓冲区（如有必要）。如果需要，与该信号连接的槽函数可以通过 QSGRendererInterface 查询原生资源，如之前的命令。请注意，此时主渲染流的记录尚未开始，并且在该流中添加命令是不可能的。开始一个流意味着清除颜色、深度和模板缓冲区，因此仅通过连接到该信号无法实现下层渲染。相反，应该连接到 beforeRenderPassRecording。然而，如果希望记录复制的命令类型，仍需要连接到此信号，因为这些命令不能在渲染流中排队。

另请参阅 rendererInterface()，Scene Graph - RHI Under QML，Scene Graph - OpenGL Under QML，Scene Graph - Metal Under QML，Scene Graph - Vulkan Under QML，以及 Scene Graph - Direct3D 11 Under QML。

[信号] 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。

[重写 虚拟 保护] 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。

[自 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纹理不能在纹理图集中使用。

在options中设置TextureHasAlphaChannel对此函数没有意义，因为假设整数通道和混合是默认的。要取消选择，设置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::RGBA8之类的纹理格式的纹理上不设置标志是完全正常的。

由于texture已经创建且包含mipmap的存在与否，因此不会由options控制mipmap。

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

如果纹理拥有其底层的本地图形资源（OpenGL纹理对象、Vulkan图像等），这取决于QRhiTexture是如何创建的（QRhiTexture::create()或QRhiTexture::createFrom()），并且此函数无法控制或更改。

此功能自Qt 6.6版引入。

另请参阅 createTextureFromImage、sceneGraphInitialized和QSGTexture。

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）时，不需要调用此函数。在 OpenGL、Direct 3D 11 等未公开原生命令缓冲区概念的图形 API 中，beginExternalCommands()和endExternalCommands()一起提供了Qt 5 resetOpenGLState()函数的替代方案。

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

另请参阅 beginExternalCommands和QQuickOpenGLUtils::resetOpenGLState。

[覆盖虚受保护] bool QQuickWindow::event(QEvent *event)

重新实现：QWindow::event(QEvent *ev)。

[覆盖虚保护] void QQuickWindow::exposeEvent(QExposeEvent *)

重实现了：QWindow::exposeEvent(QExposeEvent *ev).

[覆盖虚保护] void QQuickWindow::focusInEvent(QFocusEvent *ev)

重实现了：QWindow::focusInEvent(QFocusEvent *ev).

[覆盖虚保护] void QQuickWindow::focusOutEvent(QFocusEvent *ev)

重实现了：QWindow::focusOutEvent(QFocusEvent *ev).

[信号] void QQuickWindow::frameSwapped()

当已为呈现准备帧时，将发出此信号。启用垂直同步时，在连续动画场景中，信号最多在每个垂直同步间隔内发出一次。

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

QImage QQuickWindow::grabWindow()

捕获窗口内容并返回为图像。

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

[静态，自 6.0 版起] QSGRendererInterface::GraphicsApi QQuickWindow::graphicsApi()

返回在当前时间点初始化场景图时将使用的图形 API。

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

这并不总是方便的。如果应用程序需要在设置外部框架或需要与 setGraphicsDevice() 以方式如场景图内置 API 选择逻辑依存的方式工作时，并不是在所有情况下都能在实际将操作推迟到 QQuickWindow 已可见之后或 QQuickRenderControl::initialize() 调用时才执行这些操作。

因此，这个静态函数作为 setGraphicsApi() 的对应物提供：它可以随时调用，结果反映场景图在调用点初始化时会选择的 API。

此函数是在Qt 6.0中引入的。

另请参阅：setGraphicsApi。

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

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

此函数是在Qt 6.0中引入的。

另请参阅：setGraphicsConfiguration。

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

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

此函数是在Qt 6.0中引入的。

另请参阅：setGraphicsDevice。

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

返回对描述 RHI 部分内部状态的 GraphicsStateInfo 结构的引用，特别是后端（如 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。

[重写虚拟受保护] void QQuickWindow::keyPressEvent(QKeyEvent *e)

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

[重写虚拟受保护] void QQuickWindow::keyReleaseEvent(QKeyEvent *e)

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

[重写虚拟受保护] void QQuickWindow::mouseDoubleClickEvent(QMouseEvent *event)

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

[重写虚拟受保护] void QQuickWindow::mouseMoveEvent(QMouseEvent *event)

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

[重写虚拟受保护] void QQuickWindow::mousePressEvent(QMouseEvent *event)

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

[重写虚拟受保护] void QQuickWindow::mouseReleaseEvent(QMouseEvent *event)

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

[slot] void QQuickWindow::releaseResources()

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

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

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

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

[自 6.0 开始] QQuickRenderTarget QQuickWindow::renderTarget() const

返回传递给 setRenderTarget() 的 QQuickRenderTarget，或者如果没有提供，则返回一个默认构造的实例

此函数是在Qt 6.0中引入的。

另请参阅 setRenderTarget()。

QSGRendererInterface *QQuickWindow::rendererInterface() const

返回当前的渲染器接口。这个值始终有效，绝不会为 null。

另请参阅 QSGRenderNode 和 QSGRendererInterface。

[重写虚受保护] void QQuickWindow::resizeEvent(QResizeEvent *ev)

重实现：QWindow::resizeEvent(QResizeEvent *ev)。

[自 6.6 开始] QRhi *QQuickWindow::rhi() const

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

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

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

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

此功能自Qt 6.6版引入。

[信号] void QQuickWindow::sceneGraphAboutToStop()

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

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

另请参阅sceneGraphInvalidated()。

[static] QString QQuickWindow::sceneGraphBackend()

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

另请参阅setSceneGraphBackend()。

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

场景图初始化过程中发生错误时发出此信号。

如果应用程序想以自定义方式处理错误，如图形上下文创建失败，则应连接到此信号。如果没有槽连接到信号，则将执行不同的操作：Quick将打印消息或显示消息框，并终止应用程序。

此信号将从GUI线程发出。

[signal] void QQuickWindow::sceneGraphInitialized()

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

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

[signal] void QQuickWindow::sceneGraphInvalidated()

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

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

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

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

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

将任务job安排在达到指定的stage时运行。

这是对QQuickWindow中类似信号的便利，用于“一次”任务。

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

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

如果渲染在不同的线程上执行，则作业将在渲染线程上发生。

如果 阶段 是 无阶段，作业 将在渲染线程不忙于渲染帧时尽可能早地运行。如果在作业提交或处理时窗口未公开，并且无法渲染，作业将被删除而不会执行 run() 方法。如果使用的是非线程渲染器，作业的 run() 方法将同步执行。当使用 OpenGL 进行渲染时，在执行任何作业之前（包括 无阶段 作业），OpenGL 上下文将更改为渲染器的上下文。

另请参阅beforeRendering，afterRendering，beforeSynchronizing，afterSynchronizing，frameSwapped，以及 sceneGraphInvalidated。

[静态] void QQuickWindow::setDefaultAlphaBuffer(bool useAlpha)

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

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

另请参阅hasDefaultAlphaBuffer。

[静态，自 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进行渲染，场景图�始化后调用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）创建并传递给场景图使用匹配的图形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);
...

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

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

此函数是在Qt 6.0中引入的。

另请参阅：graphicsDevice()、QQuickRenderControl、setRenderTarget() 和 setGraphicsApi()。

void QQuickWindow::setPersistentGraphics(bool persistent)

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

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

另请参阅：isPersistentGraphics()、setPersistentSceneGraph()、sceneGraphInitialized()、sceneGraphInvalidated() 和 releaseResources()。

void QQuickWindow::setPersistentSceneGraph(bool persistent)

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

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

另请参阅：isPersistentSceneGraph()、setPersistentGraphics()、sceneGraphInvalidated()、sceneGraphInitialized() 和 releaseResources()。

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

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

QQuickRenderTarget用于表示可渲染的原生对象（通常是二维纹理和相关的属性，例如像素大小）的一个不透明句柄。

默认构造的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。

此函数是在Qt 6.0中引入的。

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

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

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

这是一个重载函数。

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

另请参阅 sceneGraphBackend().

[静态] void QQuickWindow::setTextRenderType(QQuickWindow::TextRenderType renderType)

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

另请参阅 textRenderType().

[重载虚保护] void QQuickWindow::showEvent(QShowEvent *)

重新实现：QWindow::showEvent(QShowEvent *ev).

[自 6.6 起存在] QRhiSwapChain *QQuickWindow::swapChain() const

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

此功能自Qt 6.6版引入。

[重载虚保护] void QQuickWindow::tabletEvent(QTabletEvent *event)

重新实现：QWindow::tabletEvent(QTabletEvent *ev).

[静态] QQuickWindow::TextRenderType QQuickWindow::textRenderType()

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

另请参阅 setTextRenderType().

[槽] void QQuickWindow::update()

安排窗口渲染另一帧。

调用QQuickWindow::update()与QQuickItem::update()不同，无论底层场景图是否发生变化，它都会触发重绘。

[重载虚保护] void QQuickWindow::wheelEvent(QWheelEvent *event)

重新实现：QWindow::wheelEvent(QWheelEvent *ev).