matrix 5.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350
  1. .TH MATRIX 2
  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 /sys/src/libgeometry/matrix.c
  349. .SH "SEE ALSO
  350. .IR arith3 (2)