geometric(3)

NAME

geometric - Vector and matrix functions for the sipp(3)

library

SYNOPSIS

#include <geometric.h>
[g]cc [flags] files -lsipp -lm [ libraries ]

DESCRIPTION

The sipp(3) 3D rendering library uses a lot of vector cal

culations and geometric transformations. The functions which im

plement these features are declared in geometric.h and are de

scribed in this manual.

VECTOR OPERATIONS

Sipp uses row vectors, not column vectors and a vector is

defined as follows:

typedef struct {

double x;
double y;
double z;

} Vector;

A vector is used both for directional vectors and points

(positional vectors). In the description of the sipp vector

macros and functions below, lower case letters denote scalar val

ues and upper case letters denote vectors.

MakeVector(V, xx, yy, zz)

Put xx, yy and zz in the x, y and z slot of the

Vector V respectively.

VecNegate(A)

Negate all components of the Vector A.

VecDot(A, B)

Return the dot product of the two Vectors A and B.

VecLen(A)

Return the length of the Vector A.

VecCopy(B, A)

Copy the Vector A to the Vector B (B = A; using C

notation).

VecAdd(C, A, B)

Add the two Vectors A and B and put the result in C

(Add A to B giving C; using COBOL notation).

VecSub(C, A, B)

Subtract the Vector B from Vector A and put the re

sult in C (C = A - B; using C notation).

VecScalMul(B, a, A)

Multiply the Vector A with the scalar a and put the

result in Vector B (B = a * A; using C notation).

VecAddS(C, a, A, B)

Multiply the Vector A with the scalar a, add it to

Vector B and put the result in Vector C (C = a * A + B; using C

notation).

VecComb(C, a, A, b, B)

Linearly combine the two Vectors A and B and put

the result in Vector C (C = a * A + b * B; using C notation).

VecCross(C, A, B)

Cross multiply Vector A with Vector B and put the

result in C (C = A X B; using C notation).

void vecnorm(v)

Vector *v;

Normalize the vector v, i.e. keep the direction but

make it have length 1. The length of v should not be equal to 0

to begin with. NOTE: This is the only function operating on vec

tors in sipp.

MATRIX OPERATIONS

An ordinary homogenous transformation matrix has 4 X 4 el

ements. However, all linear transformations only use 4 X 3 val

ues so to save space a sipp transformation matrix only store 4 X

3 values. Thus the transformation matrix used in sipp is defined

as follows:

typedef struct {

double mat[4][3];

} Transf_mat;

We wrap a struct around the two-dimensional array since we

want to be able to say things like &mat without being forced to

write (Transf_mat *) &mat[0] which we find horribly ugly.

There is a predefined identity matrix declared in geomet

ric.h which you can use if you want to:

extern Transf_mat ident_matrix;

The rest of this section describes the macro and functions

defined in the sipp library which work on sipp transformation ma

trixes.

MatCopy(A, B)

This macro copies the matrix B to the matrix A. A

and B should both be pointers. NOTE: This is the only macro op

erating on matrices in sipp.

Transf_mat *transf_mat_create(initmat)

Transf_mat *initmat;

Allocate memory for a new transformation matrix and

if initmat is equal to NULL, set the new matrix to the identity

matrix. Otherwise set the new matrix to the contents of initmat.

Return a pointer to the new matrix.

Transf_mat *transf_mat_destruct(mat)

Transf_mat *initmat;

Free the memory associated with the matrix mat.

void mat_translate(mat, dx, dy, dz)

Transf_mat *mat;
double dx;
double dy;
double dz;

Set mat to the transformation matrix that repre

sents the concatenation of the previous transformation in mat and

a translation along the vector (dx, dy, dz).

void mat_rotate_x(mat, ang)

Transf_mat *mat;
double ang;

Set mat to the transformation matrix that repre

sents the concatenation of the previous transformation in mat and

a rotation with the angle ang around the X axis. The angle ang is

expressed in radians.

void mat_rotate_y(mat, ang)

Transf_mat *mat;
double ang;

Set mat to the transformation matrix that repre

sents the concatenation of the previous transformation in mat and

a rotation with the angle ang around the Y axis. The angle ang

is expressed in radians.

void mat_rotate_z(mat, ang)

Transf_mat *mat;
double ang;

Set mat to the transformation matrix that repre

sents the concatenation of the previous transformation in mat and

a rotation with the angle ang around the Z axis. The angle ang

is expressed in radians.

void mat_rotate(mat, point, vector, ang)

Transf_mat *mat;
Vector *point;
Vector *vector
double ang;

Set mat to the transformation matrix that repre

sents the concatenation of the previous transformation in mat and

a rotation with the angle ang around the line represented by the

point point and the vector vector. The angle ang is expressed in

radians.

void mat_scale(mat, xscale, yscale, zscale)

Transf_mat *mat;
double xscale;
double yscale;
double zscale;

Set mat to the transformation matrix that repre

sents the concatenation of the previous transformation in mat and

a scaling with the scaling factors (xscale, yscale, zscale).

void mat_mirror_plane(mat, point, normal)

Transf_mat *mat;
Vector *point;
Vector *normal

Set mat to the transformation matrix that repre

sents the concatenation of the previous transformation in mat and

a mirroring in the plane defined by the point point and the nor

mal vector normal.

void mat_mul(res, a, b)

Transf_mat *res
Transf_mat *a
Transf_mat *b

Multiply the two matrixes a and b and put the re

sult in the matrix res. All three parameters are pointers to ma

trixes. It is possible for res to point at the same matrix as

either a or b since the result is stored in a temporary matrix

during the computations.

void point_transform(res, vec, mat)

Vector *res
Vector *vec;
Transf_mat *mat;

Transform the point (vector) vec with the transfor

mation matrix mat and put the result into the vector res. The

two vectors res and vec should not be the same vector since no

temporary is used during the computations.

SEE ALSO

sipp(3) - simple polygon processor, a 3d-graphics library
sipp_shaders(3) - a collection of shaders for sipp.
sipp_primitives(3) - a collection of object primitives for

sipp.
sipp_pixmap(3) - pixmap handling code for sipp.
sipp_bitmap(3) - bitmap handling code for sipp.

AUTHORS

Jonas Yngvesson (jonas-y@isy.liu.se)
Inge Wallin (ingwa@isy.liu.se)

BUGS

No known bugs.

3 July , 1991

GEOMETRIC(3)