Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
threedkit(7)		      Svgalib User Manual		  threedkit(7)

       threedkit - a set of functions for 3D support.

       The  3dkit consists mainly of the following triangle functions gl_stri-
       angle(3),  gl_swtriangle(3),  gl_triangle(3),  gl_trigetcolorlookup(3),
       gl_trisetcolorlookup(3),	gl_trisetdrawpoint(3), gl_wtriangle(3).

       Beware,	these  functions are not a direct part of the svgalib library.
       Instead their source is part of svgalib and can be found	in the threeD-
       kit/  subdirectory of the original svgalib distribution.	However, it is
       not installed in	the system by default, s.t. it is  unclear  where  you
       can find	it if your svgalib was installed by some linux distribution.

       In  case	 of  any such problem, simply get an svgalib distribution from
       the net.	You even don't need to install it. Just	make in	the threeDkit/
       subdirectory.  As  of this writing, svgalib-1.2.12.tar.gz is the	latest
       version	and  can  be  retrieved	 by  ftp   from   at
       /pub/Linux/libs/graphics	 and at /pub/linux/sources/libs
       which will most probably	be mirrored by a site close to you.

       The functions are defined in the	tri.o and triangl.o  files  (or	 their
       resp. sources) which you	must link to your program.

       This is main engine for 3D rendering.

       Program flow:

       1.     The  function  called  from  outside of 3dkit.c is TD_drawsolid.
	      This first calculates the	rotation matrix	from the camera	 rota-
	      tion  angles  (see  below	 for more details).  It	then allocates
	      memory for the temporary array for holding temporary  coords  in
	      subsequently  called functions.  It also sorts the surfaces from
	      furthest to closest; according to	the  distance  of  the	centre
	      grid-point of each surface from the camera.

	      It  also	establishes  whether  ROTATE_OBJECT  option  is	on and
	      zero's the camera	position if so --- this	is for displaying  the
	      object at	the screen centre like in a 3D CAD package, as apposed
	      to virtual reality where the object can be anywhere and the  ac-
	      tual camera position can move.

	      In the case of ROTATE_OBJECT being on, although the camera posi-
	      tion is zero, some distance has to be placed between the	camera
	      and  the object (or else	it would appear	to be infinitely large
	      on the screen). This is done using the variable s_cam  which  is
	      initialized to distance which is set by the calling application.
	      It then loops through each surface (ordering  them  in  the  way
	      they  were just sorted --- i.e. according	to sortarray indexing)
	      and calls	one of five graphic routines to	write the  3D  surface
	      to the hardware.

       2.     Assume  that  TD_drawsolid  then	calls TD_drawmesh.  Here, each
	      surface grid point is first  TD_translate'd  into	 a  2D	screen
	      point  and  stored  in  the  temp	 array.	 There	are  obviously
	      w(idth)*h(eight) points in the grid.

	      Following, each line from	the 2D temp  array  is	drawn  on  the
	      screen.	To  draw  the surface, the corner wishbone (two	lines)
	      from each	grid square is drawn while advancing  across  and  the
	      down.  After  completing the scan, the furthest two edges	of the
	      surface must then	be filled in, vis.:
	       _ _ _ _ _ _
	      |	| | | |	|

	      To understand the	object rotation, a knowledge of	matrix	multi-
	      plication	is required. I once derived a camera rotation before I
	      learned matrix computation. It amounted to the same  thing,  but
	      was unnecessarily	complicated to optimise.

       3.     TD_translate  called from	TD_drawmesh (and others) converts from
	      the 3D grid point	coordinate to the 2D screen coordinate	using:
	      (a) the three camera position coordinates, (or the single	camera
	      distance value, s_cam, if	ROTATE_OBJECT is  set),	 and  (b)  the
	      three camera rotation angles. However, the three camera rotation
	      angles have already been converted into a	rotation  matrix  when
	      TD_calc_rotation_matrix was called by TD_draw_solid.

	      To  convert  from	a 3D coordinate	to a 2D	screen coordinate, the
	      camera position (or more correctly, the position of  the	object
	      from  the	camera)	must first be added to each of the 3D grid co-
	      ordinates.  If the user has chosen to use	32 bit values for  the
	      discription  of the surface, then	these must be right shifted to
	      the same size as the 16 bit case.

	      x, y and z now hold the 3D position of the  object  relative  to
	      the  camera  centre  (or in these	terms, the centre of the video
	      screen RIGHT ON the screen). The vector [x y z] must now be mul-
	      tiplied  by the rotation matrix. The xt value must also have the
	      camera distance, s_cam, added to it in case the ROTATE_CAMERA is
	      set  (in which case x_cam, y_cam and z_cam (the camera position)
	      will be zero and instead s_cam will have a value to provide  the
	      necessary	 object-camera	distance).  A  test is also made as to
	      whether this value is zero or negative. In the case,  the	 point
	      is  too  close to	the camera, or behind the camera, and must not
	      be drawn.

	      After the	multiplication,	the resulting vector [xt  yt  zt]  has
	      been  rotated  to	 be aligned with screen. The vector is now ad-
	      justed for perspective by	dividing the yt	and zt	values	(hori-
	      zontal  and  vertical  respectively)  by	the xt value (into the
	      screen). Division	is done	by muldiv64 because  the  intermediate
	      product  is  larger than 32 bits.	 xscale	and yscale are factors
	      that scale the image to size.  posx and posy is just the	centre
	      of the screen, or	more precisely:

	      The exact	position of the	pinhole	camera viewing the object.

       4.     TD_calc_rotation_matrix  calculates the nine entries of the 3 by
	      3	matrix used in	TD_translate.	In  order  that	 only  integer
	      arithmetic is performed, these values are	stored and used	as in-
	      tegers. Since this matrix's entries are always  between  -1  and
	      +1,  they	have to	be integer left	shifted	to give	them accuracy.
	      TD_MULCONSTANT scales them to sufficient bits of accuracy	before
	      they are converted to integers.

	      This also	means that results (of multiplications with them) have
	      to be scaled down	by the same amount. This scaling  is  inherent
	      in  the final multiplication and division	(muldiv64) done	in the
	      TD_translate function, so	an extra division is not consumed.

	      The rotation matrix effectively rotates the vector by the	Euler-
	      ian  angles  alpha, beta and gamma.  These angles	represent suc-
	      cessive rotations	about each of the 3D axes. You can test	 which
	      angles do	what by	looking	at the calling application. Their pre-
	      cise definitions are not all that	important since	 you  can  get
	      the  keyboard  to	do the right thing with	a little trial and er-

       Intrisics of drawing non-transparent surfaces...

       to be continued ?!

       vgagl(7),  svgalib(7),  gl_striangle(3),	 gl_swtriangle(3),   gl_trian-
       gle(3),	gl_trigetcolorlookup(3),  gl_trisetcolorlookup(3),  gl_triset-
       drawpoint(3), gl_wtriangle(3), plane(6),	wrapdemo(6).

       This manual page	was edited by Michael Weller  <eowmob@exp-math.uni-es->.	 The  demos, the initial documentation and the whole threedkit
       stuff was done by Paul Sheer <>.

       Paper mail:
	      Paul Sheer
	      P	O BOX 890507
	      Johannesburg 2106
	      South Africa

       Donations (by check or postal order) will be appreciated	and  will  en-
       courage	further	development of this software. However this is strictly
       on a voluntary basis where this software	falls under  the  GNU  LIBRARY

Svgalib	(>= 1.2.11)		  2 Aug	1997			  threedkit(7)


Want to link to this manual page? Use this URL:

home | help