QWMatrix - 2D transformations of a coordinate system

       #include <qwmatrix.h>

   Public Members
       QWMatrix ()
       QWMatrix ( double m11, double m12, double m21, double m22,
           double dx, double dy )
       void setMatrix ( double m11, double m12, double m21,
           double m22, double dx, double dy )
       double m11 () const
       double m12 () const
       double m21 () const
       double m22 () const
       double dx () const
       double dy () const
       void map ( int x, int y, int * tx, int * ty ) const
       void map ( double x, double y, double * tx, double * ty )
           const
       QPoint map ( const QPoint & ) const
       QRect map ( const QRect & ) const
       QPointArray map ( const QPointArray & ) const
       void reset ()
       QWMatrix& translate ( double dx, double dy )
       QWMatrix& scale ( double sx, double sy )
       QWMatrix& shear ( double sh, double sv )
       QWMatrix& rotate ( double a )
       QWMatrix invert ( bool * = 0 ) const
       bool operator== ( const QWMatrix & ) const
       bool operator!= ( const QWMatrix & ) const
       QWMatrix& operator*= ( const QWMatrix & )


RELATED FUNCTION DOCUMENTATION

       (Note that these are not member functions.)
       QWMatrix operator* (const QWMatrix & m1, const QWMatrix &
           m2)
       QDataStream & operator<< (QDataStream & s, const QWMatrix
           & m)
       QDataStream & operator>> (QDataStream & s, QWMatrix & m)


DESCRIPTION

       The QWMatrix class specifies 2D transformations of a
       coordinate system.

       The standard coordinate system of a paint device has the
       origin located at the top left position. X values increase
       to the right, and Y values increase downwards.

       This coordinate system is default for the QPainter, which
       renders graphics in a paint device. A user-defined
       coordinate system can be specified by setting a QWMatrix
       for the painter.


           MyWidget::paintEvent( QPaintEvent * )
           {
             QPainter p;                       // our painter
             QWMatrix m;                       // our transformation matrix
             m.rotate( 22.5 );                 // rotated coordinate system
             p.begin( this );                  // start painting
             p.setWorldMatrix( m );            // use rotated coordinate system
             p.drawText( 30,20, "detator" );   // draw rotated text at 30,20
             p.end();                          // painting done
           }

       A matrix specifies how to translate, scale, shear or
       rotate the graphics, and the actual transformation is
       performed by the drawing routines in QPainter and by
       QPixmap::xForm().

       The QWMatrix class contains a 3*3 matrix of the form:

           m11  m12  0
           m21  m22  0
           dx   dy   1

       A matrix transforms a point in the plane to another point:

           x' = m11*x + m21*y + dx
           y' = m22*y + m12*x + dy

       The point (x,y) is the original point, and (x',y') is the
       transformed point. (x',y') can be transformed back to
       (x,y) by performing the same operation on the inverted
       matrix.

       The elements dx and dy specify horisontal and vertical
       translation. The elements m11 and m22 specify horisontal
       and vertical scaling. The elements m12 and m21 specify
       horisontal and vertical shearing.

       The identity matrix has m11 and m22 set to 1, all others
       set to 0. This matrix maps a point to itself.

       Translation is the simplest transformation. Setting dx and
       dy will move the coordinate system dx units along the X
       axis and dy units along the Y axis.

       Scaling can be done by setting m11 and m22. For example,
       setting m11 to 2 and m22 to 1.5 will double the height and
       increase the width by 50%.

       Shearing is controlled by m12 and m21. Setting these
       elements to values different from zero will twist the
       coordinate system.

       shearing factors and the scaling factors. The QWMatrix has
       a function that sets rotation directly.

       QWMatrix lets you combine transformations like this:

           QWMatrix m;                                 // identity matrix
           m.translate(10, -20);                       // first translate (10,-20)
           m.rotate(25);                               // then rotate 25 degrees
           m.scale(1.2, 0.7);                          // finally scale it

       The same example, but using basic matrix operations:

           double a    = pi/180 * 25;                  // convert 25 to radians
           double sina = sin(a);
           double cosa = cos(a);
           QWMatrix m1(0, 0, 0, 0, 10, -20);           // translation matrix
           QWMatrix m2( cosa, sina,                    // rotation matrix
                       -sina, cosa, 0, 0 );
           QWMatrix m3(1.2, 0, 0, 0.7, 0, 0);          // scaling matrix
           QWMatrix m;
           m = m3 * m2 * m1;                           // combine all transformations

       QPainter has functions that translate, scale, shear and
       rotate the coordinate system without using a QWMatrix.
       These functions are very convenient, however, if you want
       to perform more than a single transform operation, it is
       more efficient to build a QWMatrix and call
       QPainter::setWorldMatrix().

       See also QPainter::setWorldMatrix() and QPixmap::xForm().

       Examples: qtimage/qtimage.cpp xform/xform.cpp
       drawdemo/drawdemo.cpp qmag/qmag.cpp desktop/desktop.cpp
       movies/main.cpp


MEMBER FUNCTION DOCUMENTATION


QWMatrix::QWMatrix ()

       Constructs an identity matrix. All elements are set to
       zero, except m11 and m22 (scaling) which are set to 1.


QWMatrix::QWMatrix ( double m11, double m12, double m21, double

       m22, double dx, double dy )
       Constructs a matrix with the specified elements.


double QWMatrix::dx () const

       Returns the horizontal translation.


double QWMatrix::dy () const

       Returns the vertical translation.


QWMatrix QWMatrix::invert ( bool * invertible = 0 ) const

       Returns the inverted matrix.

       identity matrix is returned.

       If *invertible is not null, then the value of *invertible
       will be set to TRUE or FALSE to tell if the matrix is
       invertible or not.


double QWMatrix::m11 () const

       Returns the X scaling factor.


double QWMatrix::m12 () const

       Returns the vertical shearing factor.


double QWMatrix::m21 () const

       Returns the horizontal shearing factor.


double QWMatrix::m22 () const

       Returns the Y scaling factor.


QPoint QWMatrix::map ( const QPoint & p ) const

       Returns the transformed p.


QPointArray QWMatrix::map ( const QPointArray & a ) const

       Returns the point array a transformed by calling map for
       each point.

       Examples: xform/xform.cpp


QRect QWMatrix::map ( const QRect & r ) const

       Returns the transformed rectangle r.

       If rotation or shearing has been specified, then the
       bounding rectangle will be returned.


void QWMatrix::map ( double x, double y, double * tx, double * ty

       ) const
       Transforms (x,y) to (*tx,*ty), using the formulae:

           *tx = m11*x + m21*y + dx
           *ty = m22*y + m12*x + dy


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

       Transforms (x,y) to (*tx,*ty), using the formulae:

           *tx = m11*x + m21*y + dx  --  (rounded to the nearest integer)
           *ty = m22*y + m12*x + dy  --  (rounded to the nearest integer)


bool QWMatrix::operator!= ( const QWMatrix & m ) const

       Returns TRUE if this matrix is not equal to m.


QWMatrix & QWMatrix::operator*= ( const QWMatrix & m )

       Returns the result of multiplying this matrix with m.

       Returns TRUE if this matrix is equal to m.


void QWMatrix::reset ()

       Resets the matrix to an identity matrix.

       All elements are set to zero, except m11 and m22 (scaling)
       that are set to 1.


QWMatrix & QWMatrix::rotate ( double a )

       Rotates the coordinate system a degrees counterclockwise.

       Returns a reference to the matrix.

       See also translate(), scale() and shear().

       Examples: xform/xform.cpp drawdemo/drawdemo.cpp
       desktop/desktop.cpp


QWMatrix & QWMatrix::scale ( double sx, double sy )

       Scales the coordinate system unit by sx horizontally and
       sy vertically.

       Returns a reference to the matrix.

       See also translate(), shear() and rotate().

       Examples: qtimage/qtimage.cpp xform/xform.cpp
       movies/main.cpp


void QWMatrix::setMatrix ( double m11, double m12, double m21,

       double m22, double dx, double dy )
       Sets the matrix elements to the specified values.


QWMatrix & QWMatrix::shear ( double sh, double sv )

       Shears the coordinate system by sh horizontally and sv
       vertically.

       Returns a reference to the matrix.

       See also translate(), scale() and rotate().

       Examples: xform/xform.cpp drawdemo/drawdemo.cpp


QWMatrix & QWMatrix::translate ( double dx, double dy )

       Moves the coordinate system dx along the X-axis and dy
       along the Y-axis.

       Returns a reference to the matrix.

       See also scale(), shear() and rotate().

       Examples: xform/xform.cpp drawdemo/drawdemo.cpp


QWMatrix operator* (const QWMatrix & m1, const QWMatrix & m2)

       Returns the product m1 * m2.

       Remember that matrix multiplication is not commutative,
       thus a*b != b*a.


QDataStream & operator
       Writes a matrix to the stream and returns a reference to
       the stream.

       See also Format of the QDataStream operators


QDataStream & operator>> (QDataStream & s, QWMatrix & m)

       Reads a matrix from the stream and returns a reference to
       the stream.

       See also  Format of the QDataStream operators


SEE ALSO

       http://doc.trolltech.com/qwmatrix.html
       http://www.trolltech.com/faq/tech.html


COPYRIGHT

       Copyright 1992-2001 Trolltech AS,
       http://www.trolltech.com.  See the license file included
       in the distribution for a complete license statement.


AUTHOR

       Generated automatically from the source code.


BUGS

       If you find a bug in Qt, please report it as described in
       http://doc.trolltech.com/bughowto.html.  Good bug reports
       make our job much simpler. Thank you.

       In case of content or formattting problems with this
       manual page, please report them to qt-bugs@trolltech.com.
       Please include the name of the manual page (qwmatrix.3qt)
       and the Qt version (2.3.1).


Man(1) output converted with man2html