QSGRenderNode Class

Dokumentation zu den Mitgliedsfunktionen

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

Löscht den Render-Knoten. Von abgeleiteten Klassen wird erwartet, dass sie hier eine Bereinigung durchführen, die der Funktion ` releaseResources()` ähnelt.

Bei ` QRhi ` und Ressourcen wie ` QRhiBuffer`, ` QRhiTexture`, ` QRhiGraphicsPipeline` usw. empfiehlt es sich oft, Smart-Pointer wie `std::unique_ptr` zu verwenden, wodurch sich die Implementierung eines Destruktors häufig vermeiden lässt und der Quellcode kompakter wird. Beachten Sie jedoch, dass die Implementierung von ` releaseResources()` – die wahrscheinlich eine Reihe von `reset()`-Aufrufen für die `unique_ptrs` enthält – nach wie vor wichtig ist.

Siehe auch ` releaseResources()`.

[virtual] QSGRenderNode::StateFlags QSGRenderNode::changedStates() const

Diese Funktion sollte eine Maske zurückgeben, in der jedes Bit für Grafikzustände steht, die durch die Funktion ` render()` geändert wurden.

Die Standardimplementierung gibt 0 zurück, was bedeutet, dass in „ render()“ kein relevanter Zustand geändert wurde.

const QSGClipNode *QSGRenderNode::clipList() const

Gibt die aktuelle Clip-Liste zurück.

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

Gibt den aktuellen Befehlspuffer zurück.

Diese Funktion wurde in Qt 6.6 eingeführt.

Siehe auch „ renderTarget()“.

[virtual] QSGRenderNode::RenderingFlags QSGRenderNode::flags() const

Gibt Flags zurück, die das Verhalten dieses Render-Knotens beschreiben.

Die Standardimplementierung gibt 0 zurück.

Siehe auch „ RenderingFlag “ und „ rect()“.

qreal QSGRenderNode::inheritedOpacity() const

Gibt die aktuell wirksame Deckkraft zurück.

const QMatrix4x4 *QSGRenderNode::matrix() const

Gibt einen Zeiger auf die aktuelle Modell-Ansicht-Matrix zurück.

[virtual, since 6.0] void QSGRenderNode::prepare()

Wird in der Frame-Vorbereitungsphase aufgerufen. Vor jedem Aufruf von ` render()` wird diese Funktion aufgerufen.

Im Gegensatz zu ` render()` wird diese Funktion aufgerufen, bevor der Szenengrafik-Baum mit der Aufzeichnung des Render-Durchgangs für das aktuelle Bild im zugrunde liegenden Befehlspuffer beginnt. Dies ist nützlich beim Rendern mit Grafik-APIs wie Vulkan, bei denen Operationen vom Typ „Kopieren“ vor dem Render-Durchgang aufgezeichnet werden müssen.

Die Standardimplementierung ist leer.

Bei der Implementierung eines ` QSGRenderNode `, der zum Rendern ` QRhi ` verwendet, fragen Sie das ` QRhi `-Objekt über ` QQuickWindow::rhi()` aus dem ` QQuickWindow ` ab. Um einen ` QRhiCommandBuffer ` zum Übermitteln von Aufgaben zu erhalten, rufen Sie ` commandBuffer()` auf. Um Informationen zum aktiven Renderziel abzufragen, rufen Sie ` renderTarget()` auf. Weitere Informationen finden Sie im Beispiel {Scene Graph – Custom QSGRenderNode}.

Diese Funktion wurde in Qt 6.0 eingeführt.

[since 6.5] const QMatrix4x4 *QSGRenderNode::projectionMatrix() const

Gibt einen Zeiger auf die aktuelle Projektionsmatrix zurück.

In ` render()` ist dies dieselbe Matrix, die von ` RenderState::projectionMatrix()` zurückgegeben wird. Dieser Getter existiert, damit auch ` prepare()` die Möglichkeit hat, die Projektionsmatrix abzufragen.

Bei der Arbeit mit einer modernen Grafik-API oder der Qt-eigenen Grafik-Abstraktionsschicht ist es sehr wahrscheinlich, dass man „ *projectionMatrix() * *matrix() “ in einen Uniform-Buffer laden möchte. Dies muss jedoch in „ prepare()“ erfolgen, also außerhalb der Aufzeichnung eines Render-Passes. Aus diesem Grund können beide Matrizen direkt über ` QSGRenderNode` abgefragt werden, sowohl in ` prepare()` als auch in ` render()`.

Diese Funktion wurde in Qt 6.5 eingeführt.

[virtual] QRectF QSGRenderNode::rect() const

Gibt das umschließende Rechteck in Elementkoordinaten für den Bereich zurück, den render() berührt. Der Wert wird nur verwendet, wenn flags() BoundedRectRendering einschließt; andernfalls wird er ignoriert.

Die Angabe des Rechtecks in Kombination mit ` BoundedRectRendering ` ist besonders wichtig beim ` software `-Backend, da andernfalls ein Rendernode in der Szene Vollbild-Aktualisierungen auslösen würde, wodurch alle Optimierungen für Teilaktualisierungen umgangen würden.

Für Rendernodes, die den gesamten Bereich eines entsprechenden „ QQuickItem “ abdecken, lautet der Rückgabewert (0, 0, item->width(), item->height()).

Siehe auch ` flags()`.

[virtual] void QSGRenderNode::releaseResources()

Diese Funktion wird aufgerufen, wenn alle von diesem Knoten zugewiesenen benutzerdefinierten Grafikressourcen sofort freigegeben werden müssen. Falls der Knoten keine Grafikressourcen (Puffer, Texturen, Render-Ziele, Fences usw.) direkt über die verwendete Grafik-API zuweist, sind hier keine Maßnahmen erforderlich.

Werden nicht alle benutzerdefinierten Ressourcen freigegeben, kann dies auf einigen Systemen bei einem Ausfall des Grafikgeräts zu Fehlverhalten führen, da die anschließende Neuinitialisierung des Grafiksystems fehlschlagen kann.

Anders als beim Destruktor wird erwartet, dass ` render()` alle benötigten Ressourcen neu initialisieren kann, wenn es nach einem Aufruf von `releaseResources()` aufgerufen wird.

Bei OpenGL ist der OpenGL-Kontext des Szenengrafiksystems sowohl beim Aufruf des Destruktors als auch beim Aufruf dieser Funktion aktuell.

[pure virtual] void QSGRenderNode::render(const QSGRenderNode::RenderState *state)

Diese Funktion wird vom Renderer aufgerufen und sollte diesen Knoten zeichnen, indem sie Befehle direkt über ` QRhi ` oder direkt über die zugrunde liegende Grafik-API (OpenGL, Direct3D usw.) ausführt.

Die effektive Deckkraft kann mit inheritedOpacity() abgerufen werden.

Die Projektionsmatrix ist über ` state` verfügbar, während die Modell-Ansichts-Matrix mit ` matrix()` abgerufen werden kann. Die kombinierte Matrix ergibt sich dann aus der Multiplikation der Projektionsmatrix mit der Modell-Ansichts-Matrix. Die korrekte Überlagerung der Elemente in der Szene wird durch die Projektionsmatrix gewährleistet.

Bei Verwendung der bereitgestellten Matrizen folgt das Koordinatensystem für die Scheitelpunktdaten den üblichen Konventionen von QQuickItem: Oben links ist (0, 0), unten rechts sind die entsprechenden Werte von width() und height() aus QQuickItem minus eins. Angenommen, es gibt ein Koordinatenschema mit zwei Float-Werten (x-y) pro Scheitelpunkt, dann kann ein Dreieck, das die Hälfte des Objekts abdeckt, unter Verwendung der Gegenuhrzeigerrichtung als (Breite - 1, Höhe - 1), (0, 0), (0, Höhe - 1) angegeben werden.

Die Clip-Informationen werden vor dem Aufruf der Funktion berechnet. Implementierungen, die das Clipping berücksichtigen möchten, können auf der Grundlage der Informationen in ` state` Scissoring oder Stencil einrichten. Der Stencil-Puffer wird mit den erforderlichen Clip-Formen gefüllt, es liegt jedoch an der Implementierung, das Stencil-Testing zu aktivieren.

Einige Scenegraph-Backends, insbesondere Software-Backends, verwenden weder Scissoring noch Stencil. Dort wird der Clip-Bereich als gewöhnliches ` QRegion` bereitgestellt.

Bei der Implementierung eines ` QSGRenderNode `, der zum Rendern ` QRhi ` verwendet, fragen Sie das ` QRhi `-Objekt über ` QQuickWindow::rhi()` aus dem ` QQuickWindow ` ab. Um ein ` QRhiCommandBuffer ` für die Übermittlung von Arbeit zu erhalten, rufen Sie ` commandBuffer()` auf. Um Informationen über das aktive Renderziel abzufragen, rufen Sie ` renderTarget()` auf. Weitere Details finden Sie im Beispiel {Scene Graph - Custom QSGRenderNode}.

Bei Qt 6 und dem auf dem „ QRhi “ basierenden Szenengraph-Renderer sollten beim Aufruf dieser Funktion keine Annahmen über den aktiven (OpenGL-)Zustand getroffen werden, selbst wenn OpenGL verwendet wird. Gehen Sie beim Aufruf dieser Funktion von keinerlei Annahmen bezüglich der Pipelines und dynamischen Zustände aus, die an die Befehlsliste bzw. den Befehlspuffer gebunden sind.

Bei einigen Grafik-APIs, einschließlich der direkten Verwendung von ` QRhi `, kann es erforderlich sein, zusätzlich ` prepare()` neu zu implementieren oder alternativ eine Verbindung zum Signal ` QQuickWindow::beforeRendering()` herzustellen. Diese werden vor der Aufzeichnung des Beginns eines Renderpasses im Befehlspuffer aufgerufen bzw. ausgelöst (vkCmdBeginRenderPass bei Vulkan oder Beginn der Codierung über MTLRenderCommandEncoder im Fall von Metal). Das Aufzeichnen von Kopiervorgängen ist mit solchen APIs innerhalb von `render()` nicht möglich. Führen Sie solche Vorgänge stattdessen entweder in ` prepare()` oder in dem mit `beforeRendering` verbundenen Slot (mit `DirectConnection`) durch.

Siehe auch ` QSGRendererInterface ` und ` QQuickWindow::rendererInterface()`.

[since 6.6] QRhiRenderTarget *QSGRenderNode::renderTarget() const

Gibt das aktuelle Renderziel zurück.

Dies dient in erster Linie dazu, Implementierungen von „ prepare()“ und „ render()“ zu ermöglichen, die mithilfe von „ QRhi “ auf die „ renderPassDescriptor “ oder „ pixel size “ des „ QRhiRenderTarget “ zugreifen.

Um ein „ QRhiGraphicsPipeline “ zu erstellen, wofür die Angabe eines „ QRhiRenderPassDescriptor “ erforderlich ist, fragen Sie den „renderPassDescriptor“ vom Renderziel ab. Beachten Sie jedoch, dass sich das Renderziel während der Laufzeit des benutzerdefinierten „ QQuickItem “ und des „ QSGRenderNode “ ändern kann. Betrachten Sie beispielsweise, was passiert, wenn „ layer.enabled: true “ dynamisch für das Element oder einen seiner Vorfahren festgelegt wird: Dies löst das Rendern in eine Textur aus, nicht direkt in das Fenster, was bedeutet, dass der „ QSGRenderNode “ von diesem Zeitpunkt an mit einem anderen Renderziel arbeiten wird. Das neue Renderziel kann dann ein anderes Pixelformat haben, was bereits erstellte Grafik-Pipelines inkompatibel machen kann. Dies lässt sich mit einer Logik wie der folgenden handhaben:

if (m_pipeline && renderTarget()->renderPassDescriptor()->serializedFormat() != m_renderPassFormat) {
    delete m_pipeline;
    m_pipeline = nullptr;
}
if (!m_pipeline) {
    // Build a new QRhiGraphicsPipeline.
    // ...
    // Store the serialized format for fast and simple comparisons later on.
    m_renderPassFormat = renderTarget()->renderPassDescriptor()->serializedFormat();
}

Diese Funktion wurde in Qt 6.6 eingeführt.

Siehe auch ` commandBuffer()`.