QQuickRenderControl Class
Die Klasse QQuickRenderControl bietet einen Mechanismus zum Rendern des Qt Quick -Szenegraphs auf ein Offscreen-Renderziel in einer vollständig anwendungsgesteuerten Weise. Mehr...
| Kopfzeile: | #include <QQuickRenderControl> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Quick)target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake: | QT += quick |
| Vererbungen: | QObject |
Öffentliche Funktionen
| QQuickRenderControl(QObject *parent = nullptr) | |
| virtual | ~QQuickRenderControl() override |
(since 6.0) void | beginFrame() |
(since 6.6) QRhiCommandBuffer * | commandBuffer() const |
(since 6.0) void | endFrame() |
(since 6.0) bool | initialize() |
| void | invalidate() |
| void | polishItems() |
| void | prepareThread(QThread *targetThread) |
| void | render() |
| virtual QWindow * | renderWindow(QPoint *offset) |
(since 6.6) QRhi * | rhi() const |
(since 6.0) int | samples() const |
(since 6.0) void | setSamples(int sampleCount) |
| bool | sync() |
(since 6.0) QQuickWindow * | window() const |
Signale
| void | renderRequested() |
| void | sceneChanged() |
Statische öffentliche Mitglieder
| QWindow * | renderWindowFor(QQuickWindow *win, QPoint *offset = nullptr) |
Detaillierte Beschreibung
QQuickWindow und QQuickView und ihre zugehörigen internen Renderschleifen rendern die Qt Quick Szene auf ein natives Fenster. In einigen Fällen, zum Beispiel bei der Integration mit OpenGL-, Vulkan-, Metal- oder Direct 3D-Renderern von Drittanbietern, kann es nützlich sein, die Szene in eine Textur zu übertragen, die dann von der externen Rendering-Engine auf beliebige Weise verwendet werden kann. Ein solcher Mechanismus ist auch bei der Integration mit einem VR-Framework wichtig. QQuickRenderControl ermöglicht dies auf eine hardwarebeschleunigte Weise, im Gegensatz zur leistungsmäßig begrenzten Alternative der Verwendung von QQuickWindow::grabWindow()
Bei der Verwendung von QQuickRenderControl darf QQuickWindow nicht shown sein (es wird nicht auf dem Bildschirm sichtbar sein) und es gibt kein darunter liegendes natives Fenster für es. Stattdessen wird die Instanz QQuickWindow mit dem Render-Control-Objekt verknüpft, indem die Überladung des QQuickWindow -Konstruktors verwendet wird und eine Textur oder ein Bildobjekt über QQuickWindow::setRenderTarget() angegeben wird. Das QQuickWindow Objekt ist immer noch wichtig, da es die Qt Quick Szene repräsentiert und den Großteil der Mechanismen zur Verwaltung der Szene und der Ereignisausgabe bereitstellt. Es fungiert jedoch nicht als echtes Bildschirmfenster aus der Sicht des Windowing-Systems.
Die Verwaltung der Grafikgeräte, Kontexte, Bild- und Texturobjekte obliegt der Anwendung. Das Gerät oder der Kontext, der von Qt Quick verwendet werden soll, muss vor dem Aufruf von initialize() erstellt werden. Die Erstellung des Texturobjekts kann aufgeschoben werden, siehe unten. Qt 5.4 führt die Möglichkeit für QOpenGLContext ein, bestehende native Kontexte zu übernehmen. Zusammen mit QQuickRenderControl ist es damit möglich, eine QOpenGLContext zu erstellen, die den bestehenden Kontext einer externen Rendering-Engine übernimmt. Diese neue QOpenGLContext kann dann verwendet werden, um die Qt Quick Szene in eine Textur zu rendern, auf die auch der Kontext der anderen Engine zugreifen kann. Für Vulkan, Metal und Direct 3D gibt es keine von Qt bereitgestellten Wrapper für Geräteobjekte, so dass vorhandene Objekte über QQuickWindow::setGraphicsDevice() übergeben werden können, wie sie sind.
Das Laden und die Instanziierung der QML-Komponenten erfolgt über QQmlEngine. Sobald das Root-Objekt erstellt ist, muss es dem QQuickWindow's contentItem() geparentet werden.
Anwendungen müssen normalerweise mit 4 wichtigen Signalen verbunden werden:
- QQuickWindow::sceneGraphInitialized() Wird zu einem bestimmten Zeitpunkt nach dem Aufruf von QQuickRenderControl::initialize() ausgegeben. Auf dieses Signal hin wird von der Anwendung erwartet, dass sie ihr Framebuffer-Objekt erstellt und es mit dem QQuickWindow verknüpft.
- QQuickWindow::sceneGraphInvalidated() Wenn die Ressourcen der Szene freigegeben werden, kann auch das Framebuffer-Objekt zerstört werden.
- QQuickRenderControl::renderRequested() Zeigt an, dass die Szene gerendert werden muss, indem render() aufgerufen wird. Nachdem der Kontext aktuell gemacht wurde, wird von den Anwendungen erwartet, dass sie render() aufrufen.
- QQuickRenderControl::sceneChanged() Zeigt an, dass sich die Szene geändert hat, was bedeutet, dass vor dem Rendering auch eine Aufpolierung und Synchronisierung erforderlich ist.
Um Ereignisse, z. B. Maus- oder Tastaturereignisse, an die Szene zu senden, verwenden Sie QCoreApplication::sendEvent() mit der Instanz QQuickWindow als Empfänger.
Bei Tastenereignissen kann es auch erforderlich sein, den Fokus manuell auf das gewünschte Element zu setzen. In der Praxis bedeutet dies den Aufruf von forceActiveFocus() auf dem gewünschten Element, z.B. dem Stammelement der Szene, sobald es mit der Szene assoziiert ist ( QQuickWindow).
Hinweis: Im Allgemeinen wird QQuickRenderControl in Kombination mit allen Qt Quick Backends unterstützt. Einige Funktionen, insbesondere grab(), sind jedoch möglicherweise nicht in allen Fällen verfügbar.
Dokumentation der Mitgliedsfunktionen
[explicit] QQuickRenderControl::QQuickRenderControl(QObject *parent = nullptr)
Konstruiert ein QQuickRenderControl-Objekt, mit dem übergeordneten Objekt parent.
[override virtual noexcept] QQuickRenderControl::~QQuickRenderControl()
Zerstört die Instanz. Gibt alle Scenegraph-Ressourcen frei.
Siehe auch invalidate().
[since 6.0] void QQuickRenderControl::beginFrame()
Gibt den Beginn eines Grafikrahmens an. Aufrufe von sync() oder render() müssen von Aufrufen von beginFrame() und endFrame() umschlossen sein.
Anders als in der früheren, nur auf OpenGL beschränkten Welt von Qt 5, erfordert das Rendering mit anderen Grafik-APIs besser definierte Punkte für den Beginn und das Ende eines Frames. Bei der manuellen Steuerung der Rendering-Schleife über QQuickRenderControl obliegt es nun dem Benutzer von QQuickRenderControl, diese Punkte festzulegen.
Ein typischer Aktualisierungsschritt, einschließlich der Initialisierung des Renderings in eine vorhandene Textur, könnte wie folgt aussehen. Das Beispiel geht von Direct3D 11 aus, aber die gleichen Konzepte gelten auch für andere Grafik-APIs.
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's Rendering-Befehle werden hier an den Gerätekontext übergeben
Hinweis: Diese Funktion muss und darf nicht aufgerufen werden, wenn die Anpassung software von Qt Quick verwendet wird.
Hinweis: Intern rufen beginFrame() und endFrame() beginOffscreenFrame() bzw. endOffscreenFrame() auf. Dies bedeutet, dass zum Zeitpunkt des Aufrufs dieser Funktion kein Frame (weder Offscreen- noch Swapchain-basiert) auf QRhi aufgezeichnet sein darf.
Diese Funktion wurde in Qt 6.0 eingeführt.
Siehe auch endFrame(), initialize(), sync(), render(), QQuickGraphicsDevice, und QQuickRenderTarget.
[since 6.6] QRhiCommandBuffer *QQuickRenderControl::commandBuffer() const
Gibt den aktuellen Befehlspuffer zurück.
Sobald beginFrame() aufgerufen wird, wird automatisch ein QRhiCommandBuffer eingerichtet. Das ist der Befehlspuffer, den Qt Quick scenegraph verwendet, aber in manchen Fällen möchten Anwendungen ihn auch abfragen, um beispielsweise Ressourcenaktualisierungen durchzuführen (z. B. ein Textur-Readback).
Die zurückgegebene Befehlspuffer-Referenz sollte nur zwischen beginFrame() und endFrame() verwendet werden. Es gibt bestimmte Ausnahmen, z. B. ist der Aufruf von lastCompletedGpuTime() auf den Befehlspuffer direkt nach endFrame(), aber vor dem nächsten beginFrame(), gültig.
Hinweis: Diese Funktion ist nicht anwendbar und gibt null zurück, wenn die software Adaption von Qt Quick verwendet wird.
Diese Funktion wurde in Qt 6.6 eingeführt.
Siehe auch rhi(), beginFrame(), und endFrame().
[since 6.0] void QQuickRenderControl::endFrame()
Gibt das Ende eines Grafikrahmens an. Aufrufe von sync() oder render() müssen von Aufrufen von beginFrame() und endFrame() umschlossen sein.
Wenn diese Funktion aufgerufen wird, werden alle Grafikbefehle, die sich in der Warteschlange des Szenegraphen befinden, an den Kontext oder die Befehlswarteschlange übergeben, je nachdem, was zutrifft.
Hinweis: Diese Funktion muss und darf nicht aufgerufen werden, wenn die software Anpassung von Qt Quick verwendet wird.
Diese Funktion wurde in Qt 6.0 eingeführt.
Siehe auch beginFrame(), initialize(), sync(), render(), QQuickGraphicsDevice, und QQuickRenderTarget.
[since 6.0] bool QQuickRenderControl::initialize()
Initialisiert die Ressourcen des Szenengraphen. Wenn eine Grafik-API wie Vulkan, Metal, OpenGL oder Direct3D für das Qt Quick Rendering verwendet wird, richtet QQuickRenderControl eine entsprechende Rendering-Engine ein, wenn diese Funktion aufgerufen wird. Diese Rendering-Infrastruktur existiert so lange, wie QQuickRenderControl existiert.
Um zu steuern, welche Grafik-API Qt Quick verwendet, rufen Sie QQuickWindow::setGraphicsApi() mit einer der Konstanten QSGRendererInterface:GraphicsApi auf. Dies muss vor dem Aufruf dieser Funktion geschehen.
Um zu verhindern, dass der Scenegraph seine eigenen Geräte- und Kontextobjekte erstellt, geben Sie ein entsprechendes QQuickGraphicsDevice an, das bestehende Grafikobjekte umschließt, indem Sie QQuickWindow::setGraphicsDevice() aufrufen.
Um zu konfigurieren, welche Geräteerweiterungen aktiviert werden sollen (zum Beispiel für Vulkan), rufen Sie QQuickWindow::setGraphicsConfiguration() vor dieser Funktion auf.
Hinweis: Bei Verwendung von Vulkan erstellt QQuickRenderControl nicht automatisch eine QVulkanInstance. Vielmehr liegt es in der Verantwortung der Anwendung, eine geeignete QVulkanInstance und associate it mit der QQuickWindow zu erstellen. Vor der Initialisierung der QVulkanInstance wird dringend empfohlen, die Liste der gewünschten Instanzerweiterungen von Qt Quick durch Aufruf der statischen Funktion QQuickGraphicsConfiguration::preferredInstanceExtensions() abzufragen und die zurückgegebene Liste an QVulkanInstance::setExtensions() zu übergeben.
Gibt bei Erfolg true zurück, andernfalls false.
Hinweis: Diese Funktion muss und darf nicht aufgerufen werden, wenn die software Anpassung von Qt Quick verwendet wird.
Bei der Standardanpassung Qt Quick erzeugt diese Funktion ein neues QRhi -Objekt, ähnlich wie bei einem QQuickWindow auf dem Bildschirm, wenn QQuickRenderControl nicht verwendet wurde. Damit dieses neue QRhi Objekt ein bestehendes Gerät oder eine Kontextressource übernimmt (z. B. ein bestehendes QOpenGLContext verwenden, anstatt ein neues zu erstellen), verwenden Sie QQuickWindow::setGraphicsDevice() wie oben erwähnt. Wenn die Anwendung das Qt Quick Rendering auf ein bereits vorhandenes QRhi Objekt anwenden möchte, ist dies ebenfalls über QQuickGraphicsDevice::fromRhi() möglich. Wenn ein solches QQuickGraphicsDevice, das ein bereits existierendes QRhi referenziert, gesetzt wird, wird kein neues, dediziertes QRhi Objekt in initialize() erstellt.
Diese Funktion wurde in Qt 6.0 eingeführt.
Siehe auch QQuickRenderTarget, QQuickGraphicsDevice, und QQuickGraphicsConfiguration::preferredInstanceExtensions().
void QQuickRenderControl::invalidate()
Beendet das Rendern und gibt die Ressourcen frei.
Dies ist das Äquivalent zu den Aufräumarbeiten, die bei einem echten QQuickWindow stattfinden, wenn das Fenster ausgeblendet wird.
Diese Funktion wird vom Destruktor aufgerufen. Daher besteht normalerweise keine Notwendigkeit, sie direkt aufzurufen.
Nach dem Aufruf von invalidate() ist es möglich, die Instanz QQuickRenderControl durch erneuten Aufruf von initialize() wieder zu verwenden.
Hinweis: Diese Funktion berücksichtigt weder QQuickWindow::persistentSceneGraph() noch QQuickWindow::persistentGraphics(). Dies bedeutet, dass kontextspezifische Ressourcen immer freigegeben werden.
void QQuickRenderControl::polishItems()
Diese Funktion sollte so spät wie möglich vor sync() aufgerufen werden. In einem Szenario mit mehreren Threads kann das Rendering parallel zu dieser Funktion erfolgen.
void QQuickRenderControl::prepareThread(QThread *targetThread)
Bereitet das Rendering der Szene Qt Quick außerhalb des GUI-Threads vor.
targetThread gibt den Thread an, in dem die Synchronisation und das Rendering stattfinden sollen. In einem Single-Thread-Szenario ist es nicht notwendig, diese Funktion aufzurufen.
void QQuickRenderControl::render()
Rendert den Szenegraphen unter Verwendung des aktuellen Kontexts.
[signal] void QQuickRenderControl::renderRequested()
Dieses Signal wird ausgegeben, wenn der Szenegraph gerendert werden muss. Es ist nicht notwendig, sync() aufzurufen.
Hinweis: Vermeiden Sie es, das Rendering direkt auszulösen, wenn dieses Signal ausgegeben wird. Schieben Sie es stattdessen lieber auf, indem Sie beispielsweise einen Timer verwenden. Dies wird zu einer besseren Leistung führen.
[virtual] QWindow *QQuickRenderControl::renderWindow(QPoint *offset)
Wird in Unterklassen reimplementiert, um das tatsächliche Fenster zurückzugeben, in das dieses Rendering-Steuerelement gerendert wird.
Wenn offset nicht null ist, wird es auf den Offset des Steuerelements innerhalb des Fensters gesetzt.
Hinweis: Die Reimplementierung dieser Funktion ist zwar nicht zwingend erforderlich, aber für die Unterstützung mehrerer Bildschirme mit unterschiedlichen Pixelverhältnissen und die korrekte Positionierung von Popup-Fenstern, die mit QML geöffnet werden, unerlässlich. Es wird daher dringend empfohlen, sie in Unterklassen bereitzustellen.
[static] QWindow *QQuickRenderControl::renderWindowFor(QQuickWindow *win, QPoint *offset = nullptr)
Gibt das reale Fenster zurück, in dem win gerendert wird, falls vorhanden.
Wenn offset nicht leer ist, wird es auf den Offset des Renderings innerhalb seines Fensters gesetzt.
[since 6.6] QRhi *QQuickRenderControl::rhi() const
Gibt die QRhi zurück, mit der diese QQuickRenderControl verbunden ist.
Hinweis: Der QRhi existiert nur, wenn initialize() erfolgreich abgeschlossen wurde. Davor ist der Rückgabewert null.
Hinweis: Diese Funktion ist nicht anwendbar und gibt null zurück, wenn die software Anpassung von Qt Quick verwendet wird.
Diese Funktion wurde in Qt 6.6 eingeführt.
Siehe auch commandBuffer(), beginFrame(), und endFrame().
[since 6.0] int QQuickRenderControl::samples() const
Gibt die aktuelle Anzahl der Proben zurück. 1 oder 0 bedeutet kein Multisampling.
Diese Funktion wurde in Qt 6.0 eingeführt.
Siehe auch setSamples().
[signal] void QQuickRenderControl::sceneChanged()
Dieses Signal wird ausgegeben, wenn der Szenegraph aktualisiert wird, was bedeutet, dass polishItems() und sync() aufgerufen werden müssen. Wenn sync() true zurückgibt, muss render() aufgerufen werden.
Hinweis: Vermeiden Sie es, Polishing, Synchronisation und Rendering direkt auszulösen, wenn dieses Signal ausgegeben wird. Ziehen Sie es stattdessen vor, es aufzuschieben, indem Sie zum Beispiel einen Timer verwenden. Dies wird zu einer besseren Leistung führen.
[since 6.0] void QQuickRenderControl::setSamples(int sampleCount)
Legt die Anzahl der Samples fest, die für Multisampling verwendet werden. Wenn sampleCount 0 oder 1 ist, ist Multisampling deaktiviert.
Hinweis: Diese Funktion wird immer in Kombination mit einem Multisample-Rendertarget verwendet, was bedeutet, dass sampleCount mit der an QQuickRenderTarget::fromNativeTexture() übergebenen Sampleanzahl übereinstimmen muss, die wiederum mit der Sampleanzahl der nativen Textur übereinstimmen muss.
Diese Funktion wurde in Qt 6.0 eingeführt.
Siehe auch samples(), initialize(), und QQuickRenderTarget.
bool QQuickRenderControl::sync()
Diese Funktion wird verwendet, um die QML-Szene mit dem Rendering-Szenengraph zu synchronisieren.
Wenn ein dedizierter Render-Thread verwendet wird, sollte der GUI-Thread für die Dauer dieses Aufrufs blockiert werden.
Gibt true zurück, wenn die Synchronisation den Szenegraphen verändert hat.
[since 6.0] QQuickWindow *QQuickRenderControl::window() const
Gibt die QQuickWindow zurück, mit der diese QQuickRenderControl verknüpft ist.
Hinweis: Eine QQuickRenderControl wird mit einer QQuickWindow verknüpft, wenn die QQuickWindow erstellt wird. Der Rückgabewert dieser Funktion ist vor diesem Zeitpunkt null.
Diese Funktion wurde in Qt 6.0 eingeführt.
© 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.
