1threedkit(7)                  Svgalib User Manual                 threedkit(7)
2
3
4

NAME

6       threedkit - a set of functions for 3D support.
7
8

DESCRIPTION

10       The  3dkit consists mainly of the following triangle functions gl_stri‐
11       angle(3),  gl_swtriangle(3),  gl_triangle(3),  gl_trigetcolorlookup(3),
12       gl_trisetcolorlookup(3), gl_trisetdrawpoint(3), gl_wtriangle(3).
13
14       Beware,  these  functions are not a direct part of the svgalib library.
15       Instead their source is part of svgalib and can be found in the threeD‐
16       kit/  subdirectory of the original svgalib distribution. However, it is
17       not installed in the system by default, s.t. it is  unclear  where  you
18       can find it if your svgalib was installed by some linux distribution.
19
20       In  case  of  any such problem, simply get an svgalib distribution from
21       the net. You even don't need to install it. Just make in the threeDkit/
22       subdirectory.  As  of this writing, svgalib-1.2.12.tar.gz is the latest
23       version  and  can  be  retrieved  by  ftp   from   sunsite.unc.edu   at
24       /pub/Linux/libs/graphics  and tsx-11.mit.edu at /pub/linux/sources/libs
25       which will most probably be mirrored by a site close to you.
26
27       The functions are defined in the tri.o and triangl.o  files  (or  their
28       resp. sources) which you must link to your program.
29
30

EXPLANATION ON 3DKIT.C

32       This is main engine for 3D rendering.
33
34       Program flow:
35
36
37       1.     The  function  called  from  outside of 3dkit.c is TD_drawsolid.
38              This first calculates the rotation matrix from the camera  rota‐
39              tion  angles  (see  below  for more details).  It then allocates
40              memory for the temporary array for holding temporary  coords  in
41              subsequently  called functions.  It also sorts the surfaces from
42              furthest to closest; according to the  distance  of  the  centre
43              grid-point of each surface from the camera.
44
45              It  also  establishes  whether  ROTATE_OBJECT  option  is on and
46              zero's the camera position if so --- this is for displaying  the
47              object at the screen centre like in a 3D CAD package, as apposed
48              to virtual reality where the object  can  be  anywhere  and  the
49              actual camera position can move.
50
51              In the case of ROTATE_OBJECT being on, although the camera posi‐
52              tion is zero, some distance has to be placed between the  camera
53              and  the object (or else  it would appear to be infinitely large
54              on the screen). This is done using the variable s_cam  which  is
55              initialized to distance which is set by the calling application.
56              It then loops through each surface (ordering  them  in  the  way
57              they  were just sorted --- i.e. according to sortarray indexing)
58              and calls one of five graphic routines to write the  3D  surface
59              to the hardware.
60
61
62       2.     Assume  that  TD_drawsolid  then  calls TD_drawmesh.  Here, each
63              surface grid point is first  TD_translate'd  into  a  2D  screen
64              point  and  stored  in  the  temp  array.  There  are  obviously
65              w(idth)*h(eight) points in the grid.
66
67              Following, each line from the 2D temp  array  is  drawn  on  the
68              screen.   To  draw  the surface, the corner wishbone (two lines)
69              from each grid square is drawn while advancing  across  and  the
70              down.  After  completing the scan, the furthest two edges of the
71              surface must then be filled in, vis.:
72               _ _ _ _ _ _
73              |_|_|_|_|_|_
74              |_|_|_|_|_|_
75              |_|_|_|_|_|_
76              |_|_|_|_|_|_
77              |_|_|_|_|_|_
78              | | | | | |
79
80              To understand the object rotation, a knowledge of matrix  multi‐
81              plication is required. I once derived a camera rotation before I
82              learned matrix computation. It amounted to the same  thing,  but
83              was unnecessarily complicated to optimise.
84
85
86       3.     TD_translate  called from TD_drawmesh (and others) converts from
87              the 3D grid point coordinate to the 2D screen coordinate  using:
88              (a) the three camera position coordinates, (or the single camera
89              distance value, s_cam, if ROTATE_OBJECT is  set),  and  (b)  the
90              three camera rotation angles. However, the three camera rotation
91              angles have already been converted into a rotation  matrix  when
92              TD_calc_rotation_matrix was called by TD_draw_solid.
93
94              To  convert  from a 3D coordinate to a 2D screen coordinate, the
95              camera position (or more correctly, the position of  the  object
96              from  the  camera)  must  first  be added to each of the 3D grid
97              coordinates.  If the user has chosen to use 32  bit  values  for
98              the discription of the surface, then these must be right shifted
99              to the same size as the 16 bit case.
100
101              x, y and z now hold the 3D position of the  object  relative  to
102              the  camera  centre  (or in these terms, the centre of the video
103              screen RIGHT ON the screen). The vector [x y z] must now be mul‐
104              tiplied  by the rotation matrix. The xt value must also have the
105              camera distance, s_cam, added to it in case the ROTATE_CAMERA is
106              set  (in which case x_cam, y_cam and z_cam (the camera position)
107              will be zero and instead s_cam will have a value to provide  the
108              necessary  object-camera  distance).  A  test is also made as to
109              whether this value is zero or negative. In the case,  the  point
110              is  too  close to the camera, or behind the camera, and must not
111              be drawn.
112
113              After the multiplication, the resulting vector [xt  yt  zt]  has
114              been  rotated  to  be  aligned  with  screen.  The vector is now
115              adjusted for perspective by dividing the yt and zt values (hori‐
116              zontal  and  vertical  respectively)  by  the xt value (into the
117              screen). Division is done by muldiv64 because  the  intermediate
118              product  is  larger than 32 bits.  xscale and yscale are factors
119              that scale the image to size.  posx and posy is just the  centre
120              of the screen, or more precisely:
121
122              The exact position of the pinhole camera viewing the object.
123
124
125       4.     TD_calc_rotation_matrix  calculates the nine entries of the 3 by
126              3 matrix used in  TD_translate.   In  order  that  only  integer
127              arithmetic  is  performed,  these  values are stored and used as
128              integers. Since this matrix's entries are always between -1  and
129              +1,  they have to be integer left shifted to give them accuracy.
130              TD_MULCONSTANT scales them to sufficient bits of accuracy before
131              they are converted to integers.
132
133              This also means that results (of multiplications with them) have
134              to be scaled down by the same amount. This scaling  is  inherent
135              in  the final multiplication and division (muldiv64) done in the
136              TD_translate function, so an extra division is not consumed.
137
138              The rotation matrix effectively rotates the vector by the Euler‐
139              ian  angles  alpha, beta and gamma.  These angles represent suc‐
140              cessive rotations about each of the 3D axes. You can test  which
141              angles do what by looking at the calling application. Their pre‐
142              cise definitions are not all that important since  you  can  get
143              the  keyboard  to  do  the  right  thing with a little trial and
144              error.
145
146
147       Intrisics of drawing non-transparent surfaces...
148
149       to be continued ?!
150
151

SEE ALSO

153       vgagl(7),  svgalib(7),  gl_striangle(3),  gl_swtriangle(3),   gl_trian‐
154       gle(3),  gl_trigetcolorlookup(3),  gl_trisetcolorlookup(3),  gl_triset‐
155       drawpoint(3), gl_wtriangle(3), plane(6), wrapdemo(6).
156
157

AUTHOR

159       This manual page was edited  by  Michael  Weller  <eowmob@exp-math.uni-
160       essen.de>. The demos, the initial documentation and the whole threedkit
161       stuff was done by Paul Sheer <psheer@icon.co.za>.
162
163       Paper mail:
164              Paul Sheer
165              P O BOX 890507
166              Lyndhurst
167              Johannesburg 2106
168              South Africa
169
170       Donations (by check or postal  order)  will  be  appreciated  and  will
171       encourage  further  development  of  this  software.  However  this  is
172       strictly on a voluntary basis where this software falls under  the  GNU
173       LIBRARY GENERAL PUBLIC LICENSE.
174
175
176
177Svgalib (>= 1.2.11)               2 Aug 1997                      threedkit(7)
Impressum