QQuickRhiItemRenderer Class

Dokumentation der Mitgliedsfunktionen

QQuickRhiItemRenderer::QQuickRhiItemRenderer()

Konstruiert einen neuen Renderer.

Diese Funktion wird im Rendering-Thread während der Sync-Phase des Szenengraphen aufgerufen, wenn der GUI-Thread blockiert ist.

Siehe auch QQuickRhiItem::createRenderer().

[virtual noexcept] QQuickRhiItemRenderer::~QQuickRhiItemRenderer()

Der Renderer wird automatisch gelöscht, wenn die Szenengraphenressourcen für das Element QQuickRhiItem bereinigt werden.

Diese Funktion wird im Rendering-Thread aufgerufen.

Unter bestimmten Bedingungen ist es normal und wird erwartet, dass das Renderer-Objekt zerstört und dann neu erstellt wird. Der Grund dafür ist, dass die Lebensdauer des Renderers dem zugrunde liegenden Szenegraph-Knoten folgt. Wenn z. B. das übergeordnete Objekt von QQuickRhiItem geändert wird, so dass es zu einem anderen QQuickWindow gehört, werden alle Knoten des Szenegraphen aufgrund der Fensteränderung gelöscht und neu erstellt. Dabei wird auch ein QQuickRhiItemRenderer gelöscht und neu erstellt.

Im Gegensatz zu QRhiWidget muss QQuickRhiItemRenderer keine zusätzlichen Codepfade für die Freigabe (oder vorzeitige Freigabe) von Grafikressourcen implementieren, die über QRhi erstellt wurden. Es reicht aus, alles im Destruktor freizugeben oder sich auf intelligente Zeiger zu verlassen.

[protected] QRhiTexture *QQuickRhiItemRenderer::colorTexture() const

Gibt die Textur zurück, die als Farbpuffer für den Gegenstand dient.

Darf nur von initialize() und render() aufgerufen werden.

Im Gegensatz zum Tiefenschablonenpuffer und QRhiRenderTarget ist diese Textur immer verfügbar und wird von QQuickRhiItem verwaltet, unabhängig vom Wert von isAutoRenderTargetEnabled.

Siehe auch msaaColorBuffer(), depthStencilBuffer(), renderTarget(), und resolveTexture().

[protected] QRhiRenderBuffer *QQuickRhiItemRenderer::depthStencilBuffer() const

Gibt den Tiefenschablonenpuffer zurück, der für das Rendering des Objekts verwendet wird.

Darf nur von initialize() und render() aufgerufen werden.

Nur verfügbar, wenn isAutoRenderTargetEnabled true ist. Andernfalls ist der Rückgabewert nullptr und es obliegt der Neuimplementierung von initialize(), einen Tiefenschablonenpuffer und ein QRhiTextureRenderTarget zu erstellen und zu verwalten.

Siehe auch colorTexture() und renderTarget().

[pure virtual protected] void QQuickRhiItemRenderer::initialize(QRhiCommandBuffer *cb)

Wird aufgerufen, wenn das Element zum ersten Mal initialisiert wird, wenn sich die Größe, das Format oder die Anzahl der Samples der zugehörigen Textur ändert, oder wenn sich QRhi oder die Textur aus irgendeinem Grund ändern. Von der Funktion wird erwartet, dass sie die vom Rendering-Code in render() verwendeten Grafikressourcen pflegt (erstellen, wenn noch nicht erstellt, anpassen und neu erstellen, wenn sich die Größe geändert hat).

Um QRhi, QRhiTexture und andere verwandte Objekte abzufragen, rufen Sie rhi(), colorTexture(), depthStencilBuffer() und renderTarget() auf.

Wenn sich die Elementgröße ändert, sind das Objekt QRhi, die Farbpuffertextur und die Tiefenschablonenpufferobjekte alle dieselben Instanzen (so dass die Getter dieselben Zeiger zurückgeben) wie zuvor, aber die Farb- und Tiefen-/Schablonenpuffer wurden wahrscheinlich neu erstellt, was bedeutet, dass die size und die zugrunde liegende native Texturressource anders sein können als beim letzten Aufruf.

Reimplementierungen sollten auch darauf vorbereitet sein, dass sich das Objekt QRhi und die Farbpuffertextur zwischen Aufrufen dieser Funktion ändern können. Wenn beispielsweise das Objekt repariert wird, so dass es zu einer neuen QQuickWindow gehört, werden die QRhi und alle zugehörigen Ressourcen, die von der QQuickRhiItem verwaltet werden, beim nächsten Aufruf dieser Funktion andere Instanzen sein als zuvor. Es ist dann wichtig, dass alle bestehenden QRhi Ressourcen, die zuvor von der Unterklasse erstellt wurden, zerstört werden, da sie zu der vorherigen QRhi gehören, die nicht mehr verwendet werden sollte.

Wenn isAutoRenderTargetEnabled true ist, was die Standardeinstellung ist, werden eine Tiefenschablone QRhiRenderBuffer und eine QRhiTextureRenderTarget, die mit dem colorTexture() (oder msaaColorBuffer()) und dem Tiefenschablonenpuffer verbunden sind, automatisch erstellt und verwaltet. Reimplementierungen von initialize() und render() können diese Objekte über depthStencilBuffer() und renderTarget() abfragen. Wenn isAutoRenderTargetEnabled auf false gesetzt wird, werden diese Objekte nicht mehr automatisch erstellt und verwaltet. Stattdessen obliegt es der initialize()-Implementierung, Puffer zu erstellen und das Rendering-Ziel nach eigenem Ermessen einzurichten. Wenn zusätzliche Farb- oder Tiefenschablonenanhänge für das Rendering-Ziel manuell verwaltet werden, müssen ihre Größe und Sampleanzahl immer der Größe und Sampleanzahl von colorTexture() (oder msaaColorBuffer()) entsprechen, da sonst Rendering- oder 3D-API-Validierungsfehler auftreten können.

Es wird erwartet, dass die von der Unterklasse erstellten Grafikressourcen in der Destruktorimplementierung der Unterklasse freigegeben werden.

cb ist die QRhiCommandBuffer für den aktuellen Frame. Die Funktion wird aufgerufen, wenn ein Frame aufgezeichnet wird, aber kein aktiver Rendering-Durchgang stattfindet. Der Befehlspuffer wird in erster Linie bereitgestellt, um das Einreihen von resource updates zu ermöglichen, ohne dass render() aufgeschoben wird.

Diese Funktion wird im Rendering-Thread aufgerufen, sofern ein solcher vorhanden ist.

Siehe auch render().

[protected] QRhiRenderBuffer *QQuickRhiItemRenderer::msaaColorBuffer() const

Gibt den Renderbuffer zurück, der als Multisample-Farbpuffer für das Element dient.

Darf nur von initialize() und render() aufgerufen werden.

Wenn sampleCount größer als 1 ist und somit die Multisample-Antialisierung aktiviert ist, hat der zurückgegebene QRhiRenderBuffer eine passende Sampleanzahl und dient als Farbpuffer. Grafikpipelines, die zum Rendern in diesen Puffer verwendet werden, müssen mit der gleichen Sampleanzahl erstellt werden, und die Sampleanzahl des Tiefenschablonenpuffers muss ebenfalls übereinstimmen. Es wird erwartet, dass der Multisample-Inhalt in die Textur aufgelöst wird, die von resolveTexture() zurückgegeben wird. Wenn isAutoRenderTargetEnabled true ist, wird renderTarget() automatisch für diese Aufgabe eingerichtet, indem msaaColorBuffer() als renderbuffer des Farbanhangs 0 und resolveTexture() als dessen resolveTexture eingerichtet werden.

Wenn MSAA nicht verwendet wird, ist der Rückgabewert nullptr. Verwenden Sie dann stattdessen colorTexture().

Abhängig von der zugrundeliegenden 3D-Grafik-API gibt es möglicherweise keinen praktischen Unterschied zwischen Multisample-Texturen und Farb-Renderbuffern mit einer Sample-Anzahl größer als 1 (QRhi kann einfach beide auf denselben nativen Ressourcentyp abbilden). Einige ältere APIs können jedoch zwischen Texturen und Renderbuffern unterscheiden. Um OpenGL ES 3.0 zu unterstützen, wo Multisample-Renderbuffer verfügbar sind, aber Multisample-Texturen nicht, führt QQuickRhiItem immer MSAA durch, indem ein Multisample QRhiRenderBuffer als Farbanhang verwendet wird (und niemals ein Multisample QRhiTexture).

Siehe auch colorTexture(), depthStencilBuffer(), renderTarget(), und resolveTexture().

[pure virtual protected] void QQuickRhiItemRenderer::render(QRhiCommandBuffer *cb)

Wird aufgerufen, wenn der Inhalt des Puffers für die Hintergrundfarbe aktualisiert werden muss.

Es gibt immer mindestens einen Aufruf von initialize(), bevor diese Funktion aufgerufen wird.

Um Aktualisierungen anzufordern, rufen Sie QQuickItem::update() auf, wenn der Aufruf von QML oder von C++-Code auf dem Haupt-/GUI-Thread erfolgt (z. B. in einem Eigenschaftssetzer), oder update(), wenn der Aufruf aus einem QQuickRhiItemRenderer -Callback erfolgt. Der Aufruf von QQuickRhiItemRenderer's update() innerhalb von render() führt dazu, dass kontinuierlich Aktualisierungen ausgelöst werden.

cb ist die QRhiCommandBuffer für den aktuellen Frame. Die Funktion wird aufgerufen, während ein Frame aufgezeichnet wird, aber ohne einen aktiven Rendering-Durchgang.

Diese Funktion wird auf dem Render-Thread aufgerufen, falls es einen gibt.

Siehe auch initialize() und synchronize().

[protected] QRhiRenderTarget *QQuickRhiItemRenderer::renderTarget() const

Gibt das Rendering-Zielobjekt zurück, das mit QRhiCommandBuffer::beginPass() in Reimplementierungen von render() verwendet werden muss.

Darf nur von initialize() und render() aufgerufen werden.

Nur verfügbar, wenn isAutoRenderTargetEnabled true ist. Andernfalls ist der zurückgegebene Wert nullptr und es obliegt der Neuimplementierung von initialize(), einen Tiefenschablonenpuffer und einen QRhiTextureRenderTarget zu erstellen und zu verwalten.

Beim Erstellen von graphics pipelines wird ein QRhiRenderPassDescriptor benötigt. Dieser kann aus dem zurückgegebenen QRhiTextureRenderTarget durch Aufruf von renderPassDescriptor() abgefragt werden.

Siehe auch colorTexture(), depthStencilBuffer(), und QQuickWindow::effectiveDevicePixelRatio().

[protected] QRhiTexture *QQuickRhiItemRenderer::resolveTexture() const

Gibt die Nicht-Multisample-Textur zurück, in die der Multisample-Inhalt aufgelöst wird.

Das Ergebnis ist nullptr, wenn Multisample-Antialiasing nicht aktiviert ist.

Darf nur von initialize() und render() aufgerufen werden.

Wenn MSAA aktiviert ist, ist dies die Textur, die vom zugrunde liegenden Szenengraphenknoten des Objekts verwendet wird, wenn ein Quad im Haupt-Rendering-Durchgang von Qt Quick texturiert wird. QQuickRhiItemRenderer muss jedoch für das Rendering die (Multisample-)Textur QRhiRenderBuffer verwenden, die von msaaColorBuffer() zurückgegeben wird. Wenn isAutoRenderTargetEnabled true ist, wird dies von dem von renderTarget() zurückgegebenen QRhiRenderTarget übernommen. Andernfalls obliegt es dem Code der Unterklasse, ein Rendering-Zielobjekt mit dem Farbpuffer und den aufgelösten Texturen korrekt zu konfigurieren.

Siehe auch colorTexture().

[protected] QRhi *QQuickRhiItemRenderer::rhi() const

Gibt das aktuelle QRhi Objekt zurück.

Darf nur von initialize() und render() aufgerufen werden.

[pure virtual protected] void QQuickRhiItemRenderer::synchronize(QQuickRhiItem *item)

Diese Funktion wird auf dem Render-Thread aufgerufen, falls es einen gibt, während der Haupt-/GUI-Thread blockiert ist. Sie wird aufgerufen von the item's synchronize stepaufgerufen und ermöglicht das Lesen und Schreiben von Daten, die zum Haupt- und Render-Thread gehören. Typischerweise werden die in QQuickRhiItem gespeicherten Eigenschaftswerte in QQuickRhiItemRenderer kopiert, so dass sie anschließend in render() sicher gelesen werden können, wenn der Render- und der Haupt-Thread parallel weiterarbeiten.

Siehe auch initialize() und render().

[protected] void QQuickRhiItemRenderer::update()

Rufen Sie diese Funktion auf, wenn der Inhalt des Farbpuffers im Offscreen-Bereich aktualisiert werden soll. (d.h. um anzufordern, dass render() erneut aufgerufen wird; der Aufruf erfolgt zu einem späteren Zeitpunkt, und beachten Sie, dass Aktualisierungen normalerweise auf die Präsentationsrate gedrosselt werden)

Diese Funktion kann von render() aus aufgerufen werden, um eine Aktualisierung zu planen.