QQuickPaintedItem Class
La classe QQuickPaintedItem permet d'utiliser l'API QPainter dans le graphique de scène QML. Plus d'informations...
| En-tête : | #include <QQuickPaintedItem> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Quick)target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake : | QT += quick |
| Héritages : | 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
Le QQuickPaintedItem permet d'utiliser l'API QPainter avec le graphique de scène QML. Il met en place un rectangle texturé dans le graphique de scène et utilise une adresse QPainter pour peindre sur la texture. La cible de rendu dans Qt 6 est toujours QImage. Lorsque la cible de rendu est QImage, QPainter effectue d'abord le rendu dans l'image, puis le contenu est téléchargé dans la texture. Appelez update() pour déclencher un repeint.
Pour permettre à QPainter d'effectuer un rendu anticrénelé, utilisez setAntialiasing().
Pour écrire 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 implémente la peinture proprement dite. La peinture sera réalisée à l'intérieur du rectangle allant de 0,0 à width(),height().
Remarque : il est important de comprendre les implications en termes de performances que de tels éléments peuvent avoir. Voir QQuickPaintedItem::RenderTarget et QQuickPaintedItem::renderTarget.
Voir également Scene Graph - Painted Item et Writing QML Extensions with C++.
Documentation des types de membres
enum QQuickPaintedItem::PerformanceHint
flags QQuickPaintedItem::PerformanceHints
Cette énumération décrit les drapeaux que vous pouvez activer pour améliorer les performances de rendu dans QQuickPaintedItem. Par défaut, aucun de ces drapeaux n'est activé.
| Constante | Valeur | Description de la constante |
|---|---|---|
QQuickPaintedItem::FastFBOResizing | 0x1 | Depuis 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 peint avant que l'élément ne soit rendu à l'écran.
| Constante | Valeur | Description |
|---|---|---|
QQuickPaintedItem::Image | 0 | Valeur par défaut : QPainter peint sur QImage à l'aide du moteur de peinture matricielle. Le contenu de l'image doit ensuite être téléchargé dans la mémoire graphique. Cette opération peut être lente si l'élément est volumineux. Cette cible de rendu permet un anticrénelage de haute qualité et un redimensionnement rapide de l'élément. |
QQuickPaintedItem::FramebufferObject | 1 | À partir de Qt 6.9, cette valeur activera la peinture accélérée par le matériel tant que l'API de rendu utilisée est OpenGL, sinon elle sera ignorée. Pour les versions Qt 6.0 à Qt 6.8, elle sera ignorée pour toutes les API de rendu. 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 sur les propriétés
fillColor : QColor
Cette propriété contient 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 à une couleur non valide (par exemple QColor()) pour désactiver le remplissage de l'arrière-plan. Cela peut améliorer les performances et est sans danger si la fonction paint() dessine sur tous les pixels de chaque image.
Fonctions d'accès :
| QColor | fillColor() const |
| void | setFillColor(const QColor &) |
Signal du notificateur :
| 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 dans laquelle QPainter effectue le rendu. Il peut s'agir de QQuickPaintedItem::Image, QQuickPaintedItem::FramebufferObject ou QQuickPaintedItem::InvertedYFramebufferObject.
Chacune de ces cibles présente certains avantages, généralement en termes de performances et de qualité. L'utilisation d'un objet framebuffer évite le téléchargement coûteux du contenu de l'image vers la texture dans la mémoire graphique, tandis que l'utilisation d'une image permet un anticrénelage de haute qualité.
Attention : 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, de sorte que la peinture doit toujours se faire à l'intérieur de 0,0 sur width(),height().
Par défaut, la taille de la texture sera la même que celle de l'élément.
Remarque : si l'élément se trouve sur une fenêtre dont le ratio de pixels 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 Notifier :
| void | textureSizeChanged() |
Member Function Documentation
[explicit] QQuickPaintedItem::QQuickPaintedItem(QQuickItem *parent = nullptr)
Construit un QQuickPaintedItem avec l'élément parent donné.
[override virtual noexcept] QQuickPaintedItem::~QQuickPaintedItem()
Détruit le site QQuickPaintedItem.
bool QQuickPaintedItem::antialiasing() const
Retourne true si la peinture anticrénelée est activée ; sinon, false est retourné.
Par défaut, l'anticrénelage n'est pas activé.
Voir également 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
Retourne true si les mipmaps sont activés ; sinon, false est retourné.
Par défaut, le mipmapping n'est pas activé.
Voir aussi setMipmap().
bool QQuickPaintedItem::opaquePainting() const
Retourne true si cet élément est opaque ; sinon, false est retourné.
Par défaut, les éléments peints ne sont pas opaques.
Voir également setOpaquePainting().
[pure virtual] void QQuickPaintedItem::paint(QPainter *painter)
Cette fonction, qui est généralement appelée par le graphique de scène QML, peint le contenu d'un élément en coordonnées locales.
La texture sous-jacente aura une taille définie par textureSize lorsqu'elle est définie, ou par la taille de l'élément, multipliée par le ratio de pixels du périphérique de la fenêtre.
La fonction est appelée une fois que l'élément a été rempli avec l'image fillColor.
Réimplémentez cette fonction dans une sous-classe QQuickPaintedItem pour fournir l'implémentation de la peinture de l'élément, en utilisant painter.
Remarque : le graphique de scène QML utilise deux threads distincts, le thread principal s'occupant de tâches telles que le traitement des événements ou 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é par le thread principal de l'interface graphique, mais par le thread du moteur de rendu GL. Au moment où paint() est appelé, le thread de l'interface graphique est bloqué et ceci est donc à l'abri des threads.
Attention : Il convient d'être extrêmement prudent lors de la création de QObjects, de l'émission de signaux, du démarrage de temporisateurs et d'autres éléments similaires dans cette fonction, car ils auront une affinité avec le fil d'exécution du rendu.
Voir aussi width(), height(), et textureSize.
QQuickPaintedItem::PerformanceHints QQuickPaintedItem::performanceHints() const
Renvoie les indices de performance.
Par défaut, aucun indice de performance n'est activé.
Voir aussi setPerformanceHint() et setPerformanceHints().
[override virtual protected] void QQuickPaintedItem::releaseResources()
Réimplémente : QQuickItem::releaseResources().
void QQuickPaintedItem::setAntialiasing(bool enable)
Si enable est vrai, la peinture anticrénelée est activée.
Par défaut, l'anticrénelage n'est pas activé.
Voir également antialiasing().
void QQuickPaintedItem::setMipmap(bool enable)
Si enable est vrai, 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 mis à l'échelle.
Par défaut, le mipmapping n'est pas activé.
Voir également mipmap().
void QQuickPaintedItem::setOpaquePainting(bool opaque)
Si opaque est vrai, l'élément est opaque ; sinon, il est considéré comme translucide.
Les éléments opaques ne sont pas fusionnés avec le reste de la scène. Il est conseillé de fixer cette valeur à 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 la performance donnée hint sur l'élément si enabled est vrai ; sinon, efface l'indice de performance.
Par défaut, aucun indice de performance n'est activé/
Voir aussi setPerformanceHints() et performanceHints().
void QQuickPaintedItem::setPerformanceHints(QQuickPaintedItem::PerformanceHints hints)
Définit les indices de performance à hints
Par défaut, aucun indice de performance n'est activé/
Voir aussi setPerformanceHint() et performanceHints().
[override virtual] QSGTextureProvider *QQuickPaintedItem::textureProvider() const
Réimplémente : QQuickItem::textureProvider() const.
void QQuickPaintedItem::update(const QRect &rect = QRect())
Planifie un nouveau dessin de la zone couverte par rect dans cet élément. Vous pouvez appeler cette fonction chaque fois que votre élément doit être redessiné, par exemple s'il change d'apparence ou de taille.
Cette fonction n'entraîne pas une peinture immédiate, mais planifie une demande de peinture qui sera traitée par le graphique de scène QML lors du rendu de l'image suivante. L'élément ne sera redessiné 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.
