QQuickRenderControl RHI 示例
演示如何将Qt Quick 场景渲染为QRhiTexture 。
本例演示了如何设置一个Qt Quick 场景，并将其渲染重定向到QRhiTexture 。然后，应用程序就可以随意处理每帧生成的纹理。本示例是一个基于QWidget 的应用程序，它可执行图像数据回读，然后显示收集到的每帧渲染结果以及每帧基于 CPU 和 GPU 的时序信息。
通过使用 Qt 3D 图形应用程序接口抽象，该示例与任何特定图形应用程序接口无关。启动时，会显示一个对话框，其中包含平台可能支持的 3D API。
QDialog apiSelect; QVBoxLayout *selLayout = new QVBoxLayout; selLayout->addWidget(new QLabel(QObject::tr("Select graphics API to use"))); QListWidget *apiList = new QListWidget; QVarLengthArray<QSGRendererInterface::GraphicsApi, 5> apiValues; #ifdef Q_OS_WIN apiList->addItem("Direct3D 11"); apiValues.append(QSGRendererInterface::Direct3D11); apiList->addItem("Direct3D 12"); apiValues.append(QSGRendererInterface::Direct3D12); #endif #if QT_CONFIG(metal) apiList->addItem("Metal"); apiValues.append(QSGRendererInterface::Metal); #endif #if QT_CONFIG(vulkan) apiList->addItem("Vulkan"); apiValues.append(QSGRendererInterface::Vulkan); #endif #if QT_CONFIG(opengl) apiList->addItem("OpenGL / OpenGL ES"); apiValues.append(QSGRendererInterface::OpenGL); #endif if (apiValues.isEmpty()) { QMessageBox::critical(nullptr, QObject::tr("No 3D graphics API"), QObject::tr("No 3D graphics APIs are supported in this Qt build")); return 1; }
注意： 不保证所有选择都能在特定平台上运行。
一旦做出选择，就会加载 QML 文件。不过，我们不会简单地创建一个QQuickView 实例和show() 它。相反，管理Qt Quick 场景的QQuickWindow 永远不会显示在屏幕上。相反，应用程序通过QQuickRenderControl 控制何时何地渲染。
voidMainWindow::load(constQString&filename) { reset(); m_renderControl.reset(newQQuickRenderControl); m_scene.reset(newQQuickWindow(m_renderControl.get());// 在 QRhiCommandBuffer 上启用 lastCompletedGpuTime()，如果底层 3D API 支持的话 QQuickGraphicsConfigurationconfig; config.setTimestamps(true); m_scene->setGraphicsConfiguration(config);#if QT_CONFIG(vulkan) if(m_scene->graphicsApi()==QSGRendererInterface::Vulkan) m_scene->setVulkanInstance(m_vulkanInstance);#endifm_qmlEngine.reset(newQQmlEngine); m_qmlComponent.reset(newQQmlComponent(m_qmlEngine.get()、 QUrl::fromLocalFile(filename));if(m_qmlComponent->isError()) {for(constQQmlError&error: m_qmlComponent->errors()) qWarning() << error.url() << error.line() << error; QMessageBox::critical(this,tr("Cannot load QML scene"),tr("Failed to load %1").arg(filename)); reset();return; }
对象树实例化后，会查询根项（Rectangle ），确保其大小有效，然后进行传播。
注： 不支持在对象树中使用Window 元素的场景。
QObject*rootObject = m_qmlComponent->create();if(m_qmlComponent->isError()) {for(constQQmlError&error: m_qmlComponent->errors()) qWarning() << error.url() << error.line() << error; QMessageBox::critical(this,tr("Cannot load QML scene"),tr("Failed to create component")); reset();return; } QQuickItem*rootItem = qobject_cast<QQuickItem*>(rootObject);if(!rootItem) {// 摆脱屏幕上的窗口，如果根对象是一个窗口 if(QQuickWindow*w = qobject_cast<*>(rootObject)QQuickWindow*>(rootObject))删除w； QMessageBox::critical(this,tr("Invalid root item in QML scene"),tr("Root object is not a QQuickItem.如果这是一个包含 Window 的场景，请注意不支持此类场景。")); reset();return; }if(rootItem->size().width()< 16) rootItem->setSize(QSizeF(640, 360)); m_scene->contentItem()->setSize(rootItem->size()); m_scene->setGeometry(0, 0, rootItem->width(), rootItem->height()); rootItem->setParentItem(m_scene->contentItem()); m_statusMsg->setText(tr("QML scene loaded"));
此时还没有初始化渲染资源，也就是说，还没有使用本地 3D 图形 API 进行任何操作。只有在下一步才会实例化QRhi ，而这正是在引擎盖下设置 Vulkan、Metal、Direct 3D 等渲染系统的触发因素。
const bool initSuccess = m_renderControl->initialize(); if (!initSuccess) { QMessageBox::critical(this, tr("Cannot initialize renderer"), tr("QQuickRenderControl::initialize() failed")); reset(); return; } const QSGRendererInterface::GraphicsApi api = m_scene->rendererInterface()->graphicsApi(); switch (api) { case QSGRendererInterface::OpenGL: m_apiMsg->setText(tr("OpenGL")); break; case QSGRendererInterface::Direct3D11: m_apiMsg->setText(tr("D3D11")); break; case QSGRendererInterface::Direct3D12: m_apiMsg->setText(tr("D3D12")); break; case QSGRendererInterface::Vulkan: m_apiMsg->setText(tr("Vulkan")); break; case QSGRendererInterface::Metal: m_apiMsg->setText(tr("Metal")); break; default: m_apiMsg->setText(tr("Unknown 3D API")); break; } QRhi *rhi = m_renderControl->rhi(); if (!rhi) { QMessageBox::critical(this, tr("Cannot render"), tr("No QRhi from QQuickRenderControl")); reset(); return; } m_driverInfoMsg->setText(QString::fromUtf8(rhi->driverInfo().deviceName));
注： 此应用程序使用 Qt XML 创建QRhi 实例的模型。这并不是唯一可行的方法：如果应用程序维护了自己的QRhi （以及 OpenGL 上下文、Vulkan 设备等），则Qt Quick 可被请求采用并使用现有的QRhi 。这可以通过将QQuickGraphicsDevice::fromRhi() 创建的QQuickGraphicsDevice 传递给QQuickWindow 来实现，与上述代码段中设置QQuickGraphicsConfiguration 的方式类似。例如，如果希望在QRhiWidget 中使用Qt Quick 渲染的纹理：在这种情况下，需要将QRhiWidget 的QRhi 传递给Qt Quick ，而不是让Qt Quick 创建自己的纹理。
一旦QQuickRenderControl::initialize() 成功，渲染器就可以运行了。为此，我们需要一个颜色缓冲区来进行渲染。
QQuickRenderTarget 是一个轻量级隐式共享类，它携带（但不拥有）各种本地或 对象集，这些对象用于描述纹理、渲染目标或类似内容。在 上调用 () （请记住，我们有一个在屏幕上不可见的 ）会触发将 场景图的渲染重定向到应用程序提供的纹理中。在使用 （而不是 OpenGL 纹理 ID 或 VkImage 对象等本地 3D API 对象）时，应用程序应设置 ，然后通过 () 将其传递给 。QRhi QQuickWindow setRenderTarget QQuickWindow Qt Quick QRhi QRhiTextureRenderTarget QQuickRenderTarget::fromRhiRenderTarget Qt Quick
const QSize pixelSize = rootItem->size().toSize(); // no scaling, i.e. the item size is in pixels m_texture.reset(rhi->newTexture(QRhiTexture::RGBA8, pixelSize, 1, QRhiTexture::RenderTarget | QRhiTexture::UsedAsTransferSource)); if (!m_texture->create()) { QMessageBox::critical(this, tr("Cannot render"), tr("Cannot create texture object")); reset(); return; } m_ds.reset(rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil, pixelSize, 1)); if (!m_ds->create()) { QMessageBox::critical(this, tr("Cannot render"), tr("Cannot create depth-stencil buffer")); reset(); return; } QRhiTextureRenderTargetDescription rtDesc(QRhiColorAttachment(m_texture.get())); rtDesc.setDepthStencilBuffer(m_ds.get()); m_rt.reset(rhi->newTextureRenderTarget(rtDesc)); m_rpDesc.reset(m_rt->newCompatibleRenderPassDescriptor()); m_rt->setRenderPassDescriptor(m_rpDesc.get()); if (!m_rt->create()) { QMessageBox::critical(this, tr("Cannot render"), tr("Cannot create render target")); reset(); return; } m_scene->setRenderTarget(QQuickRenderTarget::fromRhiRenderTarget(m_rt.get()));
注意： 一定要为Qt Quick 提供深度-模版缓冲区，因为Qt Quick 场景图在渲染时可能会使用这两个缓冲区以及深度和模版测试。
主渲染循环如下。这也显示了如何执行图像的 GPU->CPU 回读。一旦QImage 可用，基于QWidget 的用户界面就会相应更新。在此，我们将不再赘述相关细节。
该示例还演示了一种简单的方法，用于衡量在 CPU 和 GPU 上渲染帧的成本。由于QRhi 的某些内部行为，离屏渲染的帧非常适合用于此目的，这意味着原本异步的操作（即只有在渲染后续帧时才会完成），在QRhi::endOffscreenFrame() （即QQuickRenderControl::endFrame() ）返回后就能保证准备就绪。我们在回读纹理时使用了这一知识，它也适用于 GPU 时间戳。这就是为什么应用程序可以显示每一帧的 GPU 时间，同时保证该时间实际上指的是那一帧（而不是更早的一帧）。有关 GPU 时间的详细信息，请参阅lastCompletedGpuTime() 。CPU 端的时序是通过QElapsedTimer 获取的。
QElapsedTimer cpuTimer; cpuTimer.start(); m_renderControl->polishItems(); m_renderControl->beginFrame(); m_renderControl->sync(); m_renderControl->render(); QRhi *rhi = m_renderControl->rhi(); QRhiReadbackResult readResult; QRhiResourceUpdateBatch *readbackBatch = rhi->nextResourceUpdateBatch(); readbackBatch->readBackTexture(m_texture.get(), &readResult); m_renderControl->commandBuffer()->resourceUpdate(readbackBatch); m_renderControl->endFrame(); const double gpuRenderTimeMs = m_renderControl->commandBuffer()->lastCompletedGpuTime() * 1000.0; const double cpuRenderTimeMs = cpuTimer.nsecsElapsed() / 1000000.0; // m_renderControl->begin/endFrame() is based on QRhi's // begin/endOffscreenFrame() under the hood, meaning it does not do // pipelining, unlike swapchain-based frames, and therefore the readback is // guaranteed to complete once endFrame() returns. QImage wrapperImage(reinterpret_cast<const uchar *>(readResult.data.constData()), readResult.pixelSize.width(), readResult.pixelSize.height(), QImage::Format_RGBA8888_Premultiplied); QImage result; if (rhi->isYUpInFramebuffer()) result = wrapperImage.flipped(); else result = wrapperImage.copy();
其中一个重要部分是Qt Quick 动画的步进。由于我们没有一个屏幕窗口可以通过测量经过时间、普通计时器或基于呈现率的节流来驱动动画系统，因此重定向Qt Quick 渲染往往意味着动画驱动需要由应用程序接管。否则，动画会根据普通系统计时器运行，但实际经过的时间往往与屏幕外渲染场景的预期感知无关。考虑在一个紧凑的循环中连续渲染 5 个帧。这 5 帧中的动画如何移动取决于 CPU 执行循环迭代的速度。这几乎是不理想的。为确保动画效果的一致性，请安装自定义的 QAnimationDriver。虽然这是一个面向高级用户的未注明（但公开）API，但此处的示例提供了一个使用它的简单示例。
class AnimationDriver : public QAnimationDriver { public: AnimationDriver(QObject *parent = nullptr) : QAnimationDriver(parent), m_step(16) { } void setStep(int milliseconds) { m_step = milliseconds; } void advance() override { m_elapsed += m_step; advanceAnimation(); } qint64 elapsed() const override { return m_elapsed; } private: int m_step; qint64 m_elapsed = 0; };
该应用程序有一个QSlider ，可用于将动画步长值从默认的 16 毫秒改为其他值。注意调用 QAnimationDriver 子类的 setStep() 函数。
QSlider *animSlider = new QSlider; animSlider->setOrientation(Qt::Horizontal); animSlider->setMinimum(1); animSlider->setMaximum(1000); QLabel *animLabel = new QLabel; QObject::connect(animSlider, &QSlider::valueChanged, animSlider, [this, animLabel, animSlider] { if (m_animationDriver) m_animationDriver->setStep(animSlider->value()); animLabel->setText(tr("Simulated elapsed time per frame: %1 ms").arg(animSlider->value())); }); animSlider->setValue(16); QCheckBox *animCheckBox = new QCheckBox(tr("Custom animation driver")); animCheckBox->setToolTip(tr("Note: Installing the custom animation driver makes widget drawing unreliable, depending on the platform.\n" "This is due to widgets themselves relying on QPropertyAnimation and similar, which are driven by the same QAnimationDriver.\n" "In any case, the functionality of the widgets are not affected, just the rendering may lag behind.\n" "When not checked, Qt Quick animations advance based on the system time, i.e. the time elapsed since the last press of the Next button.")); QObject::connect(animCheckBox, &QCheckBox::checkStateChanged, animCheckBox, [this, animCheckBox, animSlider, animLabel] { if (animCheckBox->isChecked()) { animSlider->setEnabled(true); animLabel->setEnabled(true); m_animationDriver = new AnimationDriver(this); m_animationDriver->install(); m_animationDriver->setStep(animSlider->value()); } else { animSlider->setEnabled(false); animLabel->setEnabled(false); delete m_animationDriver; m_animationDriver = nullptr; } }); animSlider->setEnabled(false); animLabel->setEnabled(false); controlLayout->addWidget(animCheckBox); controlLayout->addWidget(animLabel); controlLayout->addWidget(animSlider);
注： 可通过animCheckBox 复选框选择安装自定义动画驱动程序。这样可以比较安装和不安装自定义动画驱动程序的效果。此外，在某些平台上（也可能取决于主题），启用自定义驱动程序可能会导致部件绘制延迟。这是意料之中的，因为如果某些部件的动画（如QPushButton 或QCheckBox 的高亮部分）是通过QPropertyAnimation 和类似的方式管理的，那么这些动画将由相同的 QAnimationDriver 驱动，并且在点击按钮请求新的帧之前不会前进。
只需调用 advance() 就能在每一帧之前（即在调用QQuickRenderControl::beginFrame() 之前）推进动画：
void MainWindow::stepAnimations() { if (m_animationDriver) { // Now the Qt Quick scene will think that <slider value> milliseconds have // elapsed and update animations accordingly when doing the next frame. m_animationDriver->advance(); } }
另请参见 QRhi,QQuickRenderControl, 和QQuickWindow 。
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
