QQuickPaintedItem Class
La classe `QQuickPaintedItem` permet d'utiliser l'API « QPainter » dans le graphe de scène QML. En savoir plus...
| En-tête : | #include <QQuickPaintedItem> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Quick) target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake : | QT += quick |
| Hérite de : | QQuickItem |
Types publics
| enum | PerformanceHint { FastFBOResizing } |
| flags | PerformanceHints |
| enum | RenderTarget { Image, FramebufferObject, InvertedYFramebufferObject } |
Propriétés
- fillColor : QColor
- renderTarget : RenderTarget
- textureSize : QSize
Fonctions publiques
| 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()) |
Fonctions publiques réimplémentées
| virtual bool | isTextureProvider() const override |
| virtual QSGTextureProvider * | textureProvider() const override |
Signaux
| void | fillColorChanged() |
| void | renderTargetChanged() |
| void | textureSizeChanged() |
Fonctions protégées réimplémentées
| virtual void | itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value) override |
| virtual void | releaseResources() override |
| virtual QSGNode * | updatePaintNode(QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *data) override |
Description détaillée
La classe `QQuickPaintedItem` permet d'utiliser l'API « QPainter » avec le graphe de scène QML. Elle configure un rectangle texturé dans le graphe de scène et utilise un ` QPainter ` pour dessiner sur la texture. Dans Qt 6, la cible de rendu est toujours un ` QImage`. Lorsque la cible de rendu est un ` QImage`, ` QPainter ` effectue d'abord le rendu dans l'image, puis le contenu est transféré vers la texture. Appelez update() pour déclencher un rafraîchissement.
Pour permettre à QPainter d'effectuer un rendu anti-aliasing, utilisez setAntialiasing().
Pour créer votre propre élément peint, vous devez d’abord créer une sous-classe de `QQuickPaintedItem`, puis commencer par implémenter sa seule fonction publique virtuelle pure : ` paint()`, qui gère le dessin proprement dit. Le dessin s’effectuera à l’intérieur du rectangle s’étendant de 0,0 à ` width()`, `height()`.
Remarque : il est important de comprendre les implications en termes de performances que de tels éléments peuvent entraîner. Voir QQuickPaintedItem::RenderTarget et QQuickPaintedItem::renderTarget.
Voir également Graphique de scène - Élément peint et Écriture d’extensions QML avec C++.
Documentation sur les types de membres
enum QQuickPaintedItem::PerformanceHint
flags QQuickPaintedItem::PerformanceHints
Cette énumération décrit les options que vous pouvez activer pour améliorer les performances de rendu dans QQuickPaintedItem. Par défaut, aucune de ces options n'est activée.
| Constante | Valeur | Description |
|---|---|---|
QQuickPaintedItem::FastFBOResizing | 0x1 | À partir de Qt 6.0, cette valeur est ignorée. |
Le type `PerformanceHints` est un `typedef` pour ` QFlags<PerformanceHint>`. Il stocke une combinaison « OU » de valeurs `PerformanceHint`.
enum QQuickPaintedItem::RenderTarget
Cette énumération décrit les cibles de rendu de QQuickPaintedItem. La cible de rendu est la surface sur laquelle QPainter effectue le coloriage avant que l'élément ne soit affiché à l'écran.
| Constante | Valeur | Description |
|---|---|---|
QQuickPaintedItem::Image | 0 | Valeur par défaut ; QPainter dessine dans une « QImage » à l’aide du moteur de dessin raster. Le contenu de l’image doit ensuite être chargé en mémoire graphique ; cette opération peut s’avérer lente si l’élément est volumineux. Cette cible de rendu permet un lissage de haute qualité et un redimensionnement rapide des éléments. |
QQuickPaintedItem::FramebufferObject | 1 | À partir de Qt 6.9, cette valeur active le dessin accéléré par le matériel tant que l’API de rendu utilisée est OpenGL ; dans le cas contraire, elle est ignorée. Pour les versions Qt 6.0 à Qt 6.8, elle sera ignorée quelle que soit l’API de rendu utilisée. Cela permet généralement d’obtenir de meilleures performances de rendu, mais au détriment de la qualité de l’anticrénelage. |
QQuickPaintedItem::InvertedYFramebufferObject | 2 | Identique à FramebufferObject, mais avec un rendu inversé autour de l’axe X. |
Voir également ` setRenderTarget()`.
Documentation des propriétés
fillColor : QColor
Cette propriété définit la couleur de remplissage de l'arrière-plan de l'élément.
Par défaut, la couleur de remplissage est définie sur Qt::transparent.
Définissez la couleur de remplissage sur une couleur non valide (par exemple QColor()) pour désactiver le remplissage de l'arrière-plan. Cela peut améliorer les performances et ne présente aucun risque si la fonction paint() dessine sur tous les pixels à chaque image.
Fonctions d'accès :
| QColor | fillColor() const |
| void | setFillColor(const QColor &) |
Signal de notification :
| void | fillColorChanged() |
renderTarget : RenderTarget
Cette propriété contient la cible de rendu de l'élément.
Cette propriété définit la cible de rendu vers laquelle l'QPainter est rendu ; il peut s'agir de QQuickPaintedItem::Image, QQuickPaintedItem::FramebufferObject ou QQuickPaintedItem::InvertedYFramebufferObject.
Chacune présente certains avantages, généralement en termes de performances par rapport à la qualité. L’utilisation d’un objet framebuffer évite le chargement coûteux du contenu de l’image vers la texture en mémoire graphique, tandis que l’utilisation d’une image permet un anticrénelage de haute qualité.
Avertissement : le redimensionnement d’un objet framebuffer est une opération coûteuse ; évitez d’utiliser la cible de rendu QQuickPaintedItem::FramebufferObject si l’élément est souvent redimensionné.
Par défaut, la cible de rendu est QQuickPaintedItem::Image.
Fonctions d’accès :
| QQuickPaintedItem::RenderTarget | renderTarget() const |
| void | setRenderTarget(QQuickPaintedItem::RenderTarget target) |
Signal de notification :
| void | renderTargetChanged() |
textureSize : QSize
Définit la taille de la texture.
La modification de la taille de la texture n’affecte pas le système de coordonnées utilisé dans ` paint()`. Un facteur d’échelle est appliqué à la place ; le dessin doit donc toujours s’effectuer entre 0,0 et width(),height().
Par défaut, la taille de la texture sera identique à celle de cet élément.
Remarque : si l'élément se trouve dans une fenêtre dont le rapport de pixels du périphérique est différent de 1, ce facteur d'échelle sera implicitement appliqué à la taille de la texture.
Fonctions d’accès :
| QSize | textureSize() const |
| void | setTextureSize(const QSize &size) |
Signal de notification :
| void | textureSizeChanged() |
Documentation des fonctions membres
[explicit] QQuickPaintedItem::QQuickPaintedItem(QQuickItem *parent = nullptr)
Crée un objet `QQuickPaintedItem` à partir de l'élément ` parent ` spécifié.
[override virtual noexcept] QQuickPaintedItem::~QQuickPaintedItem()
Supprime l'QQuickPaintedItem.
bool QQuickPaintedItem::antialiasing() const
Renvoie « true » si le lissage est activé ; sinon, renvoie « false ».
Par défaut, l'anticrénelage n'est pas activé.
Voir aussi ` setAntialiasing()`.
[override virtual] bool QQuickPaintedItem::isTextureProvider() const
Réimplémente : QQuickItem::isTextureProvider() const.
[override virtual protected] void QQuickPaintedItem::itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value)
Réimplémente : QQuickItem::itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value).
bool QQuickPaintedItem::mipmap() const
Renvoie « true » si les mipmaps sont activées ; sinon, renvoie « false ».
Par défaut, le mipmapping n'est pas activé.
Voir également setMipmap().
bool QQuickPaintedItem::opaquePainting() const
Renvoie « true » si cet élément est opaque ; sinon, renvoie « false ».
Par défaut, les éléments peints ne sont pas opaques.
Voir également setOpaquePainting().
[pure virtual] void QQuickPaintedItem::paint(QPainter *painter)
Cette fonction, généralement appelée par le graphe de scène QML, dessine le contenu d'un élément dans un système de coordonnées local.
La texture sous-jacente aura une taille définie par la propriété « textureSize » si celle-ci est définie, ou par la taille de l’élément multipliée par le rapport de pixels de la fenêtre.
La fonction est appelée une fois que l’élément a été rempli avec la valeur de ` fillColor`.
Réimplémentez cette fonction dans une sous-classe de ` QQuickPaintedItem ` pour fournir l’implémentation de dessin de l’élément, en utilisant ` painter`.
Remarque : le graphe de scène QML utilise deux threads distincts : le thread principal se charge notamment du traitement des événements ou de la mise à jour des animations, tandis qu’un second thread se charge de l’émission effective des mises à jour des ressources graphiques et de l’enregistrement des appels de dessin. Par conséquent, paint() n’est pas appelée depuis le thread principal de l’interface graphique, mais depuis le thread du moteur de rendu compatible GL. Au moment où la fonction paint() est appelée, le thread de l'interface graphique est bloqué ; cette opération est donc sans risque d'interférence entre threads.
Avertissement : il convient de faire preuve d’uneextrême prudence lors de la création de QObjects, de l’émission de signaux, du démarrage de minuteries et d’opérations similaires au sein de cette fonction, car celles-ci auront une affinité avec le thread de rendu.
Voir également width(), height() et textureSize.
QQuickPaintedItem::PerformanceHints QQuickPaintedItem::performanceHints() const
Renvoie les conseils de performance.
Par défaut, aucune astuce de performance n'est activée.
Voir également setPerformanceHint() et setPerformanceHints().
[override virtual protected] void QQuickPaintedItem::releaseResources()
Réimplémente : QQuickItem::releaseResources().
void QQuickPaintedItem::setAntialiasing(bool enable)
Si la valeur de « enable » est « true », le lissage est activé.
Par défaut, l'anticrénelage n'est pas activé.
Voir aussi antialiasing().
void QQuickPaintedItem::setMipmap(bool enable)
Si la valeur « enable » est définie sur « true », le mipmapping est activé sur la texture associée.
Le mipmapping augmente la vitesse de rendu et réduit les artefacts d'aliasing lorsque l'élément est réduit.
Par défaut, le mipmapping n’est pas activé.
Voir aussi mipmap().
void QQuickPaintedItem::setOpaquePainting(bool opaque)
Si la propriété « opaque » est définie sur « true », l'élément est opaque ; dans le cas contraire, il est considéré comme translucide.
Les éléments opaques ne se fondent pas avec le reste de la scène ; vous devez définir cette propriété sur « true » si le contenu de l’élément est opaque afin d’accélérer le rendu.
Par défaut, les éléments peints ne sont pas opaques.
Voir également opaquePainting().
void QQuickPaintedItem::setPerformanceHint(QQuickPaintedItem::PerformanceHint hint, bool enabled = true)
Définit l'hint de performance indiquée sur l'élément si la valeur de « enabled » est « true » ; dans le cas contraire, supprime l' de performance.
Par défaut, aucune indication de performance n’est activée.
Voir également setPerformanceHints() et performanceHints().
void QQuickPaintedItem::setPerformanceHints(QQuickPaintedItem::PerformanceHints hints)
Définit les conseils de performances sur hints
Par défaut, aucune indication de performance n'est activée/
Voir également setPerformanceHint() et performanceHints().
[override virtual] QSGTextureProvider *QQuickPaintedItem::textureProvider() const
Réimplémente : QQuickItem::textureProvider() const.
void QQuickPaintedItem::update(const QRect &rect = QRect())
Planifie un rafraîchissement de la zone couverte par ` rect ` dans cet élément. Vous pouvez appeler cette fonction chaque fois que votre élément doit être rafraîchi, par exemple s’il change d’apparence ou de taille.
Cette fonction ne provoque pas de rafraîchissement immédiat ; elle planifie plutôt une demande de rafraîchissement qui sera traitée par le graphe de scène QML lors du rendu de l'image suivante. L'élément ne sera rafraîchi que s'il est visible.
Voir également ` paint()` ().
[override virtual protected] QSGNode *QQuickPaintedItem::updatePaintNode(QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *data)
Réimplémente : 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.
