1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
|
<head>
<title>matrix(3) - Plan 9 from User Space</title>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
</head>
<body bgcolor=#ffffff>
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=10><td>
<tr><td width=20><td>
<tr><td width=20><td><b>MATRIX(3)</b><td align=right><b>MATRIX(3)</b>
<tr><td width=20><td colspan=2>
<br>
<p><font size=+1><b>NAME </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
ident, matmul, matmulr, determinant, adjoint, invertmat, xformpoint,
xformpointd, xformplane, pushmat, popmat, rot, qrot, scale, move,
xform, ixform, persp, look, viewport – Geometric transformations<br>
</table>
<p><font size=+1><b>SYNOPSIS </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>#include <draw.h>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>#include <geometry.h>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void ident(Matrix m)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void matmul(Matrix a, Matrix b)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void matmulr(Matrix a, Matrix b)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>double determinant(Matrix m)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void adjoint(Matrix m, Matrix madj)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>double invertmat(Matrix m, Matrix inv)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>Point3 xformpoint(Point3 p, Space *to, Space *from)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>Point3 xformpointd(Point3 p, Space *to, Space *from)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>Point3 xformplane(Point3 p, Space *to, Space *from)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>Space *pushmat(Space *t)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>Space *popmat(Space *t)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void rot(Space *t, double theta, int axis)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void qrot(Space *t, Quaternion q)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void scale(Space *t, double x, double y, double z)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void move(Space *t, double x, double y, double z)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void xform(Space *t, Matrix m)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void ixform(Space *t, Matrix m, Matrix inv)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>int persp(Space *t, double fov, double n, double f)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void look(Space *t, Point3 eye, Point3 look, Point3 up)
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
<tt><font size=+1>void viewport(Space *t, Rectangle r, double aspect)<br>
</font></tt>
</table>
<p><font size=+1><b>DESCRIPTION </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
These routines manipulate 3-space affine and projective transformations,
represented as 4×4 matrices, thus:<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>typedef double Matrix[4][4];<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
</table>
<i>Ident</i> stores an identity matrix in its argument. <i>Matmul</i> stores
<i>a×b</i> in <i>a</i>. <i>Matmulr</i> stores <i>b×a</i> in <i>b</i>. <i>Determinant</i> returns the determinant
of matrix <i>m</i>. <i>Adjoint</i> stores the adjoint (matrix of cofactors)
of <i>m</i> in <i>madj</i>. <i>Invertmat</i> stores the inverse of matrix <i>m</i> in <i>minv</i>,
returning <i>m</i>’s determinant. Should <i>m</i> be singular
(determinant zero), <i>invertmat</i> stores its adjoint in <i>minv</i>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The rest of the routines described here manipulate <i>Spaces</i> and
transform <i>Point3s</i>. A <i>Point3</i> is a point in three-space, represented
by its homogeneous coordinates:<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>typedef struct Point3 Point3;<br>
struct Point3{<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
double x, y, z, w;<br>
</table>
};<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
</table>
The homogeneous coordinates (<i>x</i>, <i>y</i>, <i>z</i>, <i>w</i>) represent the Euclidean
point (<i>x</i>/<i>w</i>, <i>y</i>/<i>w</i>, <i>z</i>/<i>w</i>) if <i>w</i>!=0, and a “point at infinity” if <i>w</i>=0.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
A <i>Space</i> is just a data structure describing a coordinate system:<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>typedef struct Space Space;<br>
struct Space{<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
Matrix t;<br>
Matrix tinv;<br>
Space *next;<br>
</table>
};<br>
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
</font></tt>
</table>
It contains a pair of transformation matrices and a pointer to
the <i>Space</i>’s parent. The matrices transform points to and from
the “root coordinate system,” which is represented by a null <i>Space</i>
pointer.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Pushmat</i> creates a new <i>Space</i>. Its argument is a pointer to the
parent space. Its result is a newly allocated copy of the parent,
but with its <tt><font size=+1>next</font></tt> pointer pointing at the parent. <i>Popmat</i> discards
the <tt><font size=+1>Space</font></tt> that is its argument, returning a pointer to the stack.
Nominally, these two functions define a stack of
transformations, but <tt><font size=+1>pushmat</font></tt> can be called multiple times on the
same <tt><font size=+1>Space</font></tt> multiple times, creating a transformation tree.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Xformpoint</i> and <i>Xformpointd</i> both transform points from the <tt><font size=+1>Space</font></tt>
pointed to by <i>from</i> to the space pointed to by <i>to</i>. Either pointer
may be null, indicating the root coordinate system. The difference
between the two functions is that <tt><font size=+1>xformpointd</font></tt> divides <i>x</i>, <i>y</i>, <i>z</i>,
and <i>w</i> by <i>w</i>, if <i>w</i>!=0, making (<i>x</i>, <i>y</i>, <i>z</i>) the Euclidean
coordinates of the point.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Xformplane</i> transforms planes or normal vectors. A plane is specified
by the coefficients (<i>a</i>, <i>b</i>, <i>c</i>, <i>d</i>) of its implicit equation <i>ax+by+cz+d</i>=0.
Since this representation is dual to the homogeneous representation
of points, <tt><font size=+1>libgeometry</font></tt> represents planes by <tt><font size=+1>Point3</font></tt> structures,
with (<i>a</i>, <i>b</i>, <i>c</i>, <i>d</i>) stored in (<i>x</i>, <i>y</i>, <i>z</i>, <i>w</i>).
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
The remaining functions transform the coordinate system represented
by a <tt><font size=+1>Space</font></tt>. Their <tt><font size=+1>Space *</font></tt> argument must be non-null -- you can’t
modify the root <tt><font size=+1>Space</font></tt>. <i>Rot</i> rotates by angle <i>theta</i> (in radians)
about the given <i>axis</i>, which must be one of <tt><font size=+1>XAXIS</font></tt>, <tt><font size=+1>YAXIS</font></tt> or <tt><font size=+1>ZAXIS</font></tt>.
<i>Qrot</i> transforms by a rotation about an
arbitrary axis, specified by <tt><font size=+1>Quaternion</font></tt> <i>q</i>.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Scale</i> scales the coordinate system by the given scale factors
in the directions of the three axes. <i>Move</i> translates by the given
displacement in the three axial directions.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Xform</i> transforms the coordinate system by the given <tt><font size=+1>Matrix</font></tt>. If
the matrix’s inverse is known <i>a priori</i>, calling <i>ixform</i> will save
the work of recomputing it.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Persp</i> does a perspective transformation. The transformation maps
the frustum with apex at the origin, central axis down the positive
<i>y</i> axis, and apex angle <i>fov</i> and clipping planes <i>y</i>=<i>n</i> and <i>y</i>=<i>f</i> into
the double-unit cube. The plane <i>y</i>=<i>n</i> maps to <i>y</i>’=-1, <i>y</i>=<i>f</i> maps to
<i>y</i>’=1.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Look</i> does a view-pointing transformation. The <tt><font size=+1>eye</font></tt> point is moved
to the origin. The line through the <i>eye</i> and <i>look</i> points is aligned
with the y axis, and the plane containing the <tt><font size=+1>eye</font></tt>, <tt><font size=+1>look</font></tt> and <tt><font size=+1>up</font></tt>
points is rotated into the <i>x</i>-<i>y</i> plane.
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
<i>Viewport</i> maps the unit-cube window into the given screen viewport.
The viewport rectangle <i>r</i> has <i>r</i><tt><font size=+1>.min</font></tt> at the top left-hand corner,
and <i>r</i><tt><font size=+1>.max</font></tt> just outside the lower right-hand corner. Argument <i>aspect</i>
is the aspect ratio (<i>dx</i>/<i>dy</i>) of the viewport’s pixels (not of the
whole viewport). The whole window is transformed
to fit centered inside the viewport with equal slop on either
top and bottom or left and right, depending on the viewport’s
aspect ratio. The window is viewed down the <i>y</i> axis, with <i>x</i> to
the left and <i>z</i> up. The viewport has <i>x</i> increasing to the right
and <i>y</i> increasing down. The window’s <i>y</i> coordinates are mapped,
unchanged, into the viewport’s <i>z</i> coordinates.<br>
</table>
<p><font size=+1><b>SOURCE </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<tt><font size=+1>/usr/local/plan9/src/libgeometry/matrix.c<br>
</font></tt>
</table>
<p><font size=+1><b>SEE ALSO </b></font><br>
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
<a href="../man3/arith3.html"><i>arith3</i>(3)</a><br>
</table>
<td width=20>
<tr height=20><td>
</table>
<!-- TRAILER -->
<table border=0 cellpadding=0 cellspacing=0 width=100%>
<tr height=15><td width=10><td><td width=10>
<tr><td><td>
<center>
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
</center>
</table>
<!-- TRAILER -->
</body></html>
|