QQuickRhiItemRenderer Class

Dokumentation zu den Mitgliedsfunktionen

QQuickRhiItemRenderer::QQuickRhiItemRenderer()

Erstellt einen neuen Renderer.

Diese Funktion wird im Rendering-Thread während der Synchronisationsphase des Szenengraphen aufgerufen, wenn der GUI-Thread gesperrt ist.

Siehe auch ` QQuickRhiItem::createRenderer()`.

[virtual noexcept] QQuickRhiItemRenderer::~QQuickRhiItemRenderer()

Der Renderer wird automatisch gelöscht, wenn die Szenenbaum-Ressourcen für das Element „ QQuickRhiItem “ bereinigt werden.

Diese Funktion wird im Rendering-Thread aufgerufen.

Unter bestimmten Umständen ist es normal und zu erwarten, dass das Renderer-Objekt zerstört und anschließend neu erstellt wird. Dies liegt daran, dass die Lebensdauer des Renderers effektiv der des zugrunde liegenden Szenengraph-Knotens folgt. Wenn beispielsweise der übergeordnete Knoten eines „ QQuickRhiItem “-Objekts so geändert wird, dass es nun zu einem anderen „ QQuickWindow “ gehört, werden die Szenengraph-Knoten aufgrund der Fensteränderung alle entfernt und neu erstellt. Dies beinhaltet auch das Löschen und Erstellen eines neuen „ QQuickRhiItemRenderer “.

Im Gegensatz zu QRhiWidget muss QQuickRhiItemRenderer keine zusätzlichen Codepfade zum Freigeben (oder vorzeitigen Freigeben) von Grafikressourcen implementieren, die über QRhi erstellt wurden. Es reicht aus, alles im Destruktor freizugeben oder auf Smart-Pointer zurückzugreifen.

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

Gibt die Textur zurück, die als Farbpuffer für das Element dient.

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

Im Gegensatz zum Tiefen-Stencil-Puffer und dem ` QRhiRenderTarget` ist diese Textur immer verfügbar und wird vom ` QQuickRhiItem` verwaltet, unabhängig vom Wert von ` isAutoRenderTargetEnabled`.

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

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

Gibt den Tiefen-Stencil-Puffer zurück, der für die Darstellung des Elements verwendet wird.

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

Nur verfügbar, wenn isAutoRenderTargetEnabled gleich true ist. Andernfalls ist der Rückgabewert nullptr, und es obliegt der Neuimplementierung von initialize(), einen Depth-Stencil-Puffer 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 die „ QRhi “ oder die Textur aus irgendeinem Grund ändern. Von der Funktion wird erwartet, dass sie die vom Rendering-Code in „ render()“ verwendeten Grafikressourcen verwaltet (erstellt, falls noch nicht vorhanden, anpasst und neu erstellt, falls sich die Größe geändert hat).

Um den „ QRhi “, „ QRhiTexture “ und andere zugehörige Objekte abzufragen, rufen Sie „ rhi()“, „ colorTexture()“, „ depthStencilBuffer()“ und „ renderTarget()“ auf.

Wenn sich die Größe des Elements ändert, sind das ` QRhi `-Objekt, die Textur des Farbpuffers sowie die Objekte des Tiefen- und Stencil-Puffers zwar dieselben Instanzen wie zuvor (sodass die Getter dieselben Zeiger zurückgeben), doch wurden der Farbpuffer sowie der Tiefen- und Stencil-Puffer wahrscheinlich neu aufgebaut, was bedeutet, dass sich ` size ` und die zugrunde liegende native Texturressource möglicherweise von denen beim letzten Aufruf unterscheiden.

Bei Neuimplementierungen sollte ebenfalls berücksichtigt werden, dass sich das „ QRhi “-Objekt und die Farbpuffertextur zwischen den Aufrufen dieser Funktion ändern können. Wenn das Element beispielsweise einem neuen „ QQuickWindow “ zugeordnet wird, sind die „ QRhi “ und alle zugehörigen Ressourcen, die von „ QQuickRhiItem “ verwaltet werden, beim nachfolgenden Aufruf dieser Funktion andere Instanzen als zuvor. Es ist daher wichtig, dass alle vorhandenen „ QRhi “-Ressourcen, die zuvor von der Unterklasse erstellt wurden, zerstört werden, da sie zum vorherigen „ QRhi “ gehören, das nicht mehr verwendet werden sollte.

Wenn „ isAutoRenderTargetEnabled “ auf „ true “ gesetzt ist (was die Standardeinstellung ist), werden ein „depth-stencil QRhiRenderBuffer “ und ein „ QRhiTextureRenderTarget “, die mit dem „ colorTexture()“ (oder „ msaaColorBuffer()“) verknüpft sind, sowie der „depth-stencil-Buffer“ automatisch erstellt und verwaltet. Reimplementierungen von „initialize()“ und „ render()“ können diese Objekte über „ depthStencilBuffer()“ und „ renderTarget()“ abfragen. Wenn „ isAutoRenderTargetEnabled “ auf „ false “ gesetzt ist, werden diese Objekte nicht mehr automatisch erstellt und verwaltet. Stattdessen obliegt es der Implementierung von `initialize()`, die Puffer zu erstellen und das Renderziel nach eigenem Ermessen einzurichten. Bei der manuellen Verwaltung zusätzlicher Farb- oder Tiefen-Stencil-Anhänge für das Renderziel müssen deren Größe und die Anzahl der Samples stets der Größe und der Anzahl der Samples von ` colorTexture()` (bzw. ` msaaColorBuffer()`) entsprechen; andernfalls können Fehler beim Rendern oder bei der Validierung durch die 3D-API auftreten.

Es wird erwartet, dass die von der Unterklasse erstellten Grafikressourcen in der Destruktor-Implementierung der Unterklasse freigegeben werden.

cb ist der „ QRhiCommandBuffer “ für das aktuelle Bild. Die Funktion wird aufgerufen, während ein Bild aufgezeichnet wird, jedoch ohne aktiven Render-Durchlauf. Der Befehlspuffer dient in erster Linie dazu, „ resource updates “ in die Warteschlange einzureihen, ohne auf „ render()“ zurückzugreifen.

Diese Funktion wird im Render-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 Multisample-Antialiasing aktiviert ist, verfügt der zurückgegebene ` QRhiRenderBuffer ` über eine entsprechende Sample-Anzahl und dient als Farbpuffer. Grafik-Pipelines, die zum Rendern in diesen Puffer verwendet werden, müssen mit derselben Sample-Anzahl erstellt werden, und die Sample-Anzahl des Tiefen-Stencil-Puffers muss ebenfalls übereinstimmen. Es wird erwartet, dass der Multisample-Inhalt in die von ` resolveTexture()` zurückgegebene Textur aufgelöst wird. Wenn ` isAutoRenderTargetEnabled ` auf ` true` gesetzt ist, wird ` renderTarget()` automatisch entsprechend eingerichtet, indem `msaaColorBuffer()` als ` renderbuffer ` des Color-Attachments 0 und ` resolveTexture()` als dessen ` resolveTexture` festgelegt werden.

Wenn MSAA nicht verwendet wird, lautet der Rückgabewert „ nullptr “. Verwenden Sie in diesem Fall stattdessen „ colorTexture()“.

Je nach der zugrunde liegenden 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 ordnet möglicherweise beide einfach demselben nativen Ressourcentyp zu). Einige ältere APIs unterscheiden jedoch möglicherweise zwischen Texturen und Renderbuffern. Um OpenGL ES 3.0 zu unterstützen, wo Multisample-Renderbuffer verfügbar sind, Multisample-Texturen jedoch nicht, führt QQuickRhiItem MSAA immer durch, indem ein Multisample- QRhiRenderBuffer als Farb-Attachment 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 Hintergrundfarbpuffers aktualisiert werden muss.

Vor dem Aufruf dieser Funktion erfolgt immer mindestens ein Aufruf von ` initialize()`.

Um Aktualisierungen anzufordern, rufen Sie „ QQuickItem::update()“ auf, wenn Sie aus QML oder aus C++-Code im Haupt-/GUI-Thread aufrufen (z. B. in einem Eigenschaftssetter), oder „ update()“, wenn Sie aus einem „ QQuickRhiItemRenderer “-Callback heraus aufrufen. Der Aufruf von „ update()“ aus „ QQuickRhiItemRenderer “ innerhalb von „render()“ führt dazu, dass Aktualisierungen kontinuierlich ausgelöst werden.

cb ist der „ QRhiCommandBuffer “ für den aktuellen Frame. Die Funktion wird aufgerufen, während ein Frame aufgezeichnet wird, jedoch ohne aktiven Render-Durchlauf.

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

Siehe auch „ initialize()“ und „ synchronize()“.

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

Gibt das Render-Target-Objekt zurück, das bei Neaimplementierungen von ` render()` zusammen mit ` QRhiCommandBuffer::beginPass()` verwendet werden muss.

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

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

Beim Erstellen von „ graphics pipelines “ wird ein „ QRhiRenderPassDescriptor “ benötigt. Dieser kann über den 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.

Bei aktiviertem MSAA ist dies die Textur, die vom zugrunde liegenden Szenengraphenknoten des Elements verwendet wird, wenn im Hauptrenderdurchlauf von ` Qt Quick` ein Quad texturiert wird. Das Rendering von ` QQuickRhiItemRenderer` muss jedoch auf die (Multisample-)` QRhiRenderBuffer ` abzielen, die von ` msaaColorBuffer()` zurückgegeben wird. Wenn ` isAutoRenderTargetEnabled ` auf ` true` gesetzt ist, wird dies durch die von ` renderTarget()` zurückgegebene ` QRhiRenderTarget ` übernommen. Andernfalls ist es Aufgabe des Unterklassen-Codes, ein Render-Target-Objekt korrekt zu konfigurieren, das sowohl den Farbpuffer als auch die aufgelösten Texturen enthält.

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 im Render-Thread aufgerufen, sofern vorhanden, während der Haupt-/GUI-Thread gesperrt ist. Sie wird von the item's synchronize stepund ermöglicht das Lesen und Schreiben von Daten, die zum Haupt- und zum Render-Thread gehören. In der Regel werden die im ` QQuickRhiItem ` gespeicherten Eigenschaftswerte in das ` QQuickRhiItemRenderer` kopiert, damit sie anschließend sicher in ` render()` gelesen werden können, wenn der Render- und der Haupt-Thread weiterhin parallel arbeiten.

Siehe auch initialize() und render().

[protected] void QQuickRhiItemRenderer::update()

Rufen Sie diese Funktion auf, wenn der Inhalt des Offscreen-Farbpuffers aktualisiert werden soll. (D. h., um anzufordern, dass render() erneut aufgerufen wird; der Aufruf erfolgt zu einem späteren Zeitpunkt, wobei zu beachten ist, dass Aktualisierungen in der Regel auf die Darstellungsrate begrenzt sind.)

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