QQuickRenderControl Class

Dokumentation der Member-Funktionen

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

Erstellt ein `QQuickRenderControl`-Objekt, dessen übergeordnetes Objekt ` parent` ist.

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

Löscht die Instanz. Gibt alle Ressourcen des Szenengraphen frei.

Siehe auch ` invalidate()`.

[since 6.0] void QQuickRenderControl::beginFrame()

Legt den Beginn eines Grafikframes fest. Aufrufe von „ sync()“ oder „ render()“ müssen zwischen Aufrufen von „beginFrame()“ und „ endFrame()“ stehen.

Im Gegensatz zur früheren, ausschließlich auf OpenGL basierenden Welt von Qt 5 erfordert das Rendern mit anderen Grafik-APIs klar definierte Start- und Endpunkte eines Frames. Bei manueller Steuerung der Render-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. Der Beispielcode geht von Direct3D 11 aus, doch 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(); // Die Rendering-Befehle von „ Qt Quick “ werden hier an den Gerätekontext übermittelt:

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. Dies ist der Befehlspuffer Qt Quick, den der Szenegraph verwendet, aber in einigen Fällen möchten Anwendungen diesen möglicherweise auch abfragen, beispielsweise um 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; so ist beispielsweise der Aufruf von lastCompletedGpuTime() für den Befehlspuffer unmittelbar nach endFrame(), jedoch vor dem nächsten beginFrame(), zulässig.

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 Grafikframes an. Aufrufe von ` sync()` oder ` render()` müssen von Aufrufen von ` beginFrame()` und `endFrame()` umschlossen sein.

Wenn diese Funktion aufgerufen wird, werden alle vom Szenengrafikbaum in die Warteschlange gestellten Grafikbefehle an den Kontext oder die Befehlswarteschlange übermittelt, je nachdem, was zutrifft.

Diese Funktion wurde in Qt 6.0 eingeführt.

Siehe auch beginFrame(), initialize(), sync(), render(), QQuickGraphicsDevice sowie QQuickRenderTarget.

[since 6.0] bool QQuickRenderControl::initialize()

Initialisiert die Ressourcen des Szenengraphen. Bei Verwendung einer Grafik-API wie Vulkan, Metal, OpenGL oder Direct3D für das „ Qt Quick “-Rendering richtet „ QQuickRenderControl “ beim Aufruf dieser Funktion eine entsprechende Rendering-Engine ein. Diese Rendering-Infrastruktur besteht so lange, wie der „ 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 erfolgen.

Um zu verhindern, dass der Szenengrafikbaum eigene Geräte- und Kontext-Objekte erstellt, geben Sie durch den Aufruf von ` QQuickWindow::setGraphicsDevice()` einen geeigneten ` QQuickGraphicsDevice` an, der vorhandene Grafikobjekte umschließt.

Um zu konfigurieren, welche Geräteerweiterungen aktiviert werden sollen (z. B. für Vulkan), rufen Sie vor dieser Funktion QQuickWindow::setGraphicsConfiguration() auf.

Gibt bei Erfolg „ true “ zurück, andernfalls „ false “.

Mit der Standardanpassung „ Qt Quick “ erstellt diese Funktion ein neues „ QRhi “-Objekt, ähnlich wie es bei einem Bildschirm-„ QQuickWindow “ der Fall wäre, wenn „ QQuickRenderControl “ nicht verwendet würde. Damit dieses neue „ QRhi “-Objekt eine bereits vorhandene Geräte- oder Kontextressource übernimmt (z. B. ein vorhandenes „ QOpenGLContext “ verwendet, anstatt ein neues zu erstellen), verwenden Sie wie oben erwähnt „ QQuickWindow::setGraphicsDevice()“. Wenn die Anwendung möchte, dass die Darstellung von ` Qt Quick ` ein bereits vorhandenes ` QRhi `-Objekt verwendet, ist dies ebenfalls über ` QQuickGraphicsDevice::fromRhi()` möglich. Wenn ein solches ` QQuickGraphicsDevice`, das auf ein bereits vorhandenes ` QRhi` verweist, festgelegt wird, wird in `initialize()` kein neues, dediziertes ` QRhi `-Objekt erstellt.

Diese Funktion wurde in Qt 6.0 eingeführt.

Siehe auch „ QQuickRenderTarget“ , „ QQuickGraphicsDevice “ und „ QQuickGraphicsConfiguration::preferredInstanceExtensions()“.

void QQuickRenderControl::invalidate()

Das Rendern beenden und Ressourcen freigeben.

Dies entspricht den Aufräumvorgängen, die bei einem echten „ QQuickWindow “ stattfinden, wenn das Fenster ausgeblendet wird.

Diese Funktion wird vom Destruktor aufgerufen. Daher ist es in der Regel nicht erforderlich, sie direkt aufzurufen.

Sobald `invalidate()` aufgerufen wurde, kann die ` QQuickRenderControl `-Instanz durch erneuten Aufruf von ` initialize()` wiederverwendet werden.

void QQuickRenderControl::polishItems()

Diese Funktion sollte so spät wie möglich vor dem Aufruf von ` sync()` aufgerufen werden. In einer Thread-Umgebung kann die Darstellung parallel zu dieser Funktion erfolgen.

void QQuickRenderControl::prepareThread(QThread *targetThread)

Bereitet die Darstellung der „ Qt Quick “-Szene außerhalb des GUI-Threads vor.

targetThread Legt den Thread fest, in dem die Synchronisation und das Rendering stattfinden sollen. In einem Single-Thread-Szenario muss diese Funktion nicht aufgerufen werden.

void QQuickRenderControl::render()

Rendert den Szenengrafen unter Verwendung des aktuellen Kontexts.

[signal] void QQuickRenderControl::renderRequested()

Dieses Signal wird ausgelöst, wenn der Szenenbaum gerendert werden muss. Es ist nicht erforderlich, die Funktion „ sync()“ aufzurufen.

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

Wird in Unterklassen neu implementiert, um das tatsächliche Fenster zurückzugeben, in das dieses Render-Steuerelement rendert.

Ist ` offset ` nicht null, wird es auf den Versatz des Steuerelements innerhalb des Fensters gesetzt.

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

Gibt das eigentliche Fenster zurück, in dem „ win “ gerendert wird, sofern vorhanden.

Ist „ offset “ nicht null, wird es auf den Offset der Darstellung innerhalb seines Fensters gesetzt.

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

Gibt die „ QRhi “ zurück, mit der diese „ QQuickRenderControl “ verknüpft ist.

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 Samples zurück. 1 oder 0 bedeutet, dass kein Multisampling erfolgt.

Diese Funktion wurde in Qt 6.0 eingeführt.

Siehe auch „ setSamples()“.

[signal] void QQuickRenderControl::sceneChanged()

Dieses Signal wird ausgelöst, wenn der Szenengraph aktualisiert wird, was bedeutet, dass „ polishItems()“ und „ sync()“ aufgerufen werden müssen. Wenn „ sync()“ den Wert „true“ zurückgibt, muss „ render()“ aufgerufen werden.

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

Legt die Anzahl der Samples fest, die für das Multisampling verwendet werden sollen. Wenn „ sampleCount “ den Wert 0 oder 1 hat, ist das Multisampling deaktiviert.

Diese Funktion wurde in Qt 6.0 eingeführt.

Siehe auch ` samples()`, ` initialize()` und ` QQuickRenderTarget`.

bool QQuickRenderControl::sync()

Diese Funktion dient dazu, die QML-Szene mit dem Rendering-Szenenbaum zu synchronisieren.

Wenn ein dedizierter Render-Thread verwendet wird, sollte der GUI-Thread für die Dauer dieses Aufrufs gesperrt werden.

Gibt „true“ zurück, wenn die Synchronisierung den Szenengraphen verändert hat.

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

Gibt den „ QQuickWindow “ zurück, mit dem dieser „ QQuickRenderControl “ verknüpft ist.

Diese Funktion wurde in Qt 6.0 eingeführt.