Auf dieser Seite

QQuickPaintedItem Class

Die Klasse „QQuickPaintedItem“ bietet eine Möglichkeit, die API „ QPainter “ im QML-Szenenbaum zu nutzen. Mehr...

Überschrift: #include <QQuickPaintedItem>
CMake: find_package(Qt6 REQUIRED COMPONENTS Quick)
target_link_libraries(mytarget PRIVATE Qt6::Quick)
qmake: QT += quick
Erbt von: QQuickItem

Öffentliche Typen

enum PerformanceHint { FastFBOResizing }
flags PerformanceHints
enum RenderTarget { Image, FramebufferObject, InvertedYFramebufferObject }

Eigenschaften

Öffentliche Funktionen

QQuickPaintedItem(QQuickItem *parent = nullptr)
virtual ~QQuickPaintedItem() override
bool antialiasing() const
QColor fillColor() const
bool mipmap() const
bool opaquePainting() const
virtual void paint(QPainter *painter) = 0
QQuickPaintedItem::PerformanceHints performanceHints() const
QQuickPaintedItem::RenderTarget renderTarget() const
void setAntialiasing(bool enable)
void setFillColor(const QColor &)
void setMipmap(bool enable)
void setOpaquePainting(bool opaque)
void setPerformanceHint(QQuickPaintedItem::PerformanceHint hint, bool enabled = true)
void setPerformanceHints(QQuickPaintedItem::PerformanceHints hints)
void setRenderTarget(QQuickPaintedItem::RenderTarget target)
void setTextureSize(const QSize &size)
QSize textureSize() const
void update(const QRect &rect = QRect())

Neu implementierte öffentliche Funktionen

virtual bool isTextureProvider() const override
virtual QSGTextureProvider *textureProvider() const override

Signale

Neu implementierte geschützte Funktionen

virtual void itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value) override
virtual void releaseResources() override
virtual QSGNode *updatePaintNode(QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *data) override

Ausführliche Beschreibung

QPainter ermöglicht die Verwendung der -API mit dem QML-Szenengraphen. Es richtet ein texturiertes Rechteck im Szenengraphen ein und verwendet einen „ QPainter “, um auf die Textur zu zeichnen. Das Renderziel ist in Qt 6 immer ein „ QImage “. Wenn das Renderziel ein „ QImage “ ist, rendert „ QPainter “ zunächst in das Bild, anschließend wird der Inhalt in die Textur hochgeladen. Rufen Sie ` update()` auf, um eine Neuzeichnung auszulösen.

Um „ QPainter “ für das Anti-Aliasing-Rendering zu aktivieren, verwenden Sie „ setAntialiasing()“.

Um ein eigenes gezeichnetes Element zu erstellen, erstellen Sie zunächst eine Unterklasse von `QQuickPaintedItem` und beginnen dann mit der Implementierung ihrer einzigen rein virtuellen öffentlichen Funktion: ` paint()`, die das eigentliche Zeichnen implementiert. Das Zeichnen erfolgt innerhalb des Rechtecks, das sich von 0,0 bis ` width()` erstreckt, `height()`.

Hinweis: Es ist wichtig, die Auswirkungen auf die Leistung zu verstehen, die solche Elemente mit sich bringen können. Siehe QQuickPaintedItem::RenderTarget und QQuickPaintedItem::renderTarget.

Siehe auch Szenengraph – Gemaltes Element und Schreiben von QML-Erweiterungen mit C++.

Dokumentation zu Mitgliedstypen

enum QQuickPaintedItem::PerformanceHint
flags QQuickPaintedItem::PerformanceHints

Diese Enumeration beschreibt Flags, die Sie aktivieren können, um die Darstellungsleistung unter QQuickPaintedItem zu verbessern. Standardmäßig ist keines dieser Flags gesetzt.

KonstanteWertBeschreibung
QQuickPaintedItem::FastFBOResizing0x1Ab Qt 6.0 wird dieser Wert ignoriert.

Der Typ `PerformanceHints` ist ein `typedef` für ` QFlags<PerformanceHint>`. Er speichert eine OR-Kombination von `PerformanceHint`-Werten.

enum QQuickPaintedItem::RenderTarget

Diese Enumeration beschreibt die Renderziele von „ QQuickPaintedItem “. Das Renderziel ist die Oberfläche, auf die „ QPainter “ malt, bevor das Element auf dem Bildschirm dargestellt wird.

KonstanteWertBeschreibung
QQuickPaintedItem::Image0Der Standardwert; „ QPainter “ zeichnet mithilfe der Raster-Paint-Engine in ein „ QImage “. Der Bildinhalt muss anschließend in den Grafikspeicher geladen werden; dieser Vorgang kann bei großen Elementen unter Umständen langsam sein. Dieses Renderziel ermöglicht hochwertiges Anti-Aliasing und eine schnelle Größenanpassung der Elemente.
QQuickPaintedItem::FramebufferObject1Ab Qt 6.9 aktiviert dieser Wert hardwarebeschleunigtes Zeichnen, sofern die verwendete Rendering-API OpenGL ist; andernfalls wird er ignoriert. Bei den Versionen Qt 6.0 bis Qt 6.8 wird er bei allen Rendering-APIs ignoriert. Dies führt in der Regel zu einer besseren Rendering-Leistung, geht jedoch zu Lasten der Anti-Aliasing-Qualität.
QQuickPaintedItem::InvertedYFramebufferObject2Entspricht „FramebufferObject“, jedoch mit um die X-Achse gespiegeltem Rendering.

Siehe auch ` setRenderTarget()`.

Dokumentation zur Eigenschaft

fillColor : QColor

Diese Eigenschaft legt die Hintergrundfarbe des Elements fest.

Standardmäßig ist die Füllfarbe auf „ Qt::transparent “ gesetzt.

Legen Sie die Füllfarbe auf eine ungültige Farbe (z. B. `QColor()`) fest, um die Hintergrundfüllung zu deaktivieren. Dies kann die Leistung verbessern und ist unbedenklich, wenn die Funktion ` paint()` bei jedem Frame alle Pixel zeichnet.

Zugriffsfunktionen:

QColor fillColor() const
void setFillColor(const QColor &)

Notifier-Signal:

void fillColorChanged()

renderTarget : RenderTarget

Diese Eigenschaft enthält das Renderziel des Elements.

Diese Eigenschaft legt fest, in welches Renderziel das „ QPainter “ rendert; es kann sich entweder um „ QQuickPaintedItem::Image “, „ QQuickPaintedItem::FramebufferObject “ oder „ QQuickPaintedItem::InvertedYFramebufferObject “ handeln.

Jede Option bietet bestimmte Vorteile, in der Regel im Spannungsfeld zwischen Leistung und Qualität. Die Verwendung eines Framebuffer-Objekts vermeidet einen aufwendigen Upload der Bildinhalte in die Textur im Grafikspeicher, während die Verwendung eines Bildes ein hochwertiges Anti-Aliasing ermöglicht.

Warnung: Das Ändern der Größe eines Framebuffer-Objekts ist ein ressourcenintensiver Vorgang. Vermeiden Sie daher die Verwendung des Renderziels „ QQuickPaintedItem::FramebufferObject “, wenn die Größe des Elements häufig geändert wird.

Standardmäßig ist das Renderziel „ QQuickPaintedItem::Image “.

Zugriffsfunktionen:

QQuickPaintedItem::RenderTarget renderTarget() const
void setRenderTarget(QQuickPaintedItem::RenderTarget target)

Notifier-Signal:

void renderTargetChanged()

textureSize : QSize

Legt die Größe der Textur fest.

Das Ändern der Texturgröße hat keinen Einfluss auf das in „ paint()“ verwendete Koordinatensystem. Stattdessen wird ein Skalierungsfaktor angewendet, sodass das Zeichnen weiterhin innerhalb des Bereichs von 0,0 bis width() undheight() erfolgen sollte.

Standardmäßig entspricht die Texturgröße der Größe dieses Elements.

Hinweis: Befindet sich das Element in einem Fenster mit einem Gerätepixelverhältnis ungleich 1, wird dieser Skalierungsfaktor implizit auf die Texturgröße angewendet.

Zugriffsfunktionen:

QSize textureSize() const
void setTextureSize(const QSize &size)

Benachrichtigungssignal:

void textureSizeChanged()

Dokumentation der Mitgliedsfunktionen

[explicit] QQuickPaintedItem::QQuickPaintedItem(QQuickItem *parent = nullptr)

Erstellt ein `QQuickPaintedItem` mit dem angegebenen ` parent `-Element.

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

Zerstört die „ QQuickPaintedItem “.

bool QQuickPaintedItem::antialiasing() const

Gibt „true“ zurück, wenn das Zeichnen mit Kantenglättung aktiviert ist; andernfalls wird „false“ zurückgegeben.

Standardmäßig ist die Kantenglättung nicht aktiviert.

Siehe auch „ setAntialiasing()“.

[override virtual] bool QQuickPaintedItem::isTextureProvider() const

Implementiert: ` QQuickItem::isTextureProvider()` const.

[override virtual protected] void QQuickPaintedItem::itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value)

Implementiert: ` QQuickItem::itemChange` (`QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value`).

bool QQuickPaintedItem::mipmap() const

Gibt „true“ zurück, wenn Mipmaps aktiviert sind; andernfalls wird „false“ zurückgegeben.

Standardmäßig ist Mipmapping nicht aktiviert.

Siehe auch ` setMipmap()`.

bool QQuickPaintedItem::opaquePainting() const

Gibt „true“ zurück, wenn dieses Element undurchsichtig ist; andernfalls wird „false“ zurückgegeben.

Standardmäßig sind gezeichnete Elemente nicht undurchsichtig.

Siehe auch „ setOpaquePainting()“.

[pure virtual] void QQuickPaintedItem::paint(QPainter *painter)

Diese Funktion, die in der Regel vom QML-Szenengraphen aufgerufen wird, zeichnet den Inhalt eines Elements in lokalen Koordinaten.

Die zugrunde liegende Textur hat eine Größe, die durch ` textureSize ` definiert ist, sofern diese gesetzt ist, oder durch die Größe des Elements, multipliziert mit dem Gerätepixelverhältnis des Fensters.

Die Funktion wird aufgerufen, nachdem das Element mit dem Wert von ` fillColor` gefüllt wurde.

Implementieren Sie diese Funktion in einer Unterklasse von ` QQuickPaintedItem ` neu, um die Zeichenimplementierung des Elements bereitzustellen, und verwenden Sie dabei ` painter`.

Hinweis: Der QML-Szenengraph verwendet zwei separate Threads: Der Hauptthread übernimmt Aufgaben wie die Verarbeitung von Ereignissen oder die Aktualisierung von Animationen, während ein zweiter Thread die eigentliche Ausgabe von Aktualisierungen der Grafikressourcen und die Aufzeichnung von Zeichenaufrufen übernimmt. Folglich wird `paint()` nicht vom Haupt-GUI-Thread, sondern vom GL-fähigen Renderer-Thread aufgerufen. In dem Moment, in dem `paint()` aufgerufen wird, wird der GUI-Thread gesperrt, wodurch der Vorgang threadsicher ist.

Warnung: Bei der Erstellung von QObjects, dem Auslösen von Signalen, dem Starten von Timern und ähnlichen Vorgängen innerhalb dieser Funktion istäußerste Vorsicht geboten, da diese eine Affinität zum Rendering-Thread aufweisen.

Siehe auch width(), height() und textureSize.

QQuickPaintedItem::PerformanceHints QQuickPaintedItem::performanceHints() const

Gibt die Leistungshinweise zurück.

Standardmäßig ist kein Performance-Hinweis aktiviert.

Siehe auch setPerformanceHint() und setPerformanceHints().

[override virtual protected] void QQuickPaintedItem::releaseResources()

Implementiert: QQuickItem::releaseResources().

void QQuickPaintedItem::setAntialiasing(bool enable)

Wenn „ enable “ auf „true“ gesetzt ist, ist das Zeichnen mit Anti-Aliasing aktiviert.

Standardmäßig ist das Anti-Aliasing nicht aktiviert.

Siehe auch antialiasing().

void QQuickPaintedItem::setMipmap(bool enable)

Wenn „ enable “ auf „true“ gesetzt ist, ist Mipmapping für die zugehörige Textur aktiviert.

Mipmapping erhöht die Rendering-Geschwindigkeit und reduziert Aliasing-Artefakte, wenn das Element verkleinert wird.

Standardmäßig ist Mipmapping nicht aktiviert.

Siehe auch ` mipmap()`.

void QQuickPaintedItem::setOpaquePainting(bool opaque)

Wenn „ opaque “ auf „true“ gesetzt ist, ist das Element undurchsichtig; andernfalls wird es als durchscheinend betrachtet.

Undurchsichtige Objekte werden nicht mit dem Rest der Szene überblendet. Sie sollten diesen Wert auf „true“ setzen, wenn der Inhalt des Objekts undurchsichtig ist, um das Rendern zu beschleunigen.

Standardmäßig sind gezeichnete Elemente nicht undurchsichtig.

Siehe auch ` opaquePainting()`.

void QQuickPaintedItem::setPerformanceHint(QQuickPaintedItem::PerformanceHint hint, bool enabled = true)

Setzt den angegebenen Leistungs hint us für das Element, wenn „ enabled “ auf „true“ gesetzt ist; andernfalls wird der Leistungs us zurückgesetzt.

Standardmäßig ist kein Leistungshinweis aktiviert.

Siehe auch ` setPerformanceHints()` und ` performanceHints()`.

void QQuickPaintedItem::setPerformanceHints(QQuickPaintedItem::PerformanceHints hints)

Legt die Leistungshinweise wie folgt fest: hints

Standardmäßig ist kein Leistungshinweis aktiviert/

Siehe auch setPerformanceHint() und performanceHints().

[override virtual] QSGTextureProvider *QQuickPaintedItem::textureProvider() const

Implementiert: ` QQuickItem::textureProvider()` const.

void QQuickPaintedItem::update(const QRect &rect = QRect())

Plant eine Neuzeichnung des Bereichs, der von „ rect “ in diesem Element abgedeckt wird. Sie können diese Funktion immer dann aufrufen, wenn Ihr Element neu gezeichnet werden muss, beispielsweise wenn sich sein Aussehen oder seine Größe ändert.

Diese Funktion löst keine sofortige Neuzeichnung aus, sondern plant eine Neuzeichnungsanforderung ein, die vom QML-Szenengraphen beim Rendern des nächsten Frames verarbeitet wird. Das Element wird nur neu gezeichnet, wenn es sichtbar ist.

Siehe auch ` paint()`.

[override virtual protected] QSGNode *QQuickPaintedItem::updatePaintNode(QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *data)

Umsetzt: QQuickItem::updatePaintNode(QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *updatePaintNodeData).

© 2026 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.