QTransform

La classe QTransform décrit les transformations 2D d'un système de coordonnées. Plus d'informations...

#include <QTransform>

Voir la position dans l'arbre des classes.

Cette classe a été introduite dans Qt 4.3.

Description détaillée

La classe QTransform décrit les transformations 2D d'un système de coordonnées.

Une transformation décrit comment translater, redimensionner, tailler, tourner ou projeter le système de coordonnées et est souvent utilisée lors de rendu graphique.

QTransform est différent de QMatrix dans le fait que c'est une vraie matrice 3 × 3, permettant les transformations de perspectives. La méthode toAffine() de QTransform permet la conversion d'un QTransform en un QMatrix. Si la transformation de perspective a été spécifiée sur la matrice, alors la conversion va perdre des informations.

QTransform est la classe recommandée dans Qt pour les transformations.

Un objet QTransform peut être construit en utilisant les fonctions setMatrix(), scale(), rotate(), translate() et shear(). Alternativement, il peut être construit en appliquant une des opérations basiques sur les matrices. La matrice peut aussi être définie à la construction et peut être réinitialisée à la matrice d'identité (celle par défaut) en utilisant la fonction reset().

La classe QTransform supporte le déplacement des primitives graphiques : un point donné, une ligne, un polygone, une région ou un painter peuvent être déplacés au système de coordonnées défini par la matrice this avec la fonction map(). Dans le cas d'un rectangle, ses coordonnées peuvent être transformées en utilisant la fonction mapRect(). Un rectangle peut aussi être transformé en un polygone polygon (déplacé au système de coordonnées défini par la matrice this), en utilisant la fonction mapToPolygon().

QTransform fournit la fonction isIdentity() qui retourne true si la matrice est la matrice d'identité. La fonction isInvertible() retourne true si la matrice n'est pas singulière (c'est-à-dire: AB = BA = I). La fonction inverted() retourne une copie inversée de la matrice this si elle est inversible (sinon, elle retourne la matrice d'identité) et adjoint() retourne l'adjoint classique de la matrice. De plus, QTranform fournit la fonction determinant() qui retourne le déterminant de la matrice.

Finalement, la classe QTransform supporte la multiplication, l'addition et la soustraction de matrices et les objets de la classe peuvent être envoyés ou reçus sur un flux ainsi que comparés.

Rendu graphique

Lors d'un rendu graphique, la matrice définit les transformations mais la transformation est effectuée par les routines de dessin de QPainter.

Par défaut, QPainter opère sur le système de coordonnées du périphérique associé. Le système de coordonnées standard d'un QPaintDevice a son origine à la position supérieure gauche. Les valeurs x augmentent en allant vers la droite; les valeurs y, vers le bas. Pour une description complète, voyez la documentation du système de coordonnées.

QPainter a des fonctions pour translater, redimensionner, tailler et tourner le système de coordonnées sans utiliser un QTransform. Par exemple :

void SimpleTransformation::paintEvent(QPaintEvent *) { QPainter painter(this); painter.setPen(QPen(Qt::blue, 1, Qt::DashLine)); painter.drawRect(0, 0, 100, 100);   painter.rotate(45);   painter.setFont(QFont("Helvetica", 24)); painter.setPen(QPen(Qt::black, 1)); painter.drawText(20, 10, "QTransform"); }

Bien que ces fonctions soient très commodes, il peut être plus efficace de construire un QTransform et appeler QPainter::setTransform() si vous souhaitez effectuer plus d'une seule transformation. Par exemple :

void CombinedTransformation::paintEvent(QPaintEvent *) { QPainter painter(this); painter.setPen(QPen(Qt::blue, 1, Qt::DashLine)); painter.drawRect(0, 0, 100, 100);   QTransform transform; transform.translate(50, 50); transform.rotate(45); transform.scale(0.5, 1.0); painter.setTransform(transform);   painter.setFont(QFont("Helvetica", 24)); painter.setPen(QPen(Qt::black, 1)); painter.drawText(20, 10, "QTransform"); }

Opérations basiques sur les matrices

Un objet QTransform contient une matrice 3 × 3. Les éléments m31 (dx) et m32 (dy) désignent les translations horizontale et verticale. Les éléments m11 et m22 désignent les redimensionnements horizontal et vertical. Les éléments m21 et m12 désignent les taillages horizontal et vertical. Finalement, les éléments m13 et m23 désignent les projections horizontale et verticale, avec m33 comme facteur additionnel de projection.

QTransform transforme un point dans un plan vers un autre point en utilisant les formules suivantes :

 x' = m11*x + m21*y + dx
 y' = m22*y + m12*x + dy
 if (is not affine) {
     w' = m13*x + m23*y + m33
     x' /= w'
     y' /= w'
 }

Le point (x, y) est le point d'origine et (x›, y›) est le point transformé. (x›, y›) peut redevenir (x, y) en appliquant la même opération avec la matrice inverse.

Les différents éléments de la matrice peuvent être définis à la construction ou en utilisant la fonction setMatrix(). Ils peuvent aussi être modifiés en utilisant les fonctions de commodités translate(), rotate(), scale() et shear(). Les valeurs actuelles peuvent être récupérées avec les fonctions m11(), m12(), m13(), m21(), m22(), m23(), m31(), m32(), m33(), dx() et dy().

La translation est la plus simple des transformations. La définition de dx et dy va déplacer le système de coordonnées de dx unités suivant l'axe des X et de dy unités suivant l'axe des Y. Le redimensionnement peut être effectué en définissant m11 et m22. Par exemple, la définition de m11 à 2 et de m22 à 1.5 va doubler la hauteur et augmenter la largeur de 50 %. La matrice d'identité a m11, m22 et m33 définis à 1 (tous les autres éléments sont à 0) déplace un point sur lui-même. Le taillage est contrôlé par m12 et m21. Définir ces éléments à des valeurs différentes de zéro tortillera le système de coordonnées. La rotation peut être obtenue en définissant à la fois les facteurs de taille et les facteurs de redimensionnement. La transformation de perspective est obtenue en définissant à la fois les facteurs de projection et les facteurs de redimensionnement.

Voici un exemple de combinaison des transformations :

void BasicOperations::paintEvent(QPaintEvent *) { double pi = 3.14;   double a = pi/180 * 45.0; double sina = sin(a); double cosa = cos(a);   QTransform translationTransform(1, 0, 0, 1, 50.0, 50.0); QTransform rotationTransform(cosa, sina, -sina, cosa, 0, 0); QTransform scalingTransform(0.5, 0, 0, 1.0, 0, 0);   QTransform transform; transform = scalingTransform * rotationTransform * translationTransform;   QPainter painter(this); painter.setPen(QPen(Qt::blue, 1, Qt::DashLine)); painter.drawRect(0, 0, 100, 100);   painter.setTransform(transform);   painter.setFont(QFont("Helvetica", 24)); painter.setPen(QPen(Qt::black, 1)); painter.drawText(20, 10, "QTransform"); }

Voir aussi QPainter, Coordinate System, démo de transformations affines et exemple des transformations.

Type

enum QTransform::TransformationType

Fonctions membres

QTransform::QTransform ()

Construit une matrice d'identité.

Tous les éléments sont définis à zéro sauf m11 et m22 (définissant le redimensionnement) et m13 qui sont définis à 1.

Voir aussi reset().

QTransform::QTransform ( qreal m11, qreal m12, qreal m13, qreal m21, qreal m22, qreal m23, qreal m31, qreal m32, qreal m33 = 1.0 )

Construit une matrice avec les éléments m11, m12, m13, m21, m22, m23, m31, m32 et m33.

Voir aussi setMatrix().

QTransform::QTransform ( qreal m11, qreal m12, qreal m21, qreal m22, qreal dx, qreal dy )

Construit une matrice avec les éléments m11, m12, m21, m22, dx et dy.

Voir aussi setMatrix().

QTransform::QTransform ( const QMatrix & matrix )

Construit une matrice qui est une copie de la matrice matrix donnée. Notez que les éléments m13, m23 et m33 sont définis à 0, 0 et 1 respectivement.

qreal QTransform::m11 () const

Retourne le facteur de redimensionnement horizontal.

Voir aussi scale() et opérations basiques sur les matrices.

qreal QTransform::m12 () const

Retourne le facteur de taille verticale.

Voir aussi shear() et opérations basiques sur les matrices.

qreal QTransform::m13 () const

Retourne le facteur de projection horizontale.

Voir aussi translate() et opérations basiques sur les matrices.

qreal QTransform::m21 () const

Retourne le facteur de taille horizontale.

Voir aussi shear() et opérations basiques sur les matrices.

qreal QTransform::m22 () const

Retourne le facteur de redimensionnement vertical.

Voir aussi scale() et opérations basiques sur les matrices.

qreal QTransform::m23 () const

Retourne le facteur de projection verticale.

Voir aussi translate() et opérations basiques sur les matrices.

qreal QTransform::m31 () const

Retourne le facteur de translation horizontale.

Voir aussi dx(), translate() et opérations basiques sur les matrices.

qreal QTransform::m32 () const

Retourne le facteur de translation verticale.

Voir aussi dy(), translate() et opérations basiques sur les matrices.

qreal QTransform::m33 () const

Retourne le facteur de division.

Voir aussi translate() et opérations basiques sur les matrices.

QTransform QTransform::adjoint () const

Retourne l'adjoint de cette matrice.

qreal QTransform::determinant () const

Retourne le déterminant de cette matrice.

qreal QTransform::dx () const

Retourne le facteur de translation horizontale.

Voir aussi m31(), translate() et opérations basiques sur les matrices.

qreal QTransform::dy () const

Retourne le facteur de translation verticale.

Voir aussi translate() et opérations basiques sur les matrices.

QTransform QTransform::fromScale ( qreal sx, qreal sy ) [static]

Crée une matrice correspondante au redimensionnement horizontal sx et vertical sy. C'est la même chose que la fonction QTransform().scale(sx, sy) mais légèrement plus rapide.

Cette fonction a été introduite dans Qt 4.5.

QTransform QTransform::fromTranslate ( qreal dx, qreal dy ) [static]

Crée une matrice correspondant à la translation de dx suivant l'axe des X et dy suivant l'axe des Y. C'est la même chose que la fonction QTransform().translate(dx, dy) mais légèrement plus rapide.

Cette fonction a été introduite dans Qt 4.5.

QTransform QTransform::inverted ( bool * invertible = 0 ) const

Retourne une copie inversée de cette matrice.

Si la matrice est singulière (non inversible), la matrice retournée est la matrice d'identité. Si le paramètre invertible est valide (c'est-à-dire, non null), sa valeur est définie à true si la matrice est inversible, sinon il est défini à false.

Voir aussi isInvertible().

bool QTransform::isAffine () const

Retourne true si la matrice représente une transformation affine, sinon retourne false.

bool QTransform::isIdentity () const

Retourne true si la matrice est la matrice d'identité, sinon retourne false.

Voir aussi reset().

bool QTransform::isInvertible () const

Retourne true si la matrice est inversible, sinon retourne false.

Voir aussi inverted().

bool QTransform::isRotating () const

Retourne true si la matrice représente une rotation quelconque, sinon retourne false.

Voir aussi reset().

bool QTransform::isScaling () const

Retourne true si la matrice représente un redimensionnement quelconque, sinon retourne false.

Voir aussi reset().

bool QTransform::isTranslating () const

Retourne true si la matrice représente une translation quelconque, sinon retourne false.

Voir aussi reset().

void QTransform::map ( qreal x, qreal y, qreal * tx, qreal * ty ) const

Déplace les coordonnées x et y données dans le système de coordonnées défini par cette matrice. Le résultat est inséré dans *tx et *ty, respectivement.

Les coordonnées sont transformées en appliquant les formules suivantes :

 x' = m11*x + m21*y + dx
 y' = m22*y + m12*x + dy
 if (is not affine) {
     w' = m13*x + m23*y + m33
     x' /= w'
     y' /= w'
 }

Le point (x, y) est le point original et (x›, y›) le point transformé.

Voir aussi opérations basiques sur les matrices.

QPointF QTransform::map ( const QPointF & p ) const

Il s'agit d'une fonction surchargée.

Crée et retourne un objet QPointF qui est une copie du point p donné une fois déplacé dans le système de coordonnées défini par cette matrice.

QPoint QTransform::map ( const QPoint & point ) const

Il s'agit d'une fonction surchargée.

Crée et retourne un objet QPoint qui est une copie du point point donné une fois déplacé dans le système de coordonnées défini par cette matrice. Notez que les coordonnées transformées sont arrondies à l'entier le plus proche.

QLine QTransform::map ( const QLine & l ) const

Il s'agit d'une fonction surchargée.

Crée et retourne un objet QLineF qui est une copie de la ligne l donnée une fois déplacée dans le système de coordonnées défini par cette matrice.

QLineF QTransform::map ( const QLineF & line ) const

Il s'agit d'une fonction surchargée.

Crée et retourne un objet QLine qui est une copie de la ligne line donnée une fois déplacée dans le système de coordonnées défini par cette matrice. Notez que les coordonnées transformées sont arrondies à l'entier le plus proche.

QPolygonF QTransform::map ( const QPolygonF & polygon ) const

Il s'agit d'une fonction surchargée.

Crée et retourne un objet QPolygonF qui est une copie du polygone polygon donné une fois déplacé dans le système de coordonnées défini par cette matrice.

QPolygon QTransform::map ( const QPolygon & polygon ) const

Il s'agit d'une fonction surchargée.

Crée et retourne un objet QPolygon qui est une copie du polygone polygon donné une fois déplacé dans le système de coordonnées défini par cette matrice. Notez que les coordonnées transformées sont arrondies à l'entier le plus proche.

QRegion QTransform::map ( const QRegion & region ) const

Il s'agit d'une fonction surchargée.

Crée et retourne un objet QRegion qui est une copie de la région region donnée une fois déplacée dans le système de coordonnées défini par cette matrice.

L'appel de cette méthode peut être couteux si des rotations ou taillages sont utilisés.

QPainterPath QTransform::map ( const QPainterPath & path ) const

Il s'agit d'une fonction surchargée.

Crée et retourne un objet QPainterPath qui est une copie du chemin path donné une fois déplacé dans le système de coordonnées défini par cette matrice.

void QTransform::map ( int x, int y, int * tx, int * ty ) const

Il s'agit d'une fonction surchargée.

Déplace les coordonnées x et y données dans le système de coordonnées de cette matrice. Le résultat est inséré dans *tx et *ty, respectivement. Notez que les coordonnées transformées sont arrondies à l'entier le plus proche.

QRectF QTransform::mapRect ( const QRectF & rectangle ) const

Crée et retourne un objet QRectF qui est une copie du rectangle donné une fois déplacé dans le système de coordonnées défini par cette matrice.

Les coordonnées du rectangle sont transformées en utilisant les formules suivantes :

 x' = m11*x + m21*y + dx
 y' = m22*y + m12*x + dy
 if (is not affine) {
     w' = m13*x + m23*y + m33
     x' /= w'
     y' /= w'
 }

Si une rotation ou un taillage a été spécifié, cette fonction retourne le rectangle englobant. Pour récupérer la région exacte où le rectangle a été déplacé, utilisez la fonction mapToPolygon() à la place.

Voir aussi mapToPolygon() et opérations basiques sur les matrices.

QRect QTransform::mapRect ( const QRect & rectangle ) const

Il s'agit d'une fonction surchargée.

Crée et retourne un objet QRect qui est une copie du rectangle donné une fois déplacé dans le système de coordonnées défini par cette matrice. Notez que les coordonnées transformées sont arrondies à l'entier le plus proche.

QPolygon QTransform::mapToPolygon ( const QRect & rectangle ) const

Crée et retourne une représentation QPolygon du rectangle donné une fois déplacé dans le système de coordonnées défini par cette matrice.

Les coordonnées du rectangle sont transformées en utilisant les formules suivantes :

 x' = m11*x + m21*y + dx
 y' = m22*y + m12*x + dy
 if (is not affine) {
     w' = m13*x + m23*y + m33
     x' /= w'
     y' /= w'
 }

Les polygones et les rectangles se comportent légèrement différemment lors d'une transformation (à cause de l'arrondi à l'entier), donc matrix.map(QPolygon(rectangle)) n'est pas toujours identique à matrix.mapToPolygon(rectangle).

Voir aussi mapRect() et opérations basiques sur les matrices.

bool QTransform::quadToQuad ( const QPolygonF & one, const QPolygonF & two, QTransform & trans ) [static]

Crée une matrice de transformation, trans, qui déplace un polygone à quatre côtés, one, à un autre polygone à quatre côtés, two. Retourne true si la transformation est possible ; sinon retourne false.

Ceci est une fonction de commodité combinant les fonctions quadToSquare() et squareToQuad(). Elle permet à un quad d'entrée d'être transformé en un autre quad.

Voir aussi squareToQuad() et quadToSquare().

bool QTransform::quadToSquare ( const QPolygonF & quad, QTransform & trans ) [static]

Crée une matrice de transformation, trans, qui déplace un polygone à quatre côtés, one, à un carré unitaire. Retourne true si la transformation est construite ou false si elle n'existe pas.

Voir aussi squareToQuad() et quadToQuad().

void QTransform::reset ()

Réinitialise la matrice à une matrice d'identité, c'est-à-dire, tous les éléments sont définis à zéro, sauf m11 et m22 (définissant le redimensionnement) et m33 qui sont définis à 1.

Voir aussi QTransform(), isIdentity() et opérations basiques sur les matrices.

QTransform & QTransform::rotate ( qreal angle, Qt::Axis axis = Qt::ZAxis )

Tourne le système de coordonnées dans le sens inverse des aiguilles d'une montre de l‹angle donné autour des axes axis spécifiés et retourne une référence de la matrice.

Notez que si vous appliquez un QTransform à un point défini dans les coordonnées d'un widget, la direction de la rotation va être dans le sens des aiguilles d'une montre car l'axe des Y pointe vers le bas.

L'angle est spécifié en degrés.

Voir aussi setMatrix().

QTransform & QTransform::rotateRadians ( qreal angle, Qt::Axis axis = Qt::ZAxis )

Tourne le système de coordonnées dans le sens inverse des aiguilles d'une montre de l‹angle donné autour des axes axis spécifiés et retourne une référence de la matrice.

Notez que si vous appliquez un QTransform à un point défini dans les coordonnées d'un widget, la direction de la rotation va être dans le sens des aiguilles d'une montre car l'axe des Y pointe vers le bas.

L'angle est spécifié en radians.

Voir aussi setMatrix().

QTransform & QTransform::scale ( qreal sx, qreal sy )

Redimensionne le système de coordonnées horizontalement de sx et verticalement de sy et retourne une référence de la matrice.

Voir aussi setMatrix().

void QTransform::setMatrix ( qreal m11, qreal m12, qreal m13, qreal m21, qreal m22, qreal m23, qreal m31, qreal m32, qreal m33 )

Définit les éléments de la matrice aux valeurs spécifiées, m11, m12, m13 m21, m22, m23 m31, m32 et m33. Notez que cette fonction remplace les valeurs précédentes. QTransform fournit les fonctions de commodités translate(), rotate(), scale() et shear() pour manipuler les éléments de la matrice basés sur le système de coordonnées actuel.

Voir aussi QTransform().

QTransform & QTransform::shear ( qreal sh, qreal sv )

Taille le système de coordonnées horizontalement de sh et verticalement de sv et retourne une référence de la matrice.

Voir aussi setMatrix().

bool QTransform::squareToQuad ( const QPolygonF & quad, QTransform & trans ) [static]

Crée une matrice de transformation, trans, qui déplace un carré unitaire vers un polygone à quatre côtés, quad. Retourne true si la transformation est construite ou false si la transformation n'existe pas.

Voir aussi quadToSquare() et quadToQuad().

const QMatrix & QTransform::toAffine () const

Retourne le QTransform comme une matrice affine.

Attention : si une transformation de perspective a été définie, alors la conversion provoquera une perte de données.

QTransform & QTransform::translate ( qreal dx, qreal dy )

Déplace le système de coordonnées de dx suivant l'axe des X et de dy suivant l'axe des Y et retourne une référence de la matrice.

Voir aussi setMatrix().

QTransform QTransform::transposed () const

Retourne la transposée de cette matrice.

TransformationType QTransform::type () const

Retourne le type de transformation de cette matrice.

Le type de transformation est la plus haute valeur de l'enum capturant toutes les transformations de la matrice. Par exemple, si la matrice redimensionne et taille, le type sera TxShear, car TxShear a une plus haute valeur que TxScale.

Connaître le type de transformation de la matrice est utile pour optimiser : vous pouvez souvent gérer des types spécifiques plus rapidement que de gérer les cas généraux.

QTransform::operator QVariant () const

Retourne la transformation comme un QVariant.

bool QTransform::operator!= ( const QTransform & matrix ) const

Retourne true si cette matrice n'est pas égale à la matrice matrix donnée, sinon retourne false.

QTransform QTransform::operator* ( const QTransform & matrix ) const

Retourne le résultat de la multiplication de cette matrice avec la matrice matrix donnée.

Notez que la multiplication de matrice n'est pas commutative, c'est-à-dire a*b != b*a.

QTransform & QTransform::operator*= ( const QTransform & matrix )

Il s'agit d'une fonction surchargée.

Retourne le résultat de la multiplication de cette matrice avec la matrice matrix donnée.

QTransform & QTransform::operator*= ( qreal scalar )

Il s'agit d'une fonction surchargée.

Retourne le résultat de la multiplication d'un facteur scalar donné avec les éléments de la matrice.

QTransform & QTransform::operator+= ( qreal scalar )

Il s'agit d'une fonction surchargée.

Retourne la matrice obtenue en ajoutant le facteur scalar donné à chaque élément de cette matrice.

QTransform & QTransform::operator-= ( qreal scalar )

Il s'agit d'une fonction surchargée.

Retourne la matrice obtenue en soustrayant le facteur scalar donné à chaque élément de cette matrice.

QTransform & QTransform::operator/= ( qreal scalar )

Il s'agit d'une fonction surchargée.

Retourne le résultat de la division d'un facteur scalar donné avec les éléments de la matrice.

QTransform & QTransform::operator= ( const QTransform & matrix )

Assigne la matrice matrix donnée à cette matrice.

bool QTransform::operator== ( const QTransform & matrix ) const

Retourne true si cette matrice est égale à la matrice matrix donnée, sinon retourne false.

En relation mais non membres de la classe

bool qFuzzyCompare ( const QTransform & t1, const QTransform & t2 )

Retourne true si t1 et t2 sont égaux. La comparaison utilise un petit facteur flou dans la comparaison des nombres à virgule flottante ; La fonction retourne false si elles sont différentes.

Cette fonction a été introduite dans Qt 4.6.

QPoint operator* ( const QPoint & point, const QTransform & matrix )

Identique à matrix.map(point).

Voir aussi QTransform::map().

QPointF operator* ( const QPointF & point, const QTransform & matrix )

Identique à matrix.map(point).

Voir aussi QTransform::map().

QLineF operator* ( const QLineF & line, const QTransform & matrix )

Identique à matrix.map(line).

Voir aussi QTransform::map().

QLine operator* ( const QLine & line, const QTransform & matrix )

Identique à matrix.map(line).

Voir aussi QTransform::map().

QPolygon operator* ( const QPolygon & polygon, const QTransform & matrix )

Identique à matrix.map(polygon).

Voir aussi QTransform::map().

QPolygonF operator* ( const QPolygonF & polygon, const QTransform & matrix )

Identique à matrix.map(polygon).

Cette fonction a été introduite dans Qt 4.3.

Voir aussi QTransform::map().

QRegion operator* ( const QRegion & region, const QTransform & matrix )

Identique à matrix.map(region).

Voir aussi QTransform::map().

QPainterPath operator* ( const QPainterPath & path, const QTransform & matrix )

Identique à matrix.map(path).

Cette fonction a été introduite dans Qt 4.3.

Voir aussi QTransform::map().

QDataStream & operator<< ( QDataStream & stream, const QTransform & matrix )

Écrit la matrice matrix donnée sur le flux stream et retourne une référence sur le fux.

Cette fonction a été introduite dans Qt 4.3.

Voir aussi sérialisation des types de données Qt.

QDataStream & operator>> ( QDataStream & stream, QTransform & matrix )

Lit la matrice matrix à partir du flux stream et retourne une référence sur le flux.

Cette fonction a été introduite dans Qt 4.3.

Voir aussi sérialisation des types de données Qt.

Remerciements

Merci à Alexandre Laurent pour la traduction ainsi qu'à Emmanuel Di Clemente, Jonathan Courtois et Claude Leloup pour leur relecture !