.TH GRAPHMAT 3 "15 September 1992"
.SH NAME
m_alloc2, m_free2, v_alloc2, v_free2, m_alloc3, m_free3, v_alloc3, v_free3, m_cpy2, m_unity2, v_cpy2, v_fill2, v_unity2, v_zero2, m_cpy3, m_unity3, v_cpy3, v_fill3, v_unity3, v_zero3, m_det2, v_len2, vtmv_mul2, vv_inprod2, m_inv2, m_tra2, mm_add2, mm_mul2, mm_sub2, mtmm_mul2, sm_mul2, mv_mul2, sv_mul2, v_homo2, v_norm2, vv_add2, vv_sub2, vvt_mul2, m_det3, v_len3, vtmv_mul3, vv_inprod3, m_inv3, m_tra3, mm_add3, mm_mul3, mm_sub3, mtmm_mul3, sm_mul3, mv_mul3, sv_mul3, v_homo3, v_norm3, vv_add3, vv_cross3, vv_sub3, vvt_mul3, miraxis2, mirorig2, mirplane2, rot2, scaorig2, scaplane2, scaxis2, transl2, miraxis3, mirorig3, mirplane3, prjorthaxis, prjpersaxis, rot3, scaorig3, scaplane3, scaxis3, transl3 \- 3d graphics and associated matrix and vector routines
.nf
.SH SYNOPSIS
.nf
.B #include <graphmat.h>
.LP
.I /* Data initialisation */
.LP
.ta 1.0i
.B hmat2_t 	*m_alloc2(m_result)
.br
.B hmat2_t 	*m_result;

.B void		m_free2(matrix)
.br
.B hmat2_t	*matrix;

.B hvec2_t  	*v_alloc2(v_result)
.br
.B hvec2_t 	*v_result;

.B void		v_free2(vector)
.br
.B hmat2_t	*vector;

.B hmat3_t 	*m_alloc3(m_result)
.br
.B hmat3_t 	*m_result;

.B void		m_free3(matrix)
.br
.B hmat3_t	*matrix;

.B hvec3_t 	*v_alloc3(v_result)
.br
.B hvec3_t 	*v_result;

.B void		v_free3(vector)
.br
.B hmat3_t	*vector;

.B hmat2_t 	*m_cpy2(m_source, m_result)
.br
.B hmat2_t 	*m_source, *m_result;

.B hmat2_t 	*m_unity2( m_result)
.br
.B hmat2_t 	*m_result;

.B hvec2_t 	*v_cpy2(v_source, v_result) 
.br
.B hvec2_t 	*v_source, *v_result;

.B hvec2_t 	*v_fill2(x, y, w, v_result)
.br
.B double      	x, y, w;
.br
.B hvec2_t	*v_result;

.B hvec2_t 	*v_unity2(axis, v_result)
.br
.B b_axis     	axis;
.br
.B hvec2_t 	*v_result;

.B hvec2_t 	*v_zero2(v_result)
.br
.B hvec2_t 	*v_result;

.B hmat3_t 	*m_cpy3(m_source, m_result)
.br
.B hmat3_t 	*m_source, *m_result;

.B hmat3_t 	*m_unity3(m_result)
.br
.B hmat3_t 	*m_result;

.B hvec3_t 	*v_cpy3(v_source, v_result) 
.br
.B hvec3_t 	*v_source, *v_result;

.B hvec3_t 	*v_fill3(x, y, z, w, v_result)
.br
.B double     	x, y, z, w;
.br
.B hvec3_t	*v_result;

.B hvec3_t 	*v_unity3(axis, v_result)
.br
.B b_axis     	axis;
.br
.B hvec3_t 	*v_result;

.B hvec3_t 	*v_zero3(vector)
.br
.B hvec3_t 	*vector;

.LP
.I /* Basic Linear Algebra */
.LP
.B double    	m_det2(matrix)
.br
.B hmat2_t 	*matrix;

.B double     	v_len2(vector)
.br
.B hvec2_t 	*vector;

.B double     	vtmv_mul2(vector, matrix)
.br
.B hvec2_t 	*vector;
.br
.B hmat2_t 	*matrix;

.B double     	vv_inprod2(vectorA, vectorB)
.br
.B hvec2_t 	*vectorA, *vectorB;

.B hmat2_t 	*m_inv2(matrix, m_result)
.br
.B hmat2_t 	*matrix, *m_result;

.B hmat2_t 	*m_tra2(matrix, m_result)
.br
.B hmat2_t 	*matrix, *m_result;

.B hmat2_t 	*mm_add2(matrixA, matrixB, m_result)
.br
.B hmat2_t 	*matrixA, *matrixB, *m_result;

.B hmat2_t 	*mm_mul2(matrixA, matrixB, m_result)
.br
.B hmat2_t 	*matrixA, *matrixB, *m_result;

.B hmat2_t 	*mm_sub2(matrixA, matrixB, m_result)
.br
.B hmat2_t 	*matrixA, *matrixB, *m_result;

.B hmat2_t 	*mtmm_mul2(matrixA, matrixB, m_result)
.br
.B hmat2_t 	*matrixA, *matrixB, *m_result;

.B hmat2_t 	*sm_mul2(scalar, matrix, m_result)
.br
.B double     	scalar;
.br
.B hmat2_t 	*matrix, *m_result;

.B hmat2_t	*vvt_mul2(vectorA, vectorB, m_result)
.br
.B hvec2_t	*vectorA, *vectorB;
.br
.B hmat2_t	*m_result;

.B hvec2_t 	*mv_mul2(matrix, vector, v_result)
.br
.B hmat2      	*matrix;
.br
.B hvec2_t 	*vector, *v_result;

.B hvec2_t 	*sv_mul2(scalar, vector, v_result)
.br
.B double    	scalar;
.br
.B hvec2_t  	*vector, *v_result;

.B hvec2_t 	*v_homo2(vector, v_result)
.br
.B hvec2_t 	*vector, *v_result;

.B hvec2_t 	*v_norm2(vector, v_result)
.br
.B hvec2_t 	*vector, *v_result;

.B hvec2_t 	*vv_add2(vectorA, vectorB, v_result)
.br
.B hvec2_t 	*vectorA, *vectorB, *v_result;

.B hvec2_t 	*vv_sub2(vectorA, vectorB, v_result)
.br
.B hvec2_t 	*vectorA, *vectorB, *v_result;

.B double    	m_det3(matrix)
.br
.B hmat3_t 	*matrix;

.B double 	v_len3(vector)
.br
.B hvec3_t 	*vector;

.B double 	vtmv_mul3(vector, matrix)
.br
.B hvec3_t 	*vector;
.br
.B hmat3_t 	*matrix;

.B double 	vv_inprod3(vectorA, vectorB)
.br
.B hvec3_t 	*vectorA, *vectorB;

.B hmat3_t 	*m_inv3(matrix, m_result)
.br
.B hmat3_t 	*matrix, *m_result;

.B hmat3_t 	*m_tra3(matrix, m_result)
.br
.B hmat3_t 	*matrix, *m_result;

.B hmat3_t 	*mm_add3(matrixA, matrixB, m_result)
.br
.B hmat3_t 	*matrixA, *matrixB, *m_result;

.B hmat3_t 	*mm_mul3(matrixA, matrixB, m_result)
.br
.B hmat3_t 	*matrixA, *matrixB, *m_result;

.B hmat3_t 	*mm_sub3(matrixA, matrixB, m_result)
.br
.B hmat3_t 	*matrixA, *matrixB, *m_result;

.B hmat3_t 	*mtmm_mul3(matrixA, matrixB, m_result)
.br
.B hmat3_t 	*matrixA, *matrixB, *m_result;

.B hmat3_t 	*sm_mul3(scalar, matrix, m_result)
.br
.B double 	scalar;
.br
.B hmat3_t 	*matrix, *m_result;

.B hmat3_t	*vvt_mul3(vectorA, vectorB, m_result)
.br
.B hvec3_t	*vectorA, *vectorB;
.br
.B hmat3_t	*m_result;

.B hvec3_t 	*mv_mul3(matrix, vector, v_result)
.br
.B hmat3_t 	*matrix;
.br
.B *hvec3_t 	*vector, *v_result;

.B hvec3_t 	*sv_mul3(scalar, vec, v_result)
.br
.B double 	scalar;
.br
.B hvec3_t  	*vector, *v_result;

.B hvec3_t 	*v_homo3(vector, v_result)
.br
.B hvec3_t 	*vector, *v_result;

.B hvec3_t 	*v_norm3(vector, v_result)
.br
.B hvec3_t 	*vector, *v_result;

.B hvec3_t    	*vv_add3(vectorA, vectorB, v_result)
.br
.B hvec3_t    	*vectorA, *vectorB, *v_result;

.B hvec3_t    	*vv_cross3(vectorA, vectorB, v_result)
.br
.B hvec3_t    	*vectorA, *vectorB, *v_result;

.B hvec3_t    	*vv_sub3(vectorA, vectorB, v_result)
.br
.B hvec3_t    	*vectorA, *vectorB, *v_result;


.LP
.I /* Elementary transformations */
.LP
.B hmat2_t	*miraxis2(axis, m_result)
.br
.B b_axis	axis;
.br
.B hmat2_t	*m_result;

.B hmat2_t	*mirorig2(m_result)
.br
.B hmat2_t	*m_result;

.B hmat2_t	*rot2( rotation, m_result)
.br
.B double    	rotation;
.br
.B hmat2_t	*m_result;

.B hmat2_t	*scaorig2(scale, m_result)
.br
.B double    	scale;
.br
.B hmat2_t	*m_result;

.B hmat2_t	*scaxis2(scale, axis, m_result)
.br
.B double     	scale;
.br
.B b_axis	axis;
.br
.B hmat2_t	*m_result;

.B hmat2_t	*transl2(translation, m_result)
.br
.B hvec2_t	*translation;
.br
.B hmat2_t	*m_result;

.B hmat3_t	*miraxis3(axis, m_result)
.br
.B b_axis	axis;
.br
.B hmat3_t	*m_result;

.B hmat3_t	*mirorig3(m_result)
.br
.B hmat3_t	*m_result;

.B hmat3_t	*mirplane3(plane, m_result)
.br
.B b_axis	plane;
.br
.B hmat3_t	*m_result;

.B hmat3_t	*prjorthaxis(axis, m_result)
.br
.B b_axis	axis;
.br
.B hmat3_t	*m_result;

.B hmat3_t	*prjpersaxis(axis, m_result)
.br
.B b_axis	axis;
.br
.B hmat3_t	*m_result;

.B hmat3_t	*rot3( rotation, axis, m_result)
.br
.B double    	rotation;
.br
.B b_axis	axis;
.br
.B hmat3_t	*m_result;

.B hmat3_t	*scaorig3(scale, m_result)
.br
.B double    	scale;
.br
.B hmat3_t	*m_result;

.B hmat3_t	*scaplane(scale, plane, m_result)
.br
.B double    	scale;
.br
.B b_axis	plane;
.br
.B hmat3_t	*m_result;

.B hmat3_t	*scaxis3(scale, axis, m_result)
.br
.B double    	scale;
.br
.B b_axis	axis;
.br
.B hmat3_t	*m_result;

.B hmat3_t	*transl3(translation, m_result)
.br
.B hvec3_t    	*translation;
.br
.B hmat3_t	*m_result;
.SH DESCRIPTION
Matrix and vector routines associated with 3d
graphics in homogeneous coordinates, such as basic linear algebra
and elementary transformations.
.LP
This library is setup with a multi-level approach.
.br
.I Level1 :
.B the data level.
.br
.I Level 2:
.B the data initialisation level.
.br
.I Level 3:
.B basic linear algebra level.
.br
.I Level 4:
.B elementary transformation level.
.br

.I
Level 1,
the data structures, is realised as follows :
.br
.B typedef union
.br
.B {
.br
.B	double a[3];
.br
.B	struct 
.br
.B	{
.br
.B		double    x, y, w;
.br
.B	} s;
.br
.B } hvec2_t;
.LP
.LP
.B typedef union
.br
.B {
.br
.B	double a[4];
.br
.B	struct 
.br
.B	{
.br
.B		double    x, y, z, w;
.br
.B	} s;
.br
.B } hvec3_t;
.LP
.LP
.B typedef struct
.br
.B { 
.br
.B	double m[3][3];
.br
.B } hmat2_t;
.LP
.LP
.B typedef struct
.br
.B { 
.br
.B	double m[4][4];
.br
.B } hmat3_t;
.LP
.LP
To access the data elements of a vector or a matrix can be accessed with the
macros:
.LP
#define	v_x( vec )		((vec).s.x)
.br
#define	v_y( vec )		((vec).s.y)
.br
#define	v_z( vec )		((vec).s.z)
.br
#define	v_w( vec )		((vec).s.w)
.br
#define	v_elem( vec, i )	((vec).a[(i)])
.br
#define	m_elem( mat, i, j )	((mat).m[(i)][(j)])
.br
.LP
.LP
.B typedef enum
.br
.B {
.br
.B		X_AXIS, Y_AXIS, Z_AXIS
.br
.B } b_axis;
.LP
.LP 
The functions are as follows sorted:
.br
first on the level in which they belong, then on their return value and then on their name.

.SH NAMES

The function names begin with an abbreviation of the type of
operand, and in which order the operations will be carried out
on that operand. Then the order of and which operation will be
carried out, followed by the type of coordinates. (i.e
.I vtmv_mul3(vector, matrix) :
first take the transpose of 
.I vector,
multiply the transpose with  
.I matrix,
this result is multiplied by the incoming vector, all coordinates
are homogeneous 3d coordinates.)

.SH USAGE

All the "functions" may have been implemented as macro's, so you can't
take the address of a function. It is however guaranteed that arguments 
of each function/macro will be evaluated only once, except for the result
argument, which can be evaluated multiple times.
.LP
All operations can be used in place, but overlapping data gives
unspecified results.
.LP
If the parameter 
.I v_result
or
.I m_result
of a function or the parameter of an initialisation function
equals
.B NULL,
space for the parameter will be dynamically allocated using 
.B malloc(),
otherwise the parameter is assumed to hold a pointer to a memory
area which can be used. A pointer to the used area (which may have been
new allocated) is always returned.
.br
If an error occurred like memory could not be allocated,
an attempt to divide by
zero occurs, or an attempt to invert a singular matrix a general error-routine 
will be called, which has
two parameters :
.I gm_errno
and 
.I gm_func.
.br
.I gm_errno
is the error type which is one of the following
constants : 
.B DIV0,
.B NOMEM
or
.B MATSING.
.I gm_func
is a pointer to a string which contains the name of
the function where the error occurred.
.LP
A pointer to the error routine is defined as follows :
.br
.B void (* gm_error)(gm_errno, gm_func);
.br
.B gm_error_t gm_errno;
.br
.B char *gm_func;
.LP
With 
.I gm_error_t 
is defined as :
.br
.B typedef enum
.br
.B {
.br
.B	DIV0, NOMEM, MATSING
.br
.B } gm_error_t;
.br
.LP
The default error handler will abort after printing a diagnostic. You can 
redirect
.I gm_error
to your own error handler. It is not advisable to return from the error
handler as error recovery is not expected to take place.
.LP
Matrices are of type 
.B hmat3_t 
or 
.B hmat2_t 
for 2d or 3d
coordinates, respectively. 
.br
Vectors are of type 
.B hvec3_t 
or 
.B hvec2_t.
.LP
The elements of a vector can be accessed in two manners, the
first one is by name of an element of a structure, the second is
like an array.
.LP
A plane is described by the normal to that plane, with the
assumption made that the origin is an element of the plane. 
.LP
.I rotation 
is assumed to be a radial.
.LP
If a function is deallocating memory, it will check if the
incoming pointer is a
.B NULL
pointer.
.LP
.LP
.I /* Level2 : Data initialisation */
.LP
.B m_alloc2(), v_alloc2(), m_alloc3(), v_alloc3() 
allocate memory for a data item of type 
.B hmat2_t, hvec2_t, hmat3_t
and
.B hvec3_t
respectively.
.br
.B m_free2(), v_free2(), m_free3(), v_free3()
reclaim the storage allocated previously. 
.br
.B m_cpy2(), m_cpy3()
copies 
.I m_matrix 
into 
.I m_result.
.br
.B m_unity2(), m_unity3()
returns the unity matrix. (2d respectively 3d homogeneous coordinates)
.br
.B v_cpy2(), v_cpy3()
copies 
.I v_source
into 
.I v_result.
(2d respectively 3d homogeneous coordinates)
.br
.B v_fill2(), v_fill3() 
fills 
.I v_result
according the given values.
.br
.B v_unity2(), v_unity3()
returns the unity vector with 
.I w = 1.0,
the incoming basic axis 
.I axis = 1.0, 
and the
other element(s) are 0.0; (2d  respectively 3d homogeneous coordinates)
.br
.B v_zero2(), v_zero3() 
return a vector with 
.I w 
= 1.0
and the other elements 0.0;
.br
.B m_cpy2(), m_cpy3()
copies 
.I m_source
into 
.I m_result.
(2d respectively 3d homogeneous coordinates)
.LP
.I /* level3 : Basic Linear Algebra */
.LP
.B m_det2(), m_det3()
calculates the determinant of the incoming matrix. The determinant is
calculated in cartesian rather than homogeneous coordinates.
.br
.B v_len2(), v_len3()
calculates the length of the cathesian part of the homogeneous vector.
.br
.B vtmv_mul2(), vtmv_mul3()
calculate the result of the transpose of the incoming vector
multiplied by the incoming matrix multiplied by the incoming
vector (2d respectively 3d homogeneous coordinates)
.br
.B vv_inprod2(), vv_inprod3() 
calculates the geometrical innerproduct (vector . vector) of 
.I vectorA
and
.I vectorB.
.br
.B m_inv2(), m_inv3()
calculates the inverse of 
.I matrix.
It is an error if the matrix in singular.
.br
.B m_tra2(), m_tra3()
calculates the transpose 
.I matrix.
(2d respectively 3d homogeneous coordinates)
.br
.B mm_add2(), mm_sub2(), mm_add3(), mm_sub3()
calculates the result of 
.I matrixA
+ respectively -
.I matrixB.
This operation is unspecified in the sense of homogeneous coordinates; the
matrices are taken in their normal, mathematial sense.
.br
.B mm_mul2(), mm_mul3()
calculates the result of 
.I matrixA*matrixB 
(2d respectively 3d homogeneous coordinates)
.br
.B mtmm_mul2(), mtmm_mul3()
calculates the result of the transpose of the incoming 
.I matrixA
multiplied by 
.I matrixB 
multiplied by 
.I matrixA 
(2d respectively 3d homogeneous coordinates)
.br
.B sm_mul2(), sm_mul3()
calculates the result of 
.I scalar*matrix 
(2d respectively 3d homogeneous coordinates)
.br
.B mv_mul2(), mv_mul3()
calculates the result of 
.I matrix*vector
(2d respectively 3d homogeneous coordinates)
.br
.B sv_mul2(), sv_mul3() 
calculates the result of 
.I scalar*vector. 
(2d respectively 3d homogeneous coordinates)
.br
.B v_homo2(), v_homo3()
homogenize 
.I vector
so that the 
.I w
component becomes 1.0 but the length of the vector in homogeneous coordinates
stays the same. (2d respectively 3d homogeneous coordinates)
.br
.B v_norm2(), v_norm3()
normalises the incoming vector so the length of the cartesian vector
becomes 1.0. The homogeneous length stays the same.
(2d respectively 3d homogeneous coordinates)
.br
.B vv_add2(), vv_sub2(), vv_add3(), vv_sub3()
calculates the result of 
.I vectorA
+ respectively -
.I vectorB.
These operations are done in the mathematical sense. Be careful with homogeneous
coordinates, as not every possible input makes sense.
.br
.B vvt_mul2(), vvt_mul3()
calculates the result of 
.I vectorA 
multiplied by the transpose of
.I vectorB 
(2d respectively 3d homogeneous coordinates)
.br
.B vv_cross3()
calculates the geometrical crossproduct (
.I vectorA x vectorB) of two
vectors (3d homogeneous coordinates)
.LP
.I /* level4 : Elementary transformations */
.LP
.B miraxis2(), miraxis3()
calculates the mirror matrix with respect to 
.I axis. 
(2d respectively 3d homogeneous coordinates)
.br
.B mirorg2(), mirorg3()
calculates the mirror matrix relative to the origin. (2d respectively 3d
homogeneous coordinates)
.br
.B mirplane3()
calculates the mirror matrix relative to a plane. (3d homogeneous
coordinates)
.br
.B rot2()
calculates the rotation matrix over 
.I rotation
relative to the origin.
(2d homogeneous coordinates)
.br
.B rot3()
calculates the rotation matrix over 
.I rotation
along 
.I axis. 
(3d homogeneous coordinates)
.br
.B scaorg2(), scaorg3()
calculates the matrix of scaling with
.I scale
relative to the origin. (2d respectively 3d
homogeneous coordinates)
.br
.B scaplane3()
calculates the matrix of scaling with
.I scale
relative to a plane of which
.I plane
is the normal. (3d
homogeneous coordinates)
.br
.B scaxis2(), scaxis3()
calculates the matrix of scaling with
.I scale
relative to the line given by
.I axis.
(2d respectively 3d homogeneous coordinates)
.br
.B transl2(), transl3()
calculates the translation matrix over 
.I translation.
(2d respectively 3d homogeneous coordinates)
.br
.B prjorthaxis()
calculates the orthographic projection matrix along 
.I axis.
(3d homogeneous coordinates)
.br
.B prjpersaxis()
calculates the perspective projection with along
.I axis
The focus is in the origin. The projection plane is on distance
1.0 before the camera.
(3d homogeneous coordinates)

.SH CAVEATS
Vector addition and subtraction and matrix addition and
substraction are not defined for homogeneous coordinates.
One can add and subtract a point vector and a free vector, but you have to normalise the point vector first.
The result of the subtraction of two point vectors is a free vector.
.LP
Calculating the determinant of a matrix and the length of a vector is unspecified
in the sense of homogeneous coordinates

.SH RETURN VALUES
There are six types of return values: 
.B
void, double, *hvec3_t, *hvec2_t, *hmat3_t and *hmat2_t.

.SH SEE ALSO
graphadd(3), graphmat++(3), fmatpinv(3TV), malloc(3V), Graphics and matrix routines.

.SH NOTE
Library file is
.B /usr/local/lib/libgraphmat.a

.SH AUTHOR
Hans Gringhuis.
.br
Klamer Schutte