qwmatrix.3qt

Qt/Embedded是一个多平台的C++图形用户界面应用程序框架

.TH QWMatrix 3qt "10 November 2000" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2000 Trolltech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QWMatrix \- 2D transformations of a coordinate system
.SH SYNOPSIS
.br
.PP
\fC#include <qwmatrix.h>\fR
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "\fBQWMatrix\fR () "
.br
.ti -1c
.BI "\fBQWMatrix\fR ( double " "m11" ", double " "m12" ", double " "m21" ", double " "m22" ", double " "dx" ", double dy ) "
.br
.ti -1c
.BI "void \fBsetMatrix\fR ( double " "m11" ", double " "m12" ", double " "m21" ", double " "m22" ", double " "dx" ", double dy ) "
.br
.ti -1c
.BI "double \fBm11\fR () const"
.br
.ti -1c
.BI "double \fBm12\fR () const"
.br
.ti -1c
.BI "double \fBm21\fR () const"
.br
.ti -1c
.BI "double \fBm22\fR () const"
.br
.ti -1c
.BI "double \fBdx\fR () const"
.br
.ti -1c
.BI "double \fBdy\fR () const"
.br
.ti -1c
.BI "void \fBmap\fR ( int " "x" ", int " "y" ", int * " "tx" ", int * ty ) const"
.br
.ti -1c
.BI "void \fBmap\fR ( double " "x" ", double " "y" ", double * " "tx" ", double * ty ) const"
.br
.ti -1c
.BI "QPoint \fBmap\fR ( const QPoint & ) const"
.br
.ti -1c
.BI "QRect \fBmap\fR ( const QRect & ) const"
.br
.ti -1c
.BI "QPointArray \fBmap\fR ( const QPointArray & ) const"
.br
.ti -1c
.BI "void \fBreset\fR () "
.br
.ti -1c
.BI "QWMatrix& \fBtranslate\fR ( double " "dx" ", double dy ) "
.br
.ti -1c
.BI "QWMatrix& \fBscale\fR ( double " "sx" ", double sy ) "
.br
.ti -1c
.BI "QWMatrix& \fBshear\fR ( double " "sh" ", double sv ) "
.br
.ti -1c
.BI "QWMatrix& \fBrotate\fR ( double a ) "
.br
.ti -1c
.BI "QWMatrix \fBinvert\fR ( bool * = 0 ) const"
.br
.ti -1c
.BI "bool \fBoperator==\fR ( const QWMatrix & ) const"
.br
.ti -1c
.BI "bool \fBoperator!=\fR ( const QWMatrix & ) const"
.br
.ti -1c
.BI "QWMatrix& \fBoperator*=\fR ( const QWMatrix & ) "
.br
.in -1c
.SH RELATED FUNCTION DOCUMENTATION
(Note that these are not member functions.)
.in +1c
.ti -1c
.BI "QWMatrix \fBoperator*\fR (const QWMatrix & " "m1" ", const QWMatrix & " "m2" ")"
.br
.ti -1c
.BI "QDataStream & \fBoperator<<\fR (QDataStream & " "s" ", const QWMatrix & " "m" ")"
.br
.ti -1c
.BI "QDataStream & \fBoperator>>\fR (QDataStream & " "s" ", QWMatrix & " "m" ")"
.br
.in -1c
.SH DESCRIPTION
The QWMatrix class specifies 2D transformations of a coordinate system.
.PP
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.
.PP
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.
.PP
Example:
.PP
.nf
.br
    MyWidget::paintEvent( QPaintEvent * )
.br
    {
.br
      QPainter p;                       // our painter
.br
      QWMatrix m;                       // our transformation matrix
.br
      m.rotate( 22.5 );                 // rotated coordinate system
.br
      p.begin( this );                  // start painting
.br
      p.setWorldMatrix( m );            // use rotated coordinate system
.br
      p.drawText( 30,20, "detator" );   // draw rotated text at 30,20
.br
      p.end();                          // painting done
.br
    }
.fi
.PP
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().
.PP
The QWMatrix class contains a 3*3 matrix of the form:
.PP
.nf
.br
    m11  m12  0
.br
    m21  m22  0
.br
    dx   dy   1
.br
.fi
.PP
A matrix transforms a point in the plane to another point:
.PP
.nf
.br
    x' = m11*x + m21*y + dx
.br
    y' = m22*y + m12*x + dy
.fi
.PP
The point \fI(x,y)\fR is the original point, and \fI(x',y')\fR is the transformed point. \fI(x',y')\fR can be transformed back to \fI(x,y)\fR by performing the same operation on the inverted matrix.
.PP
The elements \fIdx\fR and \fIdy\fR specify horisontal and vertical translation. The elements \fIm11\fR and \fIm22\fR specify horisontal and vertical scaling. The elements \fIm12\fR and \fIm21\fR specify horisontal and vertical shearing.
.PP
The identity matrix has \fIm11\fR and \fIm22\fR set to 1, all others set to 0. This matrix maps a point to itself.
.PP
Translation is the simplest transformation. Setting \fIdx\fR and \fIdy\fR will move the coordinate system \fIdx\fR units along the X axis and \fIdy\fR units along the Y axis.
.PP
Scaling can be done by setting \fIm11\fR and \fIm22.\fR For example, setting \fIm11\fR to 2 and \fIm22\fR to 1.5 will double the height and increase the width by 50%.
.PP
Shearing is controlled by \fIm12\fR and \fIm21.\fR Setting these elements to values different from zero will twist the coordinate system.
.PP
Rotation is achieved by carefully setting both the shearing factors and the scaling factors. The QWMatrix has a function that sets rotation directly.
.PP
QWMatrix lets you combine transformations like this:
.PP
.nf
.br
    QWMatrix m;                                 // identity matrix
.br
    m.translate(10, -20);                       // first translate (10,-20)
.br
    m.rotate(25);                               // then rotate 25 degrees
.br
    m.scale(1.2, 0.7);                          // finally scale it
.fi
.PP
The same example, but using basic matrix operations:
.PP
.nf
.br
    double a    = pi/180 * 25;                  // convert 25 to radians
.br
    double sina = sin(a);
.br
    double cosa = cos(a);
.br
    QWMatrix m1(0, 0, 0, 0, 10, -20);           // translation matrix
.br
    QWMatrix m2( cosa, sina,                    // rotation matrix
.br
                -sina, cosa, 0, 0 );
.br
    QWMatrix m3(1.2, 0, 0, 0.7, 0, 0);          // scaling matrix
.br
    QWMatrix m;
.br
    m = m3 * m2 * m1;                           // combine all transformations
.fi
.PP
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().
.PP
See also QPainter::setWorldMatrix() and QPixmap::xForm().
.PP
Examples:
.(l
qtimage/qtimage.cpp xform/xform.cpp drawdemo/drawdemo.cpp qmag/qmag.cpp desktop/desktop.cpp movies/main.cpp
.)l
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QWMatrix::QWMatrix ()"
Constructs an identity matrix. All elements are set to zero, except \fIm11\fR and \fIm22\fR (scaling) which are set to 1.
.SH "QWMatrix::QWMatrix ( double m11, double m12, double m21, double m22, double dx, double dy )"
Constructs a matrix with the specified elements.
.SH "double QWMatrix::dx () const"
Returns the horizontal translation.
.SH "double QWMatrix::dy () const"
Returns the vertical translation.
.SH "QWMatrix QWMatrix::invert ( bool * invertible = 0 ) const"
Returns the inverted matrix.
.PP
If the matrix is singular (not invertible), then the identity matrix is returned.
.PP
If \fI*invertible\fR is not null, then the value of \fI*invertible\fR will be set to TRUE or FALSE to tell if the matrix is invertible or not.
.SH "double QWMatrix::m11 () const"
Returns the X scaling factor.
.SH "double QWMatrix::m12 () const"
Returns the vertical shearing factor.
.SH "double QWMatrix::m21 () const"
Returns the horizontal shearing factor.
.SH "double QWMatrix::m22 () const"
Returns the Y scaling factor.
.SH "QPoint QWMatrix::map ( const QPoint & p ) const"
Returns the transformed \fIp.\fR
.SH "QPointArray QWMatrix::map ( const QPointArray & a ) const"
Returns the point array \fIa\fR transformed by calling map for each point.
.PP
Examples:
.(l
xform/xform.cpp
.)l
.SH "QRect QWMatrix::map ( const QRect & r ) const"
Returns the transformed rectangle \fIr.\fR
.PP
If rotation or shearing has been specified, then the bounding rectangle will be returned.
.SH "void QWMatrix::map ( double x, double y, double * tx, double * ty ) const"
Transforms \fI(x,y)\fR to \fI(*tx,*ty),\fR using the formulae:
.PP
.nf
.br
    *tx = m11*x + m21*y + dx
.br
    *ty = m22*y + m12*x + dy
.fi
.SH "void QWMatrix::map ( int x, int y, int * tx, int * ty ) const"
Transforms \fI(x,y)\fR to \fI(*tx,*ty),\fR using the formulae:
.PP
.nf
.br
    *tx = m11*x + m21*y + dx  --  (rounded to the nearest integer)
.br
    *ty = m22*y + m12*x + dy  --  (rounded to the nearest integer)
.fi
.SH "bool QWMatrix::operator!= ( const QWMatrix & m ) const"
Returns TRUE if this matrix is not equal to \fIm.\fR
.SH "QWMatrix & QWMatrix::operator*= ( const QWMatrix & m )"
Returns the result of multiplying this matrix with \fIm.\fR
.SH "bool QWMatrix::operator== ( const QWMatrix & m ) const"
Returns TRUE if this matrix is equal to \fIm.\fR
.SH "void QWMatrix::reset ()"
Resets the matrix to an identity matrix.
.PP
All elements are set to zero, except \fIm11\fR and \fIm22\fR (scaling) that are set to 1.
.SH "QWMatrix & QWMatrix::rotate ( double a )"
Rotates the coordinate system \fIa\fR degrees counterclockwise.
.PP
Returns a reference to the matrix.
.PP
See also translate(), scale() and shear().
.PP
Examples:
.(l
xform/xform.cpp drawdemo/drawdemo.cpp desktop/desktop.cpp
.)l
.SH "QWMatrix & QWMatrix::scale ( double sx, double sy )"
Scales the coordinate system unit by \fIsx\fR horizontally and \fIsy\fR vertically.
.PP
Returns a reference to the matrix.
.PP
See also translate(), shear() and rotate().
.PP
Examples:
.(l
qtimage/qtimage.cpp xform/xform.cpp movies/main.cpp
.)l
.SH "void QWMatrix::setMatrix ( double m11, double m12, double m21, double m22, double dx, double dy )"
Sets the matrix elements to the specified values.
.SH "QWMatrix & QWMatrix::shear ( double sh, double sv )"
Shears the coordinate system by \fIsh\fR horizontally and \fIsv\fR vertically.
.PP
Returns a reference to the matrix.
.PP
See also translate(), scale() and rotate().
.PP
Examples:
.(l
xform/xform.cpp drawdemo/drawdemo.cpp
.)l
.SH "QWMatrix & QWMatrix::translate ( double dx, double dy )"
Moves the coordinate system \fIdx\fR along the X-axis and \fIdy\fR along the Y-axis.
.PP
Returns a reference to the matrix.
.PP
See also scale(), shear() and rotate().
.PP
Examples:
.(l
xform/xform.cpp drawdemo/drawdemo.cpp
.)l
.SH RELATED FUNCTION DOCUMENTATION
.SH "QWMatrix operator* (const QWMatrix & m1, const QWMatrix & m2)"
Returns the product \fIm1\fR * \fIm2.\fR
.PP
Remember that matrix multiplication is not commutative, thus a*b != b*a.
.SH "QDataStream & operator<< (QDataStream & s, const QWMatrix & m)"
Writes a matrix to the stream and returns a reference to the stream.
.PP
See also Format of the QDataStream operators
.SH "QDataStream & operator>> (QDataStream & s, QWMatrix & m)"
Reads a matrix from the stream and returns a reference to the stream.
.PP
See also  Format of the QDataStream operators
.SH "SEE ALSO"
.BR http://doc.trolltech.com/qwmatrix.html
.SH COPYRIGHT
Copyright 1992-2000 Trolltech AS, http://www.trolltech.com/.  See the
license file included in the distribution for a complete license
statement.
.SH AUTHOR
Generated automatically from the source code.