1threedkit(7) Svgalib User Manual threedkit(7)
2
6 threedkit - a set of functions for 3D support.
7
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 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 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 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
32 This is main engine for 3D rendering.
33 Program flow:
35 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 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 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 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 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 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 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 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 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 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 The exact position of the pinhole camera viewing the object.
123 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 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 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 Intrisics of drawing non-transparent surfaces...
148 to be continued ?!
150
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
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 Paper mail:
164 Paul Sheer
165 P O BOX 890507
166 Lyndhurst
167 Johannesburg 2106
168 South Africa
169 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.
174Svgalib (>= 1.2.11) 2 Aug 1997 threedkit(7)