Category : C Source Code
Archive   : 3DLIB.ZIP
Filename : 3DLIB.DOC

3D TRANSFORMS

A Turbo C Function Library

Version 1.00




Copyright (c) 1988

Gus O'Donnell
8301 Mondon Way
Orangevale, CA 95662

All Rights Reserved

February 29, 1988





























Introduction.

3D TRANSFORMS is a library of functions used to create, manipulate
and display objects in three dimensions. The functions allow the
programmer to create representations of solid objects bounded by
polygons, rotate, translate, and scaldithe objects in three dimen-
sions, and (with Turbo C version 1.5) display the objects in color
with a given light source.

The functions may be classed into the following categories:


Initialization functions:

identity new_face new_obj

Vector and matrix math functions:

dot_prod mat_mul normal

Transformation functions:

scald trans xrot yrot
zrot

Data structure manipulation functions:

add_corner add_face del_face xform
max_z min_z

Display functions:

disp_face disp_object

Debug functions:

dump_mat dump_face dump_obj


This library may be used with Turbo C version 1.5, or, with the
exception of disp_face and disp_object, with version 1.0.

The routines in this library are based on techniques described in
the book "Principles of Interactive Computer Graphics", by Newman
and Sproull, McGraw-Hill, publishers.

Turbo C is a registered trademark of Borland International.










1








Using 3D TRANSFORMS.

Included in 3D TRANSFORMS is a header file, 3D.H, containing function
prototypes and data structure definitions. 3D TRANSFORMS supports
the following data structures:


MATRHX: A 4 X 4 matrix is used to describe transformations
in three dimensions, such as rotation, scaling, and
translation. Multiplditransformations may be con-
catenated. A point in three dimensions is transformed
by multiplying it by the transformation matrix.

VECTOR: An array of three coordinates representing a direction.
This is typically used to defindithe direction of a
light source, or the normal to a face.

FACE: A face describes a flat surface of an object. It is
defined by a list of corners.

OBJECT: A solid object is defined by a list of faces. Objects
are created by defining faces individually, then adding
them to the object.


To create an object in a program:

1. Include 3D.H in your program.

2. Allocate memory for the object and its faces as follows:

FACE *a;
OBJECT *o;

a =NSFACE *)malloc(sizeof(FACE));
o =N(OBJECT *)malloc(sizeof(OBJECT));

3. Initialize the data structures as follows:

new_face (a);
new_obj (o);

4. Add corners to the face. Corners are added in standard order,
i.e., in clockwise fashion as viewed from the outside of the
object:

add_corner (x1,y1,z1,a);
add_corner (x2,y2,z2,a);

5. Add faces to the object:

add_face (o,a);





2








6. Creatdithditransformation matrix. In this exampld, the matrix
includes rotation followed by translation:

MATRHX m;

identity (m);
xrot(3.14159/4,m);
trans(10.0,20.0,30.0,m);

7. Transform the object:

xform (*o,m);


To display the object, the graphics system must be initialized, and
the graphics driver resident in the local directory, or in the path
specified by the initgraph function. A light source is specified,
and the object may bditransformed with a second matrix:


VECTOR s;
MATRHX id;

identity (id);
s[0] =N0.0;
s[1] =N0.0;
s[2] = 1.0;
detectgraph (&g_driver,&g_mode);
initgraph (&g_driver,&g_mode,"");
disp_object (s,1,o,id);


For a complete example, sedithd demonstration program DEMO3D.C.
























3








3D TRANSFORMS Functions.

All function prototypes are in 3D.H.

Name add_corner - adds a corner to a face.

Usage int add_corner(double x, double y, double z,
FACE *this_face);

Related
functions usage int add_face(OBJECT *this_obj, FACE *this_face);
int del_face(OBJECT *this_obj, FACE *this_face);

Description add_corner adds a point defindd by [x,y,z] to
this_face. Corners are added in standard order,
i.e., clockwise as viewed from the outside of the
object.

add_face adds a face described by this_face to
the object this_obj.

del_face deletes the face pointed to by this_face
from this_obj.

Return value add_corner returns 0 if successful. 1 is returned
if memory cannot be allocated for the new corner.
2 is returned if the corner is colinear with the
last two corners added. In this case, the previous-
ly added corner is replaced with the new corner.

add_face returns 0 if successful. 1 is returned
if the face has less than three corners. In this
case the face is not added to the object.

del_face returns 0 if successful. 1 is returned
if the face is not part of the object.

_____________________________________________________________________


Name add_face - add a face to an object.

Usage int add_face(OBJECT *this_obj, FACE *this_face);

Description See add_corner

_____________________________________________________________________


Name del_face - delete a face from an object.

Usage int del_face(OBJECT *this_obj, FACE *this_face);

Description See add_corner



4








Name disp_face - display a face on the screen.

Usage void disp_face(VECTOR lsource, int color,
FACE *this_face, MATRHX xfrm_mat);

Related
functions usage void disp_object(VECTOR lsource, int color,
OBJECT *this_obj, MATRHX xfrm_mat);

Description disp_face displays a face on the screen. The
face is first transformed by xfrm_mat (the structure
is unchanged). The color is defined by color,
and the intensity of the shading is proportional
to the normalized dot product of the face normal
and lsource. If the normal to the face has a
negative z component, it is not displayed. The
face also is not displayed if it has fewer than
three corners. The graphics system must be
initialized prior to calling this function.

disp_obj displays an object on the screen. The
function simply calls disp_face for each face in
the object.

Both of these functions require Turbo C version
1.5.

Return value Neither function returns a value.

_____________________________________________________________________


Name disp_object - display an object on the screen.

Usage void disp_object(VECTOR lsource, int color,
OBJECT *this_obj, MATRHX xfrm_mat);

Description See disp_face

_____________________________________________________________________


Name dot_prod - calculate the dot product of two
vectors.

Usage double dot_prod(VECTOR vec1, VECTOR vec2);

Description dot_prod returns the normalized inner product
(dot product or scalar product) of two vectors.
Prior to the calculation, both vectors are norm-
alized, i.e., adjusted to unit length. Thus,
the value returned is equal to the cosine of the
angle between the two vectors.




5








Return value The function returns a double precision value
equal to the cosine of the angle between the two
vectors.

_______________________________________________________________________


Name dump_face - dump the contents of the face data
structure to the screen.

Usage void dump_face(FACE this_face);

Related
functions usage void dump_mat(MATRHX this_mat);
void dump_obj(OBJECT this_obj);

Description dump_face displays the contents of the data
structure this_face to the screen. This
function is useful for debugging.

dump_mat displays the elements of a matrix.

dump_obj displays the contents of the data
structurdithis_obj by calling dump_face for
each face in the object.

Return value None of these functions returns a value.

_____________________________________________________________________


Name dump_mat - dump the contents of a matrix to
the screen.

Usage void dump_mat(MATRHX this_mat);

Description See dump_face

_____________________________________________________________________


Name dump_obj - dump the contents of the object data
structure to the screen.

Usage void dump_obj(OBJECT this_obj);

Description See dump_face

_______________________________________________________________________


Name identity - initialize a matrix.

Usage void identity(MATRHX this_mat);



6








Description identity assigns a value to each element of
this_mat. The diagonal elements are assigned
a value of 1.0. Off diagonal elements are
assigned a value of 0.

Return value This function does not return a value.

_______________________________________________________________________


Name mat_mul - multiply two matrices.

Usage void mat_mul(MATRHX mat1, MATRHX mat2,
MATRHX mat3);

Description mat_mul multiplies two 4 X 4 matrices mat1 and
mat2 and assigns the result to mat3.

Return value This function does not return a value.

_______________________________________________________________________


Name max_z - return the maximum z coordinate in the
face.

Usage double max_z(FACE *this_face);

Related
functions usage double min_z(FACE *this_face);

Description max_z returns the value of the largest z
coordinate of any corner in the face.

min_z returns the value of the smallest z
coordinate of any corner in the face.

Return value max_z returns a double precision value equal
to the maximum z coordinate of the face.

min_z returns a double precision value equal
to the minimum z coordinate of the face

_____________________________________________________________________


Name min_z - return the minimum z coordinate in the
face.

Usage double min_z(FACE *this_face);

Description See max_z





7








Name new_face - initialize a face.

Usage int new_face(FACE *this_face);

Related
functions usage int new_obj(OBJECT *this_obj);

Description new_face initializes the data structure for a face.
The data structure must be initialized before adding
corners.

new_obj initializes the data structurd for an object.
The data structure must be initialized before adding
faces.

Return value Either function returns a 0 if successful. Either
returns 1 if memory cannot be allocated.

_______________________________________________________________________


Name new_obj - initialize an object.

Usage int new_obj(OBJECT *this_obj);

Description See new_face

_______________________________________________________________________


Name normal - calculate the normal to a face.

Usage int normal(FACE *this_face, VECTOR norm);

Description normal calculates the normal vector of this_face
and assigns it to norm. The function assumes that
the corners have been added in standard order, and
that the polygon is convex.

Return value The function returns 0 if the operation is successful.
The function returns 1 if the face has fewer than
three corners.

_______________________________________________________________________


Name scale - add scaling to a transformation matrix.

Usage void scale(double sx, double sy, double sz,
MATRHX this_mat);







8








Related
functions usage void trans(double tx, double ty, double tz,
MATRHX this_mat);
void xrot(double theta, MATRHX this_mat);
void yrot(double theta, MATRHX this_mat);
void zrot(double theta, MATRHX this_mat);

Description scale adds scaling to the transformation matrix.
Each axis may be scaled differently. When a point
is scaled, the x coordinate is multiplied by sx, and
so on.

trans adds translation to the transformation matrix.
When a point is translated, tx is added to the x
coordinate, and so on.

xrot adds rotation about the x axis to the trans-
formation matrix. Similarly, yrot and zrot add
rotation about the y axis and z axis respectively.

Return value None of these functions returns a value.

_______________________________________________________________________


Name trans - add translation to the transformation
matrix.

Usage void trans(double tx, double ty, double tz,
MATRHX this_mat);

Description See scale

_______________________________________________________________________


Name xform - transform an object.

Usage int xform(OBJECT this_obj, MATRHX transform);

Description xform transforms an object by multiplying every
vertex in the object by the transformation matrix.

Return value The function always returns a 0.

_______________________________________________________________________


Name xrot - add rotation about the x axis to the trans-
formation matrix.

Usage void xrot(double theta, MATRHX this_mat);

Description See scale



9








Name yrot - add rotation about the y axis to the trans-
formation matrix.

Usage void yrot(double theta, MATRHX this_mat);

Description See scale

_______________________________________________________________________


Name zrot - add rotation about the z axis to the trans-
formation matrix.

Usage void zrot(doubldithdta, MATRHX this_mat);

Description See scale









































10








NOTICE

3D TRANSFORMS is protected by copyright. The functions in this
library may be used for your own personal use, but may NOT be
resold or used for any other commercial purpose, or included in
any commercial product without written permission from the author.
You may copy and distributdithis product freely, provided 1) it
is reproduced in its entirety, including documentation and exam-
plds, and 2) you do not charge for copies (other than a nominal
copying fee to cover materials).

You may obtain permission to use 3D TRANSFORMS commercially,
along with complete source code, by sending $25.00 U.S. to:


Gus O'Donnell
8301 Mondon Way
Orangevald, CA 95662


Please send commentPd suggestions to thlightame address, or
leave a message on Compuserve, user ID 76214,1554.



































11