1 058b0118 2005-01-03 devnull .TH MATRIX 3
3 058b0118 2005-01-03 devnull ident, matmul, matmulr, determinant, adjoint, invertmat, xformpoint, xformpointd, xformplane, pushmat, popmat, rot, qrot, scale, move, xform, ixform, persp, look, viewport \- Geometric transformations
4 058b0118 2005-01-03 devnull .SH SYNOPSIS
7 058b0118 2005-01-03 devnull #include <draw.h>
10 058b0118 2005-01-03 devnull #include <geometry.h>
13 058b0118 2005-01-03 devnull void ident(Matrix m)
16 058b0118 2005-01-03 devnull void matmul(Matrix a, Matrix b)
19 058b0118 2005-01-03 devnull void matmulr(Matrix a, Matrix b)
22 058b0118 2005-01-03 devnull double determinant(Matrix m)
25 058b0118 2005-01-03 devnull void adjoint(Matrix m, Matrix madj)
28 058b0118 2005-01-03 devnull double invertmat(Matrix m, Matrix inv)
31 058b0118 2005-01-03 devnull Point3 xformpoint(Point3 p, Space *to, Space *from)
34 058b0118 2005-01-03 devnull Point3 xformpointd(Point3 p, Space *to, Space *from)
37 058b0118 2005-01-03 devnull Point3 xformplane(Point3 p, Space *to, Space *from)
40 058b0118 2005-01-03 devnull Space *pushmat(Space *t)
43 058b0118 2005-01-03 devnull Space *popmat(Space *t)
46 058b0118 2005-01-03 devnull void rot(Space *t, double theta, int axis)
49 058b0118 2005-01-03 devnull void qrot(Space *t, Quaternion q)
52 058b0118 2005-01-03 devnull void scale(Space *t, double x, double y, double z)
55 058b0118 2005-01-03 devnull void move(Space *t, double x, double y, double z)
58 058b0118 2005-01-03 devnull void xform(Space *t, Matrix m)
61 058b0118 2005-01-03 devnull void ixform(Space *t, Matrix m, Matrix inv)
64 058b0118 2005-01-03 devnull int persp(Space *t, double fov, double n, double f)
67 058b0118 2005-01-03 devnull void look(Space *t, Point3 eye, Point3 look, Point3 up)
70 058b0118 2005-01-03 devnull void viewport(Space *t, Rectangle r, double aspect)
71 058b0118 2005-01-03 devnull .SH DESCRIPTION
72 058b0118 2005-01-03 devnull These routines manipulate 3-space affine and projective transformations,
73 058b0118 2005-01-03 devnull represented as 4\(mu4 matrices, thus:
77 058b0118 2005-01-03 devnull typedef double Matrix[4][4];
81 058b0118 2005-01-03 devnull stores an identity matrix in its argument.
82 058b0118 2005-01-03 devnull .I Matmul
84 058b0118 2005-01-03 devnull .I a\(mub
87 058b0118 2005-01-03 devnull .I Matmulr
89 058b0118 2005-01-03 devnull .I b\(mua
92 058b0118 2005-01-03 devnull .I Determinant
93 058b0118 2005-01-03 devnull returns the determinant of matrix
95 058b0118 2005-01-03 devnull .I Adjoint
96 058b0118 2005-01-03 devnull stores the adjoint (matrix of cofactors) of
99 058b0118 2005-01-03 devnull .IR madj .
100 058b0118 2005-01-03 devnull .I Invertmat
101 058b0118 2005-01-03 devnull stores the inverse of matrix
104 058b0118 2005-01-03 devnull .IR minv ,
105 058b0118 2005-01-03 devnull returning
106 058b0118 2005-01-03 devnull .IR m 's
107 058b0118 2005-01-03 devnull determinant.
110 058b0118 2005-01-03 devnull be singular (determinant zero),
111 058b0118 2005-01-03 devnull .I invertmat
112 058b0118 2005-01-03 devnull stores its
113 058b0118 2005-01-03 devnull adjoint in
114 058b0118 2005-01-03 devnull .IR minv .
116 058b0118 2005-01-03 devnull The rest of the routines described here
117 058b0118 2005-01-03 devnull manipulate
118 058b0118 2005-01-03 devnull .I Spaces
119 058b0118 2005-01-03 devnull and transform
120 058b0118 2005-01-03 devnull .IR Point3s .
122 058b0118 2005-01-03 devnull .I Point3
123 058b0118 2005-01-03 devnull is a point in three-space, represented by its
124 058b0118 2005-01-03 devnull homogeneous coordinates:
127 058b0118 2005-01-03 devnull typedef struct Point3 Point3;
128 058b0118 2005-01-03 devnull struct Point3{
129 058b0118 2005-01-03 devnull double x, y, z, w;
133 058b0118 2005-01-03 devnull The homogeneous coordinates
134 058b0118 2005-01-03 devnull .RI ( x ,
138 058b0118 2005-01-03 devnull represent the Euclidean point
139 058b0118 2005-01-03 devnull .RI ( x / w ,
140 058b0118 2005-01-03 devnull .IR y / w ,
141 058b0118 2005-01-03 devnull .IR z / w )
143 058b0118 2005-01-03 devnull .IR w ≠0,
144 058b0118 2005-01-03 devnull and a ``point at infinity'' if
145 058b0118 2005-01-03 devnull .IR w =0.
148 058b0118 2005-01-03 devnull .I Space
149 058b0118 2005-01-03 devnull is just a data structure describing a coordinate system:
152 058b0118 2005-01-03 devnull typedef struct Space Space;
153 058b0118 2005-01-03 devnull struct Space{
154 058b0118 2005-01-03 devnull Matrix t;
155 058b0118 2005-01-03 devnull Matrix tinv;
156 058b0118 2005-01-03 devnull Space *next;
160 058b0118 2005-01-03 devnull It contains a pair of transformation matrices and a pointer
162 058b0118 2005-01-03 devnull .IR Space 's
163 058b0118 2005-01-03 devnull parent. The matrices transform points to and from the ``root
164 058b0118 2005-01-03 devnull coordinate system,'' which is represented by a null
165 058b0118 2005-01-03 devnull .I Space
166 058b0118 2005-01-03 devnull pointer.
168 058b0118 2005-01-03 devnull .I Pushmat
169 058b0118 2005-01-03 devnull creates a new
170 058b0118 2005-01-03 devnull .IR Space .
171 058b0118 2005-01-03 devnull Its argument is a pointer to the parent space. Its result
172 058b0118 2005-01-03 devnull is a newly allocated copy of the parent, but with its
174 058b0118 2005-01-03 devnull pointer pointing at the parent.
175 058b0118 2005-01-03 devnull .I Popmat
176 058b0118 2005-01-03 devnull discards the
177 058b0118 2005-01-03 devnull .B Space
178 058b0118 2005-01-03 devnull that is its argument, returning a pointer to the stack.
179 058b0118 2005-01-03 devnull Nominally, these two functions define a stack of transformations,
181 058b0118 2005-01-03 devnull .B pushmat
182 058b0118 2005-01-03 devnull can be called multiple times
183 058b0118 2005-01-03 devnull on the same
184 058b0118 2005-01-03 devnull .B Space
185 058b0118 2005-01-03 devnull multiple times, creating a transformation tree.
187 058b0118 2005-01-03 devnull .I Xformpoint
189 058b0118 2005-01-03 devnull .I Xformpointd
190 058b0118 2005-01-03 devnull both transform points from the
191 058b0118 2005-01-03 devnull .B Space
192 058b0118 2005-01-03 devnull pointed to by
194 058b0118 2005-01-03 devnull to the space pointed to by
195 058b0118 2005-01-03 devnull .IR to .
196 058b0118 2005-01-03 devnull Either pointer may be null, indicating the root coordinate system.
197 058b0118 2005-01-03 devnull The difference between the two functions is that
198 058b0118 2005-01-03 devnull .B xformpointd
208 058b0118 2005-01-03 devnull .IR w ≠0,
210 058b0118 2005-01-03 devnull .RI ( x ,
213 058b0118 2005-01-03 devnull the Euclidean coordinates of the point.
215 058b0118 2005-01-03 devnull .I Xformplane
216 058b0118 2005-01-03 devnull transforms planes or normal vectors. A plane is specified by the
217 058b0118 2005-01-03 devnull coefficients
218 058b0118 2005-01-03 devnull .RI ( a ,
222 058b0118 2005-01-03 devnull of its implicit equation
223 058b0118 2005-01-03 devnull .IR ax+by+cz+d =0.
224 058b0118 2005-01-03 devnull Since this representation is dual to the homogeneous representation of points,
225 058b0118 2005-01-03 devnull .B libgeometry
226 058b0118 2005-01-03 devnull represents planes by
227 058b0118 2005-01-03 devnull .B Point3
228 058b0118 2005-01-03 devnull structures, with
229 058b0118 2005-01-03 devnull .RI ( a ,
233 058b0118 2005-01-03 devnull stored in
234 058b0118 2005-01-03 devnull .RI ( x ,
237 058b0118 2005-01-03 devnull .IR w ).
239 058b0118 2005-01-03 devnull The remaining functions transform the coordinate system represented
241 058b0118 2005-01-03 devnull .BR Space .
243 058b0118 2005-01-03 devnull .B Space *
244 058b0118 2005-01-03 devnull argument must be non-null \(em you can't modify the root
245 058b0118 2005-01-03 devnull .BR Space .
247 058b0118 2005-01-03 devnull rotates by angle
248 058b0118 2005-01-03 devnull .I theta
249 058b0118 2005-01-03 devnull (in radians) about the given
250 058b0118 2005-01-03 devnull .IR axis ,
251 058b0118 2005-01-03 devnull which must be one of
252 058b0118 2005-01-03 devnull .BR XAXIS ,
253 058b0118 2005-01-03 devnull .B YAXIS
255 058b0118 2005-01-03 devnull .BR ZAXIS .
257 058b0118 2005-01-03 devnull transforms by a rotation about an arbitrary axis, specified by
258 058b0118 2005-01-03 devnull .B Quaternion
261 058b0118 2005-01-03 devnull .I Scale
262 058b0118 2005-01-03 devnull scales the coordinate system by the given scale factors in the directions of the three axes.
263 058b0118 2005-01-03 devnull .IB Move
264 058b0118 2005-01-03 devnull translates by the given displacement in the three axial directions.
266 058b0118 2005-01-03 devnull .I Xform
267 058b0118 2005-01-03 devnull transforms the coordinate system by the given
268 058b0118 2005-01-03 devnull .BR Matrix .
269 058b0118 2005-01-03 devnull If the matrix's inverse is known
271 058b0118 2005-01-03 devnull .IR priori ,
273 058b0118 2005-01-03 devnull .I ixform
274 058b0118 2005-01-03 devnull will save the work of recomputing it.
276 058b0118 2005-01-03 devnull .I Persp
277 058b0118 2005-01-03 devnull does a perspective transformation.
278 058b0118 2005-01-03 devnull The transformation maps the frustum with apex at the origin,
279 058b0118 2005-01-03 devnull central axis down the positive
281 058b0118 2005-01-03 devnull axis, and apex angle
283 058b0118 2005-01-03 devnull and clipping planes
284 058b0118 2005-01-03 devnull .IR y = n
286 058b0118 2005-01-03 devnull .IR y = f
287 058b0118 2005-01-03 devnull into the double-unit cube.
288 058b0118 2005-01-03 devnull The plane
289 058b0118 2005-01-03 devnull .IR y = n
291 058b0118 2005-01-03 devnull .IR y '=-1,
292 058b0118 2005-01-03 devnull .IR y = f
294 058b0118 2005-01-03 devnull .IR y '=1.
297 058b0118 2005-01-03 devnull does a view-pointing transformation. The
299 058b0118 2005-01-03 devnull point is moved to the origin.
300 058b0118 2005-01-03 devnull The line through the
304 058b0118 2005-01-03 devnull points is aligned with the y axis,
305 058b0118 2005-01-03 devnull and the plane containing the
306 058b0118 2005-01-03 devnull .BR eye ,
310 058b0118 2005-01-03 devnull points is rotated into the
311 058b0118 2005-01-03 devnull .IR x - y
314 058b0118 2005-01-03 devnull .I Viewport
315 058b0118 2005-01-03 devnull maps the unit-cube window into the given screen viewport.
316 058b0118 2005-01-03 devnull The viewport rectangle
319 058b0118 2005-01-03 devnull .IB r .min
320 058b0118 2005-01-03 devnull at the top left-hand corner, and
321 058b0118 2005-01-03 devnull .IB r .max
322 058b0118 2005-01-03 devnull just outside the lower right-hand corner.
323 058b0118 2005-01-03 devnull Argument
324 058b0118 2005-01-03 devnull .I aspect
325 058b0118 2005-01-03 devnull is the aspect ratio
326 058b0118 2005-01-03 devnull .RI ( dx / dy )
327 058b0118 2005-01-03 devnull of the viewport's pixels (not of the whole viewport).
328 058b0118 2005-01-03 devnull The whole window is transformed to fit centered inside the viewport with equal
329 058b0118 2005-01-03 devnull slop on either top and bottom or left and right, depending on the viewport's
330 058b0118 2005-01-03 devnull aspect ratio.
331 058b0118 2005-01-03 devnull The window is viewed down the
333 058b0118 2005-01-03 devnull axis, with
335 058b0118 2005-01-03 devnull to the left and
337 058b0118 2005-01-03 devnull up. The viewport
340 058b0118 2005-01-03 devnull increasing to the right and
342 058b0118 2005-01-03 devnull increasing down. The window's
344 058b0118 2005-01-03 devnull coordinates are mapped, unchanged, into the viewport's
346 058b0118 2005-01-03 devnull coordinates.
347 058b0118 2005-01-03 devnull .SH SOURCE
348 c3674de4 2005-01-11 devnull .B \*9/src/libgeometry/matrix.c
349 058b0118 2005-01-03 devnull .SH "SEE ALSO
350 058b0118 2005-01-03 devnull .IR arith3 (3)