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

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

The sipp(3) 3D rendering library uses a lot of vector calculations and geometric transformations. The functions which implement these features are declared in geometric.h and are described in this manual.

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 values 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 result 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 vectors in sipp.

An ordinary homogenous transformation matrix has 4 X 4 elements. However, all linear transformations only use 4 X 3 values 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 geometric.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 matrixes.

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 operating 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 represents 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 represents 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 represents 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 represents 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 represents 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 represents 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 represents the concatenation of the previous transformation in mat and a mirroring in the plane defined by the point point and the normal 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 result in the matrix res. All three parameters are pointers to matrixes. 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 transformation 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.

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.

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

Inge Wallin (ingwa@isy.liu.se)

No known bugs.