matrix.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)