1QWMatrix(3qt) QWMatrix(3qt)
2
6 QWMatrix - 2D transformations of a coordinate system
7
9 #include <qwmatrix.h>
10 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 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
55 The QWMatrix class specifies 2D transformations of a coordinate system.
56 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 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 Example:
66 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 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 The QWMatrix class contains a 3x3 matrix of the form:
83 m11
85 ────
86 m21
87 dx
88 A matrix transforms a point in the plane to another point:
91 x' = m11*x + m21*y + dx
93 y' = m22*y + m12*x + dy
94 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 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 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 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 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 Shearing is controlled by m12 and m21. Setting these elements to values
114 different from zero will twist the coordinate system.
115 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 QWMatrix lets you combine transformations like this:
121 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 Here's the same example using basic matrix operations:
128 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 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 See also QPainter::setWorldMatrix(), QPixmap::xForm(), Graphics
146 Classes, and Image Processing Classes.
147 Member Type Documentation
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 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 QWMatrix::Points - transformations are applied to the shape's points.
160 QWMatrix::Areas - transformations are applied (e.g. to the width and
162 height) so that the area is transformed.
163 Example:
165 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 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 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 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 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 <center>
190 [Image Omitted]
191 </center>
193
196 Constructs an identity matrix. All elements are set to zero except m11
197 and m22 (scaling), which are set to 1.
198
200 dx, double dy )
201 Constructs a matrix with the elements, m11, m12, m21, m22, dx and dy.
202
204 Returns the matrix's determinant.
205
207 Returns the horizontal translation.
208
210 Returns the vertical translation.
211
213 Returns the inverted matrix.
214 If the matrix is singular (not invertible), the identity matrix is
216 returned.
217 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 See also isInvertible().
222 Example: t14/cannon.cpp.
224
226 Returns TRUE if the matrix is the identity matrix; otherwise returns
227 FALSE.
228 See also reset().
230
232 Returns TRUE if the matrix is invertible; otherwise returns FALSE.
233 See also invert().
235
237 Returns the X scaling factor.
238
240 Returns the vertical shearing factor.
241
243 Returns the horizontal shearing factor.
244
246 Returns the Y scaling factor.
247
249 Transforms ( x, y ) to ( *tx, *ty ) using the formulae:
250 *tx = m11*x + m21*y + dx (rounded to the nearest integer)
252 *ty = m22*y + m12*x + dy (rounded to the nearest integer)
253 Examples:
255
257 This is an overloaded member function, provided for convenience. It
258 behaves essentially like the above function.
259 Transforms ( x, y ) to ( *tx, *ty ) using the following formulae:
261 *tx = m11*x + m21*y + dx
263 *ty = m22*y + m12*x + dy
264
266 This is an overloaded member function, provided for convenience. It
267 behaves essentially like the above function.
268 Transforms p to using the formulae:
270 retx = m11*px + m21*py + dx (rounded to the nearest integer)
272 rety = m22*py + m12*px + dy (rounded to the nearest integer)
273
275 This function is obsolete. It is provided to keep old source working.
276 We strongly advise against using it in new code.
277 Please use QWMatrix::mapRect() instead.
279 Note that this method does return the bounding rectangle of the r, when
281 shearing or rotations are used.
282
284 This is an overloaded member function, provided for convenience. It
285 behaves essentially like the above function.
286 Returns the point array a transformed by calling map for each point.
288
290 This is an overloaded member function, provided for convenience. It
291 behaves essentially like the above function.
292 Transforms the region r.
294 Calling this method can be rather expensive, if rotations or shearing
296 are used.
297
299 Returns the transformed rectangle rect.
300 The bounding rectangle is returned if rotation or shearing has been
302 specified.
303 If you need to know the exact region rect maps to use operator*().
305 See also operator*().
307 Example: xform/xform.cpp.
309
311 Returns the transformed rectangle rect as a polygon.
312 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
318 Returns the transformed rectangle rect.
319 A rectangle which has been rotated or sheared may result in a non-
321 rectangular region being returned.
322 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 See also QWMatrix::mapRect().
328
330 Returns TRUE if this matrix is not equal to m; otherwise returns FALSE.
331
333 Returns the result of multiplying this matrix by matrix m.
334
336 Returns TRUE if this matrix is equal to m; otherwise returns FALSE.
337
339 Resets the matrix to an identity matrix.
340 All elements are set to zero, except m11 and m22 (scaling) which are
342 set to 1.
343 See also isIdentity().
345
347 Rotates the coordinate system a degrees counterclockwise.
348 Returns a reference to the matrix.
350 See also translate(), scale(), and shear().
352 Examples:
354
356 Scales the coordinate system unit by sx horizontally and sy vertically.
357 Returns a reference to the matrix.
359 See also translate(), shear(), and rotate().
361 Examples:
363
365 double dx, double dy )
366 Sets the matrix elements to the specified values, m11, m12, m21, m22,
367 dx and dy.
368
370 [static]
371 Sets the transformation mode that QWMatrix and painter transformations
372 use to m.
373 See also QWMatrix::TransformationMode.
375
377 Shears the coordinate system by sh horizontally and sv vertically.
378 Returns a reference to the matrix.
380 See also translate(), scale(), and rotate().
382 Examples:
384
386 Returns the current transformation mode.
387 See also QWMatrix::TransformationMode.
389
391 Moves the coordinate system dx along the X-axis and dy along the Y-
392 axis.
393 Returns a reference to the matrix.
395 See also scale(), shear(), and rotate().
397 Examples:
399
402 Writes the matrix m to the stream s and returns a reference to the
403 stream.
404 See also Format of the QDataStream operators.
406
408 Reads the matrix m from the stream s and returns a reference to the
409 stream.
410 See also Format of the QDataStream operators.
412
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
424 Generated automatically from the source code.
425
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 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 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).
440Trolltech AS 2 February 2007 QWMatrix(3qt)