1 058b0118 2005-01-03 devnull .TH MATRIX 3
  2 058b0118 2005-01-03 devnull .SH NAME
  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
  5 058b0118 2005-01-03 devnull .PP
  6 058b0118 2005-01-03 devnull .B
  7 058b0118 2005-01-03 devnull #include <draw.h>
  8 058b0118 2005-01-03 devnull .PP
  9 058b0118 2005-01-03 devnull .B
 10 058b0118 2005-01-03 devnull #include <geometry.h>
 11 058b0118 2005-01-03 devnull .PP
 12 058b0118 2005-01-03 devnull .B
 13 058b0118 2005-01-03 devnull void ident(Matrix m)
 14 058b0118 2005-01-03 devnull .PP
 15 058b0118 2005-01-03 devnull .B
 16 058b0118 2005-01-03 devnull void matmul(Matrix a, Matrix b)
 17 058b0118 2005-01-03 devnull .PP
 18 058b0118 2005-01-03 devnull .B
 19 058b0118 2005-01-03 devnull void matmulr(Matrix a, Matrix b)
 20 058b0118 2005-01-03 devnull .PP
 21 058b0118 2005-01-03 devnull .B
 22 058b0118 2005-01-03 devnull double determinant(Matrix m)
 23 058b0118 2005-01-03 devnull .PP
 24 058b0118 2005-01-03 devnull .B
 25 058b0118 2005-01-03 devnull void adjoint(Matrix m, Matrix madj)
 26 058b0118 2005-01-03 devnull .PP
 27 058b0118 2005-01-03 devnull .B
 28 058b0118 2005-01-03 devnull double invertmat(Matrix m, Matrix inv)
 29 058b0118 2005-01-03 devnull .PP
 30 058b0118 2005-01-03 devnull .B
 31 058b0118 2005-01-03 devnull Point3 xformpoint(Point3 p, Space *to, Space *from)
 32 058b0118 2005-01-03 devnull .PP
 33 058b0118 2005-01-03 devnull .B
 34 058b0118 2005-01-03 devnull Point3 xformpointd(Point3 p, Space *to, Space *from)
 35 058b0118 2005-01-03 devnull .PP
 36 058b0118 2005-01-03 devnull .B
 37 058b0118 2005-01-03 devnull Point3 xformplane(Point3 p, Space *to, Space *from)
 38 058b0118 2005-01-03 devnull .PP
 39 058b0118 2005-01-03 devnull .B
 40 058b0118 2005-01-03 devnull Space *pushmat(Space *t)
 41 058b0118 2005-01-03 devnull .PP
 42 058b0118 2005-01-03 devnull .B
 43 058b0118 2005-01-03 devnull Space *popmat(Space *t)
 44 058b0118 2005-01-03 devnull .PP
 45 058b0118 2005-01-03 devnull .B
 46 058b0118 2005-01-03 devnull void rot(Space *t, double theta, int axis)
 47 058b0118 2005-01-03 devnull .PP
 48 058b0118 2005-01-03 devnull .B
 49 058b0118 2005-01-03 devnull void qrot(Space *t, Quaternion q)
 50 058b0118 2005-01-03 devnull .PP
 51 058b0118 2005-01-03 devnull .B
 52 058b0118 2005-01-03 devnull void scale(Space *t, double x, double y, double z)
 53 058b0118 2005-01-03 devnull .PP
 54 058b0118 2005-01-03 devnull .B
 55 058b0118 2005-01-03 devnull void move(Space *t, double x, double y, double z)
 56 058b0118 2005-01-03 devnull .PP
 57 058b0118 2005-01-03 devnull .B
 58 058b0118 2005-01-03 devnull void xform(Space *t, Matrix m)
 59 058b0118 2005-01-03 devnull .PP
 60 058b0118 2005-01-03 devnull .B
 61 058b0118 2005-01-03 devnull void ixform(Space *t, Matrix m, Matrix inv)
 62 058b0118 2005-01-03 devnull .PP
 63 058b0118 2005-01-03 devnull .B
 64 058b0118 2005-01-03 devnull int persp(Space *t, double fov, double n, double f)
 65 058b0118 2005-01-03 devnull .PP
 66 058b0118 2005-01-03 devnull .B
 67 058b0118 2005-01-03 devnull void look(Space *t, Point3 eye, Point3 look, Point3 up)
 68 058b0118 2005-01-03 devnull .PP
 69 058b0118 2005-01-03 devnull .B
 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:
 74 058b0118 2005-01-03 devnull .IP
 75 058b0118 2005-01-03 devnull .EX
 76 058b0118 2005-01-03 devnull .ta 6n
 77 058b0118 2005-01-03 devnull typedef double Matrix[4][4];
 78 058b0118 2005-01-03 devnull .EE
 79 058b0118 2005-01-03 devnull .PP
 80 058b0118 2005-01-03 devnull .I Ident
 81 058b0118 2005-01-03 devnull stores an identity matrix in its argument.
 82 058b0118 2005-01-03 devnull .I Matmul
 83 058b0118 2005-01-03 devnull stores
 84 058b0118 2005-01-03 devnull .I a\(mub
 85 058b0118 2005-01-03 devnull in
 86 058b0118 2005-01-03 devnull .IR a .
 87 058b0118 2005-01-03 devnull .I Matmulr
 88 058b0118 2005-01-03 devnull stores
 89 058b0118 2005-01-03 devnull .I b\(mua
 90 058b0118 2005-01-03 devnull in
 91 058b0118 2005-01-03 devnull .IR b .
 92 058b0118 2005-01-03 devnull .I Determinant
 93 058b0118 2005-01-03 devnull returns the determinant of matrix
 94 058b0118 2005-01-03 devnull .IR m .
 95 058b0118 2005-01-03 devnull .I Adjoint
 96 058b0118 2005-01-03 devnull stores the adjoint (matrix of cofactors) of
 97 058b0118 2005-01-03 devnull .I m
 98 058b0118 2005-01-03 devnull in
 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
102 058b0118 2005-01-03 devnull .I m
103 058b0118 2005-01-03 devnull in
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.
108 058b0118 2005-01-03 devnull Should
109 058b0118 2005-01-03 devnull .I m
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 .
115 058b0118 2005-01-03 devnull .PP
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 .
121 058b0118 2005-01-03 devnull A
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:
125 058b0118 2005-01-03 devnull .IP
126 058b0118 2005-01-03 devnull .EX
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;
130 058b0118 2005-01-03 devnull };
131 058b0118 2005-01-03 devnull .EE
132 058b0118 2005-01-03 devnull .PP
133 058b0118 2005-01-03 devnull The homogeneous coordinates
134 058b0118 2005-01-03 devnull .RI ( x ,
135 058b0118 2005-01-03 devnull .IR y ,
136 058b0118 2005-01-03 devnull .IR z ,
137 058b0118 2005-01-03 devnull .IR w )
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 )
142 058b0118 2005-01-03 devnull if
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.
146 058b0118 2005-01-03 devnull .PP
147 058b0118 2005-01-03 devnull A
148 058b0118 2005-01-03 devnull .I Space
149 058b0118 2005-01-03 devnull is just a data structure describing a coordinate system:
150 058b0118 2005-01-03 devnull .IP
151 058b0118 2005-01-03 devnull .EX
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;
157 058b0118 2005-01-03 devnull };
158 058b0118 2005-01-03 devnull .EE
159 058b0118 2005-01-03 devnull .PP
160 058b0118 2005-01-03 devnull It contains a pair of transformation matrices and a pointer
161 058b0118 2005-01-03 devnull to the
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.
167 058b0118 2005-01-03 devnull .PP
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
173 058b0118 2005-01-03 devnull .B next
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,
180 058b0118 2005-01-03 devnull but
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.
186 058b0118 2005-01-03 devnull .PP
187 058b0118 2005-01-03 devnull .I Xformpoint
188 058b0118 2005-01-03 devnull and
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
193 058b0118 2005-01-03 devnull .I from
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
199 058b0118 2005-01-03 devnull divides
200 058b0118 2005-01-03 devnull .IR x ,
201 058b0118 2005-01-03 devnull .IR y ,
202 058b0118 2005-01-03 devnull .IR z ,
203 058b0118 2005-01-03 devnull and
204 058b0118 2005-01-03 devnull .I w
205 058b0118 2005-01-03 devnull by
206 058b0118 2005-01-03 devnull .IR w ,
207 058b0118 2005-01-03 devnull if
208 058b0118 2005-01-03 devnull .IR w ≠0,
209 058b0118 2005-01-03 devnull making
210 058b0118 2005-01-03 devnull .RI ( x ,
211 058b0118 2005-01-03 devnull .IR y ,
212 058b0118 2005-01-03 devnull .IR z )
213 058b0118 2005-01-03 devnull the Euclidean coordinates of the point.
214 058b0118 2005-01-03 devnull .PP
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 ,
219 058b0118 2005-01-03 devnull .IR b ,
220 058b0118 2005-01-03 devnull .IR c ,
221 058b0118 2005-01-03 devnull .IR d )
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 ,
230 058b0118 2005-01-03 devnull .IR b ,
231 058b0118 2005-01-03 devnull .IR c ,
232 058b0118 2005-01-03 devnull .IR d )
233 058b0118 2005-01-03 devnull stored in
234 058b0118 2005-01-03 devnull .RI ( x ,
235 058b0118 2005-01-03 devnull .IR y ,
236 058b0118 2005-01-03 devnull .IR z ,
237 058b0118 2005-01-03 devnull .IR w ).
238 058b0118 2005-01-03 devnull .PP
239 058b0118 2005-01-03 devnull The remaining functions transform the coordinate system represented
240 058b0118 2005-01-03 devnull by a
241 058b0118 2005-01-03 devnull .BR Space .
242 058b0118 2005-01-03 devnull Their
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 .
246 058b0118 2005-01-03 devnull .I Rot
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
254 058b0118 2005-01-03 devnull or
255 058b0118 2005-01-03 devnull .BR ZAXIS .
256 058b0118 2005-01-03 devnull .I Qrot
257 058b0118 2005-01-03 devnull transforms by a rotation about an arbitrary axis, specified by
258 058b0118 2005-01-03 devnull .B Quaternion
259 058b0118 2005-01-03 devnull .IR q .
260 058b0118 2005-01-03 devnull .PP
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.
265 058b0118 2005-01-03 devnull .PP
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
270 058b0118 2005-01-03 devnull .I a
271 058b0118 2005-01-03 devnull .IR priori ,
272 058b0118 2005-01-03 devnull calling
273 058b0118 2005-01-03 devnull .I ixform
274 058b0118 2005-01-03 devnull will save the work of recomputing it.
275 058b0118 2005-01-03 devnull .PP
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
280 058b0118 2005-01-03 devnull .I y
281 058b0118 2005-01-03 devnull axis, and apex angle
282 058b0118 2005-01-03 devnull .I fov
283 058b0118 2005-01-03 devnull and clipping planes
284 058b0118 2005-01-03 devnull .IR y = n
285 058b0118 2005-01-03 devnull and
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
290 058b0118 2005-01-03 devnull maps to
291 058b0118 2005-01-03 devnull .IR y '=-1,
292 058b0118 2005-01-03 devnull .IR y = f
293 058b0118 2005-01-03 devnull maps to
294 058b0118 2005-01-03 devnull .IR y '=1.
295 058b0118 2005-01-03 devnull .PP
296 058b0118 2005-01-03 devnull .I Look
297 058b0118 2005-01-03 devnull does a view-pointing transformation.  The
298 058b0118 2005-01-03 devnull .B eye
299 058b0118 2005-01-03 devnull point is moved to the origin.
300 058b0118 2005-01-03 devnull The line through the
301 058b0118 2005-01-03 devnull .I eye
302 058b0118 2005-01-03 devnull and
303 058b0118 2005-01-03 devnull .I look
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 ,
307 058b0118 2005-01-03 devnull .B look
308 058b0118 2005-01-03 devnull and
309 058b0118 2005-01-03 devnull .B up
310 058b0118 2005-01-03 devnull points is rotated into the
311 058b0118 2005-01-03 devnull .IR x - y
312 058b0118 2005-01-03 devnull plane.
313 058b0118 2005-01-03 devnull .PP
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
317 058b0118 2005-01-03 devnull .I r
318 058b0118 2005-01-03 devnull has
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
332 058b0118 2005-01-03 devnull .I y
333 058b0118 2005-01-03 devnull axis, with
334 058b0118 2005-01-03 devnull .I x
335 058b0118 2005-01-03 devnull to the left and
336 058b0118 2005-01-03 devnull .I z
337 058b0118 2005-01-03 devnull up.  The viewport
338 058b0118 2005-01-03 devnull has
339 058b0118 2005-01-03 devnull .I x
340 058b0118 2005-01-03 devnull increasing to the right and
341 058b0118 2005-01-03 devnull .I y
342 058b0118 2005-01-03 devnull increasing down.  The window's
343 058b0118 2005-01-03 devnull .I y
344 058b0118 2005-01-03 devnull coordinates are mapped, unchanged, into the viewport's
345 058b0118 2005-01-03 devnull .I z
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 d32deab1 2020-08-16 rsc .MR arith3 (3)