QQuickRenderControl Class

成员函数文档

[explicit] QQuickRenderControl::QQuickRenderControl(QObject *parent = nullptr)

创建一个 QQuickRenderControl 对象，其父对象为parent 。

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

销毁该实例。释放所有场景图资源。

另请参阅 invalidate()。

[since 6.0] void QQuickRenderControl::beginFrame()

指定图形帧的开始。对sync()或render()的调用必须被beginFrame()和endFrame()的调用所包围。

与早期仅支持 OpenGL 的 Qt 5 不同，使用其他图形 API 进行渲染需要更明确地定义帧的起始和结束点。当通过 `QQuickRenderControl` 手动驱动渲染循环时，现在需要由 `QQuickRenderControl ` 的用户来指定这些点。

一个典型的更新步骤（包括将渲染结果初始化到现有纹理中）可能如下所示。该示例代码片段基于 Direct3D 11，但相同的概念也适用于其他图形 API。

if(!m_quickInitialized) {
    m_quickWindow->setGraphicsDevice(QQuickGraphicsDevice::fromDeviceAndContext(m_engine->device(), m_engine->context()));

    if(!m_renderControl->initialize())
        qWarning("Failed to initialize redirected Qt Quick rendering");

    m_quickWindow->setRenderTarget(QQuickRenderTarget::fromNativeTexture({ quint64(m_res.texture), 0},
                                                                         QSize(QML_WIDTH,QML_HEIGHT),
                                                                         SAMPLE_COUNT));

    m_quickInitialized= true;
}

m_renderControl->polishItems();

m_renderControl->beginFrame();
m_renderControl->sync();
m_renderControl->render();
m_renderControl->endFrame();//Qt Quick 的渲染命令在此处提交至设备上下文

该函数于 Qt 6.0 中引入。

另请参阅 endFrame()、initialize()、sync()、render()、QQuickGraphicsDevice 以及QQuickRenderTarget 。

[since 6.6] QRhiCommandBuffer *QQuickRenderControl::commandBuffer() const

返回当前的命令缓冲区。

一旦调用beginFrame()，系统会自动建立一个QRhiCommandBuffer 。这是场景图Qt Quick 所使用的命令缓冲区，但在某些情况下，应用程序可能也需要查询该缓冲区，例如为了执行资源更新（例如纹理回读）。

返回的命令缓冲区引用仅应在beginFrame()与endFrame()之间使用。存在特定例外情况，例如在endFrame()之后、但下一个beginFrame()之前，对该命令缓冲区调用lastCompletedGpuTime()是有效的。

该函数在 Qt 6.6 中引入。

另请参阅 rhi()、beginFrame() 和endFrame()。

[since 6.0] void QQuickRenderControl::endFrame()

指定图形帧的结束。对sync()或render()的调用必须被beginFrame()和endFrame()的调用所包围。

调用此函数时，场景图中排入队列的任何图形命令将被提交至上下文或命令队列（视具体情况而定）。

该函数在 Qt 6.0 中引入。

另请参阅 beginFrame()、initialize()、sync()、render()、QQuickGraphicsDevice 以及QQuickRenderTarget 。

[since 6.0] bool QQuickRenderControl::initialize()

初始化场景图资源。当使用 Vulkan、Metal、OpenGL 或 Direct3D 等图形 API 进行Qt Quick 渲染时，调用此函数后，QQuickRenderControl 将设置相应的渲染引擎。只要QQuickRenderControl 存在，该渲染基础设施就一直存在。

若要控制Qt Quick 使用哪种图形 API，请使用QSGRendererInterface:GraphicsApi 常量之一调用QQuickWindow::setGraphicsApi()。此操作必须在调用本函数之前完成。

若要防止场景图创建自己的设备和上下文对象，请通过调用QQuickWindow::setGraphicsDevice() 指定一个适当的QQuickGraphicsDevice ，该对象应封装现有的图形对象。

若要配置要启用的设备扩展（例如，针对 Vulkan），请在本函数调用之前调用QQuickWindow::setGraphicsConfiguration()。

成功时返回true ，否则返回false 。

使用默认的Qt Quick 适配时，此函数会创建一个新的QRhi 对象，这与未使用QQuickRenderControl 时屏幕上的QQuickWindow 的行为类似。要使这个新的QRhi 对象采用某些现有的设备或上下文资源（例如，使用现有的QOpenGLContext 而不是创建一个新的），请如上所述使用QQuickWindow::setGraphicsDevice()。 当应用程序希望让Qt Quick 的渲染使用已存在的QRhi 对象时，也可通过QQuickGraphicsDevice::fromRhi()实现。当设置了此类QQuickGraphicsDevice （其引用了已存在的QRhi ）时，initialize()中将不会创建新的、专用的QRhi 对象。

该函数在 Qt 6.0 中引入。

另请参阅 QQuickRenderTarget 、QQuickGraphicsDevice 以及QQuickGraphicsConfiguration::preferredInstanceExtensions()。

void QQuickRenderControl::invalidate()

停止渲染并释放资源。

这相当于当窗口被隐藏时，真实的QQuickWindow 所执行的清理操作。

该函数由析构函数调用。因此通常无需直接调用它。

一旦调用了 invalidate()，就可以通过再次调用initialize() 来重用该QQuickRenderControl 实例。

void QQuickRenderControl::polishItems()

应尽可能在调用 `sync()` 之前尽早调用此函数。在多线程环境下，渲染操作可以与该函数并行进行。

void QQuickRenderControl::prepareThread(QThread *targetThread)

准备在GUI线程之外渲染Qt Quick 场景。

targetThread 指定将在此线程上进行同步和渲染。在单线程场景下，无需调用此函数。

void QQuickRenderControl::render()

使用当前上下文渲染场景图。

[signal] void QQuickRenderControl::renderRequested()

当需要渲染场景图时，会发出此信号。无需调用sync()。

[virtual] QWindow *QQuickRenderControl::renderWindow(QPoint *offset)

在子类中重新实现，以返回该渲染控件实际进行渲染的目标窗口。

如果 `offset ` 不为空，则将其设置为该控件在窗口内的偏移量。

[static] QWindow *QQuickRenderControl::renderWindowFor(QQuickWindow *win, QPoint *offset = nullptr)

返回win 正在渲染到的实际窗口（如果存在）。

如果 `offset ` 不为空，则将其设置为该窗口内渲染内容的偏移量。

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

返回与该QQuickRenderControl 关联的QRhi 。

该函数在 Qt 6.6 中引入。

另请参阅 commandBuffer()、beginFrame() 和endFrame()。

[since 6.0] int QQuickRenderControl::samples() const

返回当前的采样数。1 或 0 表示不进行多采样。

该函数在 Qt 6.0 中引入。

另请参阅 setSamples()。

[signal] void QQuickRenderControl::sceneChanged()

当场景图更新时会发出此信号，这意味着需要调用polishItems() 和sync()。如果sync() 返回 true，则需要调用render()。

[since 6.0] void QQuickRenderControl::setSamples(int sampleCount)

设置多采样所使用的采样数。当sampleCount 为0或1时，多采样功能将被禁用。

该函数在 Qt 6.0 中引入。

另请参阅 samples()、initialize() 和QQuickRenderTarget 。

bool QQuickRenderControl::sync()

此函数用于将 QML 场景与渲染场景图进行同步。

如果使用了专用的渲染线程，则在调用此函数期间应阻塞 GUI 线程。

如果同步操作更改了场景图，则返回true。

[since 6.0] QQuickWindow *QQuickRenderControl::window() const

返回与该QQuickRenderControl 关联的QQuickWindow 。

该函数于 Qt 6.0 中引入。