tmatrix.3 - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
tmatrix.3 (6089B)
---
1 .TH MATRIX 3
2 .SH NAME
3 ident, matmul, matmulr, determinant, adjoint, invertmat, xformpoint, xformpointd, xformplane, pushmat, popmat, rot, qrot, scale, move, xform, ixform, persp, look, viewport \- Geometric transformations
4 .SH SYNOPSIS
5 .PP
6 .B
7 #include <draw.h>
8 .PP
9 .B
10 #include <geometry.h>
11 .PP
12 .B
13 void ident(Matrix m)
14 .PP
15 .B
16 void matmul(Matrix a, Matrix b)
17 .PP
18 .B
19 void matmulr(Matrix a, Matrix b)
20 .PP
21 .B
22 double determinant(Matrix m)
23 .PP
24 .B
25 void adjoint(Matrix m, Matrix madj)
26 .PP
27 .B
28 double invertmat(Matrix m, Matrix inv)
29 .PP
30 .B
31 Point3 xformpoint(Point3 p, Space *to, Space *from)
32 .PP
33 .B
34 Point3 xformpointd(Point3 p, Space *to, Space *from)
35 .PP
36 .B
37 Point3 xformplane(Point3 p, Space *to, Space *from)
38 .PP
39 .B
40 Space *pushmat(Space *t)
41 .PP
42 .B
43 Space *popmat(Space *t)
44 .PP
45 .B
46 void rot(Space *t, double theta, int axis)
47 .PP
48 .B
49 void qrot(Space *t, Quaternion q)
50 .PP
51 .B
52 void scale(Space *t, double x, double y, double z)
53 .PP
54 .B
55 void move(Space *t, double x, double y, double z)
56 .PP
57 .B
58 void xform(Space *t, Matrix m)
59 .PP
60 .B
61 void ixform(Space *t, Matrix m, Matrix inv)
62 .PP
63 .B
64 int persp(Space *t, double fov, double n, double f)
65 .PP
66 .B
67 void look(Space *t, Point3 eye, Point3 look, Point3 up)
68 .PP
69 .B
70 void viewport(Space *t, Rectangle r, double aspect)
71 .SH DESCRIPTION
72 These routines manipulate 3-space affine and projective transformations,
73 represented as 4\(mu4 matrices, thus:
74 .IP
75 .EX
76 .ta 6n
77 typedef double Matrix[4][4];
78 .EE
79 .PP
80 .I Ident
81 stores an identity matrix in its argument.
82 .I Matmul
83 stores
84 .I a\(mub
85 in
86 .IR a .
87 .I Matmulr
88 stores
89 .I b\(mua
90 in
91 .IR b .
92 .I Determinant
93 returns the determinant of matrix
94 .IR m .
95 .I Adjoint
96 stores the adjoint (matrix of cofactors) of
97 .I m
98 in
99 .IR madj .
100 .I Invertmat
101 stores the inverse of matrix
102 .I m
103 in
104 .IR minv ,
105 returning
106 .IR m 's
107 determinant.
108 Should
109 .I m
110 be singular (determinant zero),
111 .I invertmat
112 stores its
113 adjoint in
114 .IR minv .
115 .PP
116 The rest of the routines described here
117 manipulate
118 .I Spaces
119 and transform
120 .IR Point3s .
121 A
122 .I Point3
123 is a point in three-space, represented by its
124 homogeneous coordinates:
125 .IP
126 .EX
127 typedef struct Point3 Point3;
128 struct Point3{
129 double x, y, z, w;
130 };
131 .EE
132 .PP
133 The homogeneous coordinates
134 .RI ( x ,
135 .IR y ,
136 .IR z ,
137 .IR w )
138 represent the Euclidean point
139 .RI ( x / w ,
140 .IR y / w ,
141 .IR z / w )
142 if
143 .IR w ≠0,
144 and a ``point at infinity'' if
145 .IR w =0.
146 .PP
147 A
148 .I Space
149 is just a data structure describing a coordinate system:
150 .IP
151 .EX
152 typedef struct Space Space;
153 struct Space{
154 Matrix t;
155 Matrix tinv;
156 Space *next;
157 };
158 .EE
159 .PP
160 It contains a pair of transformation matrices and a pointer
161 to the
162 .IR Space 's
163 parent. The matrices transform points to and from the ``root
164 coordinate system,'' which is represented by a null
165 .I Space
166 pointer.
167 .PP
168 .I Pushmat
169 creates a new
170 .IR Space .
171 Its argument is a pointer to the parent space. Its result
172 is a newly allocated copy of the parent, but with its
173 .B next
174 pointer pointing at the parent.
175 .I Popmat
176 discards the
177 .B Space
178 that is its argument, returning a pointer to the stack.
179 Nominally, these two functions define a stack of transformations,
180 but
181 .B pushmat
182 can be called multiple times
183 on the same
184 .B Space
185 multiple times, creating a transformation tree.
186 .PP
187 .I Xformpoint
188 and
189 .I Xformpointd
190 both transform points from the
191 .B Space
192 pointed to by
193 .I from
194 to the space pointed to by
195 .IR to .
196 Either pointer may be null, indicating the root coordinate system.
197 The difference between the two functions is that
198 .B xformpointd
199 divides
200 .IR x ,
201 .IR y ,
202 .IR z ,
203 and
204 .I w
205 by
206 .IR w ,
207 if
208 .IR w ≠0,
209 making
210 .RI ( x ,
211 .IR y ,
212 .IR z )
213 the Euclidean coordinates of the point.
214 .PP
215 .I Xformplane
216 transforms planes or normal vectors. A plane is specified by the
217 coefficients
218 .RI ( a ,
219 .IR b ,
220 .IR c ,
221 .IR d )
222 of its implicit equation
223 .IR ax+by+cz+d =0.
224 Since this representation is dual to the homogeneous representation of points,
225 .B libgeometry
226 represents planes by
227 .B Point3
228 structures, with
229 .RI ( a ,
230 .IR b ,
231 .IR c ,
232 .IR d )
233 stored in
234 .RI ( x ,
235 .IR y ,
236 .IR z ,
237 .IR w ).
238 .PP
239 The remaining functions transform the coordinate system represented
240 by a
241 .BR Space .
242 Their
243 .B Space *
244 argument must be non-null \(em you can't modify the root
245 .BR Space .
246 .I Rot
247 rotates by angle
248 .I theta
249 (in radians) about the given
250 .IR axis ,
251 which must be one of
252 .BR XAXIS ,
253 .B YAXIS
254 or
255 .BR ZAXIS .
256 .I Qrot
257 transforms by a rotation about an arbitrary axis, specified by
258 .B Quaternion
259 .IR q .
260 .PP
261 .I Scale
262 scales the coordinate system by the given scale factors in the directions of the three axes.
263 .IB Move
264 translates by the given displacement in the three axial directions.
265 .PP
266 .I Xform
267 transforms the coordinate system by the given
268 .BR Matrix .
269 If the matrix's inverse is known
270 .I a
271 .IR priori ,
272 calling
273 .I ixform
274 will save the work of recomputing it.
275 .PP
276 .I Persp
277 does a perspective transformation.
278 The transformation maps the frustum with apex at the origin,
279 central axis down the positive
280 .I y
281 axis, and apex angle
282 .I fov
283 and clipping planes
284 .IR y = n
285 and
286 .IR y = f
287 into the double-unit cube.
288 The plane
289 .IR y = n
290 maps to
291 .IR y '=-1,
292 .IR y = f
293 maps to
294 .IR y '=1.
295 .PP
296 .I Look
297 does a view-pointing transformation. The
298 .B eye
299 point is moved to the origin.
300 The line through the
301 .I eye
302 and
303 .I look
304 points is aligned with the y axis,
305 and the plane containing the
306 .BR eye ,
307 .B look
308 and
309 .B up
310 points is rotated into the
311 .IR x - y
312 plane.
313 .PP
314 .I Viewport
315 maps the unit-cube window into the given screen viewport.
316 The viewport rectangle
317 .I r
318 has
319 .IB r .min
320 at the top left-hand corner, and
321 .IB r .max
322 just outside the lower right-hand corner.
323 Argument
324 .I aspect
325 is the aspect ratio
326 .RI ( dx / dy )
327 of the viewport's pixels (not of the whole viewport).
328 The whole window is transformed to fit centered inside the viewport with equal
329 slop on either top and bottom or left and right, depending on the viewport's
330 aspect ratio.
331 The window is viewed down the
332 .I y
333 axis, with
334 .I x
335 to the left and
336 .I z
337 up. The viewport
338 has
339 .I x
340 increasing to the right and
341 .I y
342 increasing down. The window's
343 .I y
344 coordinates are mapped, unchanged, into the viewport's
345 .I z
346 coordinates.
347 .SH SOURCE
348 .B \*9/src/libgeometry/matrix.c
349 .SH "SEE ALSO
350 .MR arith3 (3)