1QWMatrix(3qt)                                                    QWMatrix(3qt)
2
3
4

NAME

6       QWMatrix - 2D transformations of a coordinate system
7

SYNOPSIS

9       #include <qwmatrix.h>
10
11   Public Members
12       QWMatrix ()
13       QWMatrix ( double m11, double m12, double m21, double m22, double dx,
14           double dy )
15       void setMatrix ( double m11, double m12, double m21, double m22, double
16           dx, double dy )
17       double m11 () const
18       double m12 () const
19       double m21 () const
20       double m22 () const
21       double dx () const
22       double dy () const
23       void map ( int x, int y, int * tx, int * ty ) const
24       void map ( double x, double y, double * tx, double * ty ) const
25       QRect mapRect ( const QRect & rect ) const
26       QPoint map ( const QPoint & p ) const
27       QRect map ( const QRect & r ) const  (obsolete)
28       QPointArray map ( const QPointArray & a ) const
29       QRegion map ( const QRegion & r ) const
30       QRegion mapToRegion ( const QRect & rect ) const
31       QPointArray mapToPolygon ( const QRect & rect ) const
32       void reset ()
33       bool isIdentity () const
34       QWMatrix & translate ( double dx, double dy )
35       QWMatrix & scale ( double sx, double sy )
36       QWMatrix & shear ( double sh, double sv )
37       QWMatrix & rotate ( double a )
38       bool isInvertible () const
39       double det () const
40       QWMatrix invert ( bool * invertible = 0 ) const
41       bool operator== ( const QWMatrix & m ) const
42       bool operator!= ( const QWMatrix & m ) const
43       QWMatrix & operator*= ( const QWMatrix & m )
44       enum TransformationMode { Points, Areas }
45
46   Static Public Members
47       void setTransformationMode ( QWMatrix::TransformationMode m )
48       TransformationMode transformationMode ()
49
51       QDataStream & operator<< ( QDataStream & s, const QWMatrix & m )
52       QDataStream & operator>> ( QDataStream & s, QWMatrix & m )
53

DESCRIPTION

55       The QWMatrix class specifies 2D transformations of a coordinate system.
56
57       The standard coordinate system of a paint device has the origin located
58       at the top-left position. X values increase to the right; Y values
59       increase downward.
60
61       This coordinate system is the default for the QPainter, which renders
62       graphics in a paint device. A user-defined coordinate system can be
63       specified by setting a QWMatrix for the painter.
64
65       Example:
66
67               MyWidget::paintEvent( QPaintEvent * )
68               {
69                   QPainter p;                      // our painter
70                   QWMatrix m;                      // our transformation matrix
71                   m.rotate( 22.5 );                // rotated coordinate system
72                   p.begin( this );                 // start painting
73                   p.setWorldMatrix( m );           // use rotated coordinate system
74                   p.drawText( 30,20, "detator" );  // draw rotated text at 30,20
75                   p.end();                         // painting done
76               }
77
78       A matrix specifies how to translate, scale, shear or rotate the
79       graphics; the actual transformation is performed by the drawing
80       routines in QPainter and by QPixmap::xForm().
81
82       The QWMatrix class contains a 3x3 matrix of the form:
83
84       m11
85       ────
86       m21
87       dx
88
89
90       A matrix transforms a point in the plane to another point:
91
92               x' = m11*x + m21*y + dx
93               y' = m22*y + m12*x + dy
94
95       The point (x, y) is the original point, and (x', y') is the transformed
96       point. (x', y') can be transformed back to (x, y) by performing the
97       same operation on the inverted matrix.
98
99       The elements dx and dy specify horizontal and vertical translation. The
100       elements m11 and m22 specify horizontal and vertical scaling. The
101       elements m12 and m21 specify horizontal and vertical shearing.
102
103       The identity matrix has m11 and m22 set to 1; all others are set to 0.
104       This matrix maps a point to itself.
105
106       Translation is the simplest transformation. Setting dx and dy will move
107       the coordinate system dx units along the X axis and dy units along the
108       Y axis.
109
110       Scaling can be done by setting m11 and m22. For example, setting m11 to
111       2 and m22 to 1.5 will double the height and increase the width by 50%.
112
113       Shearing is controlled by m12 and m21. Setting these elements to values
114       different from zero will twist the coordinate system.
115
116       Rotation is achieved by carefully setting both the shearing factors and
117       the scaling factors. The QWMatrix also has a function that sets
118       rotation directly.
119
120       QWMatrix lets you combine transformations like this:
121
122               QWMatrix m;           // identity matrix
123               m.translate(10, -20); // first translate (10,-20)
124               m.rotate(25);         // then rotate 25 degrees
125               m.scale(1.2, 0.7);    // finally scale it
126
127       Here's the same example using basic matrix operations:
128
129               double a    = pi/180 * 25;         // convert 25 to radians
130               double sina = sin(a);
131               double cosa = cos(a);
132               QWMatrix m1(1, 0, 0, 1, 10, -20);  // translation matrix
133               QWMatrix m2( cosa, sina,           // rotation matrix
134                           -sina, cosa, 0, 0 );
135               QWMatrix m3(1.2, 0, 0, 0.7, 0, 0); // scaling matrix
136               QWMatrix m;
137               m = m3 * m2 * m1;                  // combine all transformations
138
139       QPainter has functions to translate, scale, shear and rotate the
140       coordinate system without using a QWMatrix. Although these functions
141       are very convenient, it can be more efficient to build a QWMatrix and
142       call QPainter::setWorldMatrix() if you want to perform more than a
143       single transform operation.
144
145       See also QPainter::setWorldMatrix(), QPixmap::xForm(), Graphics
146       Classes, and Image Processing Classes.
147
148   Member Type Documentation

QWMatrix::TransformationMode

150       QWMatrix offers two transformation modes. Calculations can either be
151       done in terms of points (Points mode, the default), or in terms of area
152       (Area mode).
153
154       In Points mode the transformation is applied to the points that mark
155       out the shape's bounding line. In Areas mode the transformation is
156       applied in such a way that the area of the contained region is
157       correctly transformed under the matrix.
158
159       QWMatrix::Points - transformations are applied to the shape's points.
160
161       QWMatrix::Areas - transformations are applied (e.g. to the width and
162       height) so that the area is transformed.
163
164       Example:
165
166       Suppose we have a rectangle, QRect( 10, 20, 30, 40 ) and a
167       transformation matrix QWMatrix( 2, 0, 0, 2, 0, 0 ) to double the
168       rectangle's size.
169
170       In Points mode, the matrix will transform the top-left (10,20) and the
171       bottom-right (39,59) points producing a rectangle with its top-left
172       point at (20,40) and its bottom-right point at (78,118), i.e. with a
173       width of 59 and a height of 79.
174
175       In Areas mode, the matrix will transform the top-left point in the same
176       way as in Points mode to (20/40), and double the width and height, so
177       the bottom-right will become (69,99), i.e. a width of 60 and a height
178       of 80.
179
180       Because integer arithmetic is used (for speed), rounding differences
181       mean that the modes will produce slightly different results given the
182       same shape and the same transformation, especially when scaling up.
183       This also means that some operations are not commutative.
184
185       Under Points mode, matrix * ( region1 | region2 ) is not equal to
186       matrix * region1 | matrix * region2. Under Area mode, matrix *
187       (pointarray[i]) is not neccesarily equal to (matrix * pointarry)[i].
188
189       <center>
190                                   [Image Omitted]
191
192       </center>
193

MEMBER FUNCTION DOCUMENTATION

QWMatrix::QWMatrix ()

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

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

200       dx, double dy )
201       Constructs a matrix with the elements, m11, m12, m21, m22, dx and dy.
202

double QWMatrix::det () const

204       Returns the matrix's determinant.
205

double QWMatrix::dx () const

207       Returns the horizontal translation.
208

double QWMatrix::dy () const

210       Returns the vertical translation.
211

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

213       Returns the inverted matrix.
214
215       If the matrix is singular (not invertible), the identity matrix is
216       returned.
217
218       If invertible is not 0: the value of *invertible is set to TRUE if the
219       matrix is invertible; otherwise *invertible is set to FALSE.
220
221       See also isInvertible().
222
223       Example: t14/cannon.cpp.
224

bool QWMatrix::isIdentity () const

226       Returns TRUE if the matrix is the identity matrix; otherwise returns
227       FALSE.
228
229       See also reset().
230

bool QWMatrix::isInvertible () const

232       Returns TRUE if the matrix is invertible; otherwise returns FALSE.
233
234       See also invert().
235

double QWMatrix::m11 () const

237       Returns the X scaling factor.
238

double QWMatrix::m12 () const

240       Returns the vertical shearing factor.
241

double QWMatrix::m21 () const

243       Returns the horizontal shearing factor.
244

double QWMatrix::m22 () const

246       Returns the Y scaling factor.
247

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

249       Transforms ( x, y ) to ( *tx, *ty ) using the formulae:
250
251               *tx = m11*x + m21*y + dx  (rounded to the nearest integer)
252               *ty = m22*y + m12*x + dy  (rounded to the nearest integer)
253
254       Examples:
255

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

257       This is an overloaded member function, provided for convenience. It
258       behaves essentially like the above function.
259
260       Transforms ( x, y ) to ( *tx, *ty ) using the following formulae:
261
262               *tx = m11*x + m21*y + dx
263               *ty = m22*y + m12*x + dy
264

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

266       This is an overloaded member function, provided for convenience. It
267       behaves essentially like the above function.
268
269       Transforms p to using the formulae:
270
271               retx = m11*px + m21*py + dx  (rounded to the nearest integer)
272               rety = m22*py + m12*px + dy  (rounded to the nearest integer)
273

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

275       This function is obsolete. It is provided to keep old source working.
276       We strongly advise against using it in new code.
277
278       Please use QWMatrix::mapRect() instead.
279
280       Note that this method does return the bounding rectangle of the r, when
281       shearing or rotations are used.
282

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

284       This is an overloaded member function, provided for convenience. It
285       behaves essentially like the above function.
286
287       Returns the point array a transformed by calling map for each point.
288

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

290       This is an overloaded member function, provided for convenience. It
291       behaves essentially like the above function.
292
293       Transforms the region r.
294
295       Calling this method can be rather expensive, if rotations or shearing
296       are used.
297

QRect QWMatrix::mapRect ( const QRect & rect ) const

299       Returns the transformed rectangle rect.
300
301       The bounding rectangle is returned if rotation or shearing has been
302       specified.
303
304       If you need to know the exact region rect maps to use operator*().
305
306       See also operator*().
307
308       Example: xform/xform.cpp.
309

QPointArray QWMatrix::mapToPolygon ( const QRect & rect ) const

311       Returns the transformed rectangle rect as a polygon.
312
313       Polygons and rectangles behave slightly differently when transformed
314       (due to integer rounding), so matrix.map( QPointArray( rect ) ) is not
315       always the same as matrix.mapToPolygon( rect ).
316

QRegion QWMatrix::mapToRegion ( const QRect & rect ) const

318       Returns the transformed rectangle rect.
319
320       A rectangle which has been rotated or sheared may result in a non-
321       rectangular region being returned.
322
323       Calling this method can be expensive, if rotations or shearing are
324       used. If you just need to know the bounding rectangle of the returned
325       region, use mapRect() which is a lot faster than this function.
326
327       See also QWMatrix::mapRect().
328

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

330       Returns TRUE if this matrix is not equal to m; otherwise returns FALSE.
331

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

333       Returns the result of multiplying this matrix by matrix m.
334

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

336       Returns TRUE if this matrix is equal to m; otherwise returns FALSE.
337

void QWMatrix::reset ()

339       Resets the matrix to an identity matrix.
340
341       All elements are set to zero, except m11 and m22 (scaling) which are
342       set to 1.
343
344       See also isIdentity().
345

QWMatrix & QWMatrix::rotate ( double a )

347       Rotates the coordinate system a degrees counterclockwise.
348
349       Returns a reference to the matrix.
350
351       See also translate(), scale(), and shear().
352
353       Examples:
354

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

356       Scales the coordinate system unit by sx horizontally and sy vertically.
357
358       Returns a reference to the matrix.
359
360       See also translate(), shear(), and rotate().
361
362       Examples:
363

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

365       double dx, double dy )
366       Sets the matrix elements to the specified values, m11, m12, m21, m22,
367       dx and dy.
368

void QWMatrix::setTransformationMode ( QWMatrix::TransformationMode m )

370       [static]
371       Sets the transformation mode that QWMatrix and painter transformations
372       use to m.
373
374       See also QWMatrix::TransformationMode.
375

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

377       Shears the coordinate system by sh horizontally and sv vertically.
378
379       Returns a reference to the matrix.
380
381       See also translate(), scale(), and rotate().
382
383       Examples:
384

TransformationMode QWMatrix::transformationMode () [static]

386       Returns the current transformation mode.
387
388       See also QWMatrix::TransformationMode.
389

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

391       Moves the coordinate system dx along the X-axis and dy along the Y-
392       axis.
393
394       Returns a reference to the matrix.
395
396       See also scale(), shear(), and rotate().
397
398       Examples:
399

QDataStream & operator<< ( QDataStream & s, const QWMatrix & m )

402       Writes the matrix m to the stream s and returns a reference to the
403       stream.
404
405       See also Format of the QDataStream operators.
406

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

408       Reads the matrix m from the stream s and returns a reference to the
409       stream.
410
411       See also Format of the QDataStream operators.
412
413

SEE ALSO

415       http://doc.trolltech.com/qwmatrix.html
416       http://www.trolltech.com/faq/tech.html
417
419       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
420       license file included in the distribution for a complete license
421       statement.
422

AUTHOR

424       Generated automatically from the source code.
425

BUGS

427       If you find a bug in Qt, please report it as described in
428       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
429       help you. Thank you.
430
431       The definitive Qt documentation is provided in HTML format; it is
432       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
433       web browser. This man page is provided as a convenience for those users
434       who prefer man pages, although this format is not officially supported
435       by Trolltech.
436
437       If you find errors in this manual page, please report them to qt-
438       bugs@trolltech.com.  Please include the name of the manual page
439       (qwmatrix.3qt) and the Qt version (3.3.8).
440
441
442
443Trolltech AS                    2 February 2007                  QWMatrix(3qt)
Impressum