--- name: "sipp_geometric" section: "3" platform: "linux" package: "sipp-dev" version: "3.1-11" release: "Debian 4.0 (Etch)" platforms: ["linux"] url: "https://new.carta.tech/sipp_geometric" --- # sipp\_geometric(3) Vector and matrix functions for the sipp(3) library ## NAME geometric - Vector and matrix functions for the [sipp(3)](/sipp/3.md) library ## SYNOPSIS *#include \* \[g\]cc \[*flags*\] *files* -lsipp -lm \[ *libraries* \] ## DESCRIPTION The [sipp(3)](/sipp/3.md) 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. ## 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 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. ## MATRIX OPERATIONS 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. ## SEE ALSO [sipp(3)](/sipp/3.md) - simple polygon processor, a 3d-graphics library\ [sipp\_shaders(3)](/sipp_shaders/3.md) - a collection of shaders for *sipp*.\ [sipp\_primitives(3)](/sipp_primitives/3.md) - a collection of object primitives for *sipp*.\ [sipp\_pixmap(3)](/sipp_pixmap/3.md) - 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.