C/C++ Interactive Reference Guide

home *** CD-ROM | disk | FTP | other *** search

/ C/C++ Interactive Reference Guide / C-C++ Interactive Reference Guide.iso / c_ref / csource5 / 302_01 / 3dlib.doc < prev next >

Wrap

Text File | 1990-02-14 | 19.9 KB | 790 lines

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 scale the 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: scale 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: MATRIX: A 4 X 4 matrix is used to describe transformations in three dimensions, such as rotation, scaling, and translation. Multiple transformations 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 define the 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 = (FACE *)malloc(sizeof(FACE)); o = (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. Create the transformation matrix. In this example, the matrix includes rotation followed by translation: MATRIX 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 be transformed with a second matrix: VECTOR s; MATRIX id; identity (id); s[0] = 0.0; s[1] = 0.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, see the 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 defined 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, MATRIX xfrm_mat); Related functions usage void disp_object(VECTOR lsource, int color, OBJECT *this_obj, MATRIX 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, MATRIX 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(MATRIX 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 structure this_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(MATRIX 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(MATRIX 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(MATRIX mat1, MATRIX mat2, MATRIX 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 structure 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, MATRIX this_mat); 8 Related functions usage void trans(double tx, double ty, double tz, MATRIX this_mat); void xrot(double theta, MATRIX this_mat); void yrot(double theta, MATRIX this_mat); void zrot(double theta, MATRIX 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, MATRIX this_mat); Description See scale _______________________________________________________________________ Name xform - transform an object. Usage int xform(OBJECT this_obj, MATRIX 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, MATRIX this_mat); Description See scale 9 Name yrot - add rotation about the y axis to the trans- formation matrix. Usage void yrot(double theta, MATRIX this_mat); Description See scale _______________________________________________________________________ Name zrot - add rotation about the z axis to the trans- formation matrix. Usage void zrot(double theta, MATRIX 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 distribute this product freely, provided 1) it is reproduced in its entirety, including documentation and exam- ples, 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 Orangevale, CA 95662 Please send comments and suggestions to this same address, or leave a message on Compuserve, user ID 76214,1554. 11