From ae2ef9dbf060ba101e32bae2b5edfed979630e30 Mon Sep 17 00:00:00 2001 From: Paul Wicking Date: Thu, 10 Jun 2021 15:41:25 +0200 Subject: Doc: Improve QTransform documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Explain QTransform's model of vector/matrix operations. * Improve snippets used to illuminate QTransform's behavior. Fixes: QTBUG-83869 Pick-to: 6.2 6.1 5.15 Change-Id: I84c3b1a221c139ee992f82c3ee4aebadeef8ee63 Reviewed-by: Edward Welbourne Reviewed-by: Topi Reiniö Reviewed-by: Andy Nichols --- .../snippets/code/src_gui_painting_qtransform.cpp | 8 ++++---- src/gui/doc/snippets/transform/main.cpp | 14 ++++++-------- src/gui/painting/qtransform.cpp | 21 +++++++++++++++++++++ 3 files changed, 31 insertions(+), 12 deletions(-) (limited to 'src/gui') diff --git a/src/gui/doc/snippets/code/src_gui_painting_qtransform.cpp b/src/gui/doc/snippets/code/src_gui_painting_qtransform.cpp index 23d55febfe..97b9ee8af9 100644 --- a/src/gui/doc/snippets/code/src_gui_painting_qtransform.cpp +++ b/src/gui/doc/snippets/code/src_gui_painting_qtransform.cpp @@ -54,7 +54,7 @@ namespace src_gui_painting_qtransform { //! [0] x' = m11*x + m21*y + dx y' = m22*y + m12*x + dy -if (is not affine) { +if (!isAffine()) { w' = m13*x + m23*y + m33 x' /= w' y' /= w' @@ -65,7 +65,7 @@ if (is not affine) { //! [1] x' = m11*x + m21*y + dx y' = m22*y + m12*x + dy -if (is not affine) { +if (!isAffine()) { w' = m13*x + m23*y + m33 x' /= w' y' /= w' @@ -76,7 +76,7 @@ if (is not affine) { //! [2] x' = m11*x + m21*y + dx y' = m22*y + m12*x + dy -if (is not affine) { +if (!isAffine()) { w' = m13*x + m23*y + m33 x' /= w' y' /= w' @@ -87,7 +87,7 @@ if (is not affine) { //! [3] x' = m11*x + m21*y + dx y' = m22*y + m12*x + dy -if (is not affine) { +if (!isAffine()) { w' = m13*x + m23*y + m33 x' /= w' y' /= w' diff --git a/src/gui/doc/snippets/transform/main.cpp b/src/gui/doc/snippets/transform/main.cpp index f3b31b0f83..d15b059020 100644 --- a/src/gui/doc/snippets/transform/main.cpp +++ b/src/gui/doc/snippets/transform/main.cpp @@ -48,6 +48,7 @@ ** ****************************************************************************/ #include +#include #include #include #include @@ -105,18 +106,15 @@ class BasicOperations : public QWidget //! [2] void BasicOperations::paintEvent(QPaintEvent *) { - double pi = 3.14; - - double a = pi/180 * 45.0; + const double a = qDegreesToRadians(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 scale(0.5, 0, 0, 1.0, 0, 0); + QTransform rotate(cosa, sina, -sina, cosa, 0, 0); + QTransform translate(1, 0, 0, 1, 50.0, 50.0); - QTransform transform; - transform = scalingTransform * rotationTransform * translationTransform; + QTransform transform = scale * rotate * translate; QPainter painter(this); painter.setPen(QPen(Qt::blue, 1, Qt::DashLine)); diff --git a/src/gui/painting/qtransform.cpp b/src/gui/painting/qtransform.cpp index 8f2dc21a21..7d057732c7 100644 --- a/src/gui/painting/qtransform.cpp +++ b/src/gui/painting/qtransform.cpp @@ -213,6 +213,7 @@ static void nanWarning(const char *func) transformation is achieved by setting both the projection factors and the scaling factors. + \section2 Combining Transforms Here's the combined transformations example using basic matrix operations: @@ -223,6 +224,26 @@ static void nanWarning(const char *func) \snippet transform/main.cpp 2 \endtable + The combined transform first scales each operand, then rotates it, and + finally translates it, just as in the order in which the product of its + factors is written. This means the point to which the transforms are + applied is implicitly multiplied on the left with the transform + to its right. + + \section2 Relation to Matrix Notation + The matrix notation in QTransform is the transpose of a commonly-taught + convention which represents transforms and points as matrices and vectors. + That convention multiplies its matrix on the left and column vector to the + right. In other words, when several transforms are applied to a point, the + right-most matrix acts directly on the vector first. Then the next matrix + to the left acts on the result of the first operation - and so on. As a + result, that convention multiplies the matrices that make up a composite + transform in the reverse of the order in QTransform, as you can see in + \l {Combining Transforms}. Transposing the matrices, and combining them to + the right of a row vector that represents the point, lets the matrices of + transforms appear, in their product, in the order in which we think of the + transforms being applied to the point. + \sa QPainter, {Coordinate System}, {painting/affine}{Affine Transformations Example}, {Transformations Example} */ -- cgit v1.2.3