--- name: "sipp" section: "3" platform: "linux" package: "sipp-dev" version: "3.1-11" release: "Debian 4.0 (Etch)" platforms: ["linux"] url: "https://new.carta.tech/sipp/3" --- # sipp(3) simple polygon processor, a 3d-graphics library ## NAME sipp - simple polygon processor, a 3d-graphics library ## SYNOPSIS *#include \* \[g\]cc \[*flags*\] *files* -lsipp -lm \[ *libraries* \] ## DESCRIPTION SIPP is a library for creating 3-dimensional scenes and rendering them using a scan-line z-buffer algorithm. A scene is built up of objects which can be transformed with rotation, translation and scaling. The objects form hierarchies where each object can have arbitrarily many subobjects and subsurfaces. A surface is a number of connected polygons which are rendered with either Phong, Gouraud or flat shading. An image can also be rendered as a line drawing of the polygon edges without any shading at all. The library also provides 3-dimensional texture mapping with automatic interpolation of texture coordinates. Simple anti-aliasing can be performed through oversampling. The scene can be illuminated by an arbitrary number of lightsources. These lightsources can be of three basic types: directional, point or spotlight. Light from spotlights can cast shadows. It is possible to create several virtual cameras, and then specify one of them to use when rendering the image. A major feature in SIPP is the ability for a user to provide his own shading function for a surface. This makes it easy to experiment with various shading models and to do special effects. The shader controls both the color and opacity of a surface. A basic shading algorithm is provided with the library, and also a number of other, more specialized shaders. Images can be rendered directly onto a file in the Portable Pixmap format (ppm) or, for line images, Portable Bitmap, (pbm) or, with a function defined by the user, into anything that it is capable of plotting a pixel (or drawing a line).This could, for instance, be a window in a window system or even a plotter file. ## USAGE This manual page is intended as a quick reference guide to data types and functions available in SIPP. See the **User's Guide to SIPP** for a detailed description of the meaning of the function arguments and the usage of the functions. ## DATA TYPES The include file *sipp.h* defines the following data types: - *bool* A boolean type, with values *TRUE* or *FALSE*. These constants are also defined in *sipp.h*. - *Color* A struct with three members, *red*, *grn* and *blu*. Each member of the struct is a *double* which should be in the range \[0,1\]. - *Vector* A struct with three members, *x*, *y* and *z* which are all *doubles*. - *Transf\_mat* *Transf\_mat* is a standard 4 x 4 homogenous transformation matrix. Actually it is stored as a 4 x 3 matrix to save memory, since the rightmost column is only needed in the viewing calculation. The members of a *Transf\_mat* should never be accessed directly, but rather through the abstract functions described in the **FUNCTIONS** section. See also geometric(3). - *Surface* and *Object* *Surface* and *Object* are both opaque types used by SIPP. A predefined *Object* called *sipp\_world* is used as starting point of the rendering process. All objects that should be included in the rendering must be in the object hierarchy under *sipp\_world*. - *Surf\_desc* A *Surf\_desc* is a surface description, used by the built-in shader to store properties about a surface. The definition of *Surf\_desc* is as follows: \ *typedef struct {*\ *double ambient;* /\* Fraction of color visible in ambient light \*/\ *double specular;* /\* Fraction of colour specularly reflected \*/\ *double c3;* /\* "Shininess" 0 = shiny, 1 = dull \*/\ *Color color;* /\* Colour of the surface \*/\ *Color opacity;* /\* Opacity of the surface \*/\ *} Surf\_desc;* - *Surf\_desc\_hdr* Header used on surface descriptions when an application needs more advanced memory menegement.\ *typedef struct {*\ *int ref\_count;* /\* Count of references \*/\ *void (\*free\_func)();* /\* Function to call to release memory \*/\ *void \*client\_data;* /\* Generic pointer to user data \*/\ *} Surf\_desc\_hdr;* - *Lightsource* This structure holds information about a lightsource. Two members in the struct, *color* and *next* are of interest to users writing their own shaders. *color* is of type *Color* and spcifies the color of the light emitted from the lightsource. *next* is a pointer to another *Lightsource* struct and points to the next defined lightsource in the scene, or *NULL* if there are no more lightsources. - *Camera* A structure holding a virtual camera. SIPP provides a predefined *Camera* and a pointer to it called *sipp\_camera*. This camera is the default viewpoint used when rendering a scene. ## FUNCTIONS The rest of this manual contains a brief description of the avaliable functions in SIPP. For a full description of how to use the functions, see **User's Guide to SIPP**. ## Initializations - *void sipp\_init()* Initialize the library and set up default values. - *void sipp\_background(red, green, blue)* *double red;*\ *double green;*\ *double blue;* Set the background color of the image. - *void sipp\_show\_backfaces(flag)* *bool flag;* Specify if backfacing polygons should be culled or not. - *void sipp\_shadows(flag, dmap\_size)* *bool flag;*\ *int dmap\_size;* Turn shadow casting on or off and specify size of depth maps. - *void sipp\_render\_direction(direction)* *bool direction;* Decide if rendering of the scanlines should take place bottom-to-top or top-to-bottom. Allowed values on *direction* are *TOP\_TO\_BOTTOM* and *BOTTOM\_TO\_TOP*. - *void sipp\_set\_update\_callback(proc, client\_data, period)* *void (\*proc)();*\ *void \*client\_data;*\ *int \*period;* Specify a callback function and the period between calls to it during rendering. - *void sipp\_user\_refcount(flag)* *bool flag;* Select if users references should be counted in surfaces and objects. This is for users who need more advanced memory management. - *bool sipp\_surface\_desc\_headers(flag)* *bool flag;* Tell SIPP that surface descriptions from now on are specified with headers of type *Surf\_desc\_hdr*. The function returns the old value of the flag. This is for users who need more advanced memory management. ## Object creation - *void vertex\_push(x, y, z)* *double x, y, z;* Push a vertex onto the internal vertex stack. - *void vertex\_tx\_push(x, y, z, u, v, w)* *double x, y, z;*\ *double u, v, w;* Push a vertex and it's texture coordinates onto the vertex stack. - *void vertex\_n\_push(x, y, z, nx, ny, nz)* *double x, y, z;*\ *double nx, ny, nz;* Push a vertex with a specified normal vector onto the vertex stack. - *void vertex\_tx\_n\_push(x, y, z, u, v, w, nx, ny, nz)* *double x, y, z;*\ *double u, v, w;*\ *double nx, ny, nz;* Push a vertex with texture coordinates and a specified normal vector onto the vertex stack. - *void polygon\_push()* Create a polygon from the vertices on the vertex stack and push it onto the polygon stack. - *Surface \*surface\_basic\_create(ambient, red, grn, blu, specular, c3, opred, opgrn, opblu)* *double ambient;*\ *double red, grn, blu;*\ *double specular;*\ *double c3;*\ *double opred, opgrn, opblu;* Create a surface from the polygons on the polygon stack. The surface will be shaded by the internal shader, *basic\_shader()*, using the parameters as values in a *Surf\_desc* struct. - *Surface \*surface\_create(surf\_desc, shader)* *void \*surf\_desc;*\ *Shader \*shader;* Create a surface from the polygons on the polygon stack. The surface will be shaded by *shader* using the surface description *surf\_desc*. - *void surface\_unref(surface)* *Surface \*surface;* Delete a previously created surface. - *void surface\_basic\_shader(surface, ambient, red, grn, blu, specular, c3, opred, opgrn, opblu)* *Surface \*surface;*\ *double ambient;*\ *double red, grn, blu;*\ *double specular;*\ *double c3;*\ *double opred, opgrn, opblu;* Set *surface* to be shaded by the basic shader and use the other parameters as values in the *Surf\_desc* struct. - *void surface\_set\_shader(surface, surf\_desc, shader)* *Surface \*surface;*\ *void \*surf\_desc;*\ *Shader \*shader;* Set the surface *surface* to be shaded with the shading function *shader* using the surface description *surf\_desc*. - *Object \*object\_create()* Create an empty object. - *void object\_unref(obj)* *Object \*obj;* Delete an object, i.e. the memory used by *obj* and all its subobjects and surfaces are recursively freed. This function used to be called *object\_delete()* and that function is also avaliable for compatibility, it will however be removed in future versions. - *void object\_add\_surface(obj, surf)* *Object \*obj;*\ *Surface \*surf;* Add the surface *surf* to the object *obj*. - *bool object\_sub\_surface(obj, surf)* *Object \*obj;*\ *Surface \*surf;* Remove the surface *surf* from the object *obj*. Returns *FALSE* if the surface was not found in the object. - *void object\_add\_subobj(obj, subobj)* *Object \*obj;*\ *Object \*subobj;* Add the subobject *subobj* to the object *obj*. - *bool object\_sub\_subobj(obj, subobj)* *Object \*obj;*\ *Object \*subobj;* Remove the subobject *subobj* from the object *obj*. Returns *FALSE* if the subobject was not found in the object. - *Object \*object\_instance(obj)* *Object \*obj;* Create a new instance of a previously defined object. The lists of surfaces and subobjects in *obj* are not copied, only a new reference with its own transformation matrix is created. - *Object \*object\_dup(obj)* *Object \*obj;* Copy recursively an object and its subobjects. The surfaces in the object tree are not copied, only new references to them are made. - *Object \*object\_deep\_dup(obj)* *Object \*obj;* Copy the entire tree for the object *obj*, including subobjects and all surfaces, polygons and vertices. ## Object transformations - *Transf\_mat \*object\_get\_transf(obj, matrix)* *Object \*obj;*\ *Transf\_mat \*matrix;* Return the transformation matrix currently stored in the object *obj*. If *matrix* is not NULL, the transformation matrix will be copied to that location and a pointer to it (identical to *matrix*) is returned. If *matrix* is NULL a new matrix will be allocated, the transformation matrix copied into it and a pointer to the new matrix is returned.\ - *void object\_set\_transf(obj, matrix)* *Object \*obj;*\ *Transf\_mat \*matrix;* Set the transformation matrix of the object *obj* to *matrix*.\ - *void object\_clear\_transf(obj)* *Object \*obj;* Set the transformation matrix of the object *obj* to the unit matrix.\ - *void object\_rot\_x(obj, ang)* *Object \*obj;*\ *double ang;* Rotate the object *obj* the angle *ang* about the X axis. *ang* is expressed in radians. - *void object\_rot\_y(obj, ang)* *Object \*obj;*\ *double ang;* Rotate the object *obj* the angle *ang* about the Y axis. *ang* is expressed in radians. - *void object\_rot\_z(obj, ang)* *Object \*obj;*\ *double ang;* Rotate the object *obj* the angle *ang* about the Z axis. *ang* is expressed in radians. - *void object\_rot(obj, point, vec, ang)* *Object \*obj;*\ *Vector \*point;*\ *Vector \*vec;*\ *double ang;* Rotate the object *obj* the angle *ang* about the line given by the point *point* and the vector *vec*. *ang* is expressed in radians. - *void object\_scale(obj, xscale, yscale, zscale)* *Object \*obj;*\ *double xscale, yscale, zscale;* Scale the object *obj* with the scaling factors *xscale,yscale* and *zscale* in the main directions respectively. - *void object\_move(obj, dx, dy, dz)* *Object \*obj;*\ *double dx, dy, dz;* Move (translate) the object *obj dx, dy* and *dz* in the three main directions, respectively. - *void object\_transform(obj, matrix)* *Object \*obj;*\ *Transf\_mat \*matrix;* Post multiply the matrix *matrix* into the transformation matrix of the object *obj*. ## Lights - *Lightsource \*lightsource\_create(x, y, z, red, green, blue, type)* *double x, y, z;*\ *double red, green, blue;*\ *int type;* Create a new lightsource.The type specified in *type* should be either *LIGHT\_DIRECTION* or *LIGHT\_POINT*. - *Lightsource \*spotlight\_create(x1, y1, z1, x2, y2, z2, opening, red, green, blue, type, shadow)* *double x1, y1, z1;*\ *double x2, y2, z2;*\ *double opening;*\ *double red, green, blue;*\ *int type;*\ *bool shadow;* Create a new spotlight. *type* should be either *SPOT\_SHARP* or *SPOT\_SOFT*. - *void light\_destruct(light)* *Lightsource \*light;* Release the memory used by a lightsource or a spotlight. - *void lightsource\_put(lightsrc, x, y, z);* *Lightsource \*lightsrc;*\ *double x, y, z;* Specify a new position or direction to a lightsource. - *void spotlight\_pos(spot, x, y, z);* *Lightsource \*spot;*\ *double x, y, z;* Specify a new position for a spotlight. - *void spotlight\_at(spot, x, y, z);* *Lightsource \*spot;*\ *double x, y, z;* Specify a new point that a spotlight is pointing at. - *void spotlight\_opening(spot, opening);* *Lightsource \*spot;*\ *double opening;* Specify a new opening angle for a spotlight. - *void spotlight\_shadows(spot, flag);* *Lightsource \*spot;*\ *bool flag;* Turn shadow casting on or off for a spotlight. - *void light\_color(light, red, green, blue);* *Lightsource \*light;*\ *double red, green, blue;* Change the color of the light emitted from a lightsource or a spotlight. - *void light\_active(light, flag);* *Lightsource \*light;*\ *bool flag;* Turn a lightsource or a spotlight on or off. - *double light\_eval(light, position, light\_vector);* *Lightsource \*light;*\ *Vector \*position;*\ *Vector \*light\_vector;* Evaluate how much light from a lightsource or a spotlight that reaches a point and calculate a vector from the light to the light. ## Cameras - *Camera \*camera\_create()* Create a new virtual camera. - *void camera\_destruct(camera)* *Camera \*camera;* Release the memory used by a virtual camera. - *void camera\_position(camera, x, y, z)* *Camera \*camera;*\ *double x, y, z;* Define the position of a camera. - *void camera\_look\_at(camera, x, y, z)* *Camera \*camera;*\ *double x, y, z;* Define the point a camera is looking at. - *void camera\_up(camera, x, y, z)* *Camera \*camera;*\ *double x, y, z;* Define the up vector of the camera. - *void camera\_focal(camera, ratio)* *Camera \*camera;*\ *double ratio;* Define the focal ratio of a camera. - *camera\_params(camera, x, y, z, to\_x, to\_y, to\_z, up\_x, up\_y, up\_z, focal\_ratio)* *Camera \*camera;*\ *double x, y, z;*\ *double to\_x, to\_y, to\_z;*\ *double up\_x, up\_y, up\_z;*\ *double focal\_ratio;* Set all parameters of a camera in one call. ## Rendering - *void render\_image\_file(width, height, file, mode, oversampling)* *int width, height;*\ *FILE \*file;*\ *int mode;*\ *int oversampling;* Render an image of the current scene into a file. *mode* should be one of *PHONG, GOURAUD, FLAT* or *LINE*. - *void render\_field\_file(width, height, file, mode, oversampling, field)* *int width, height;*\ *FILE \*file;*\ *int mode;*\ *int oversampling;*\ *int field;* Render the current scene as a field (half frame) into a file. *mode* should be one of *PHONG, GOURAUD, FLAT* or *LINE* and *field* should be either *ODD* or *EVEN*. - *void render\_image\_func(width, height, pix\_func, data, mode, oversampling)* *int width, height;*\ *void (\*pix\_func)();*\ *void \*data;*\ *int mode;*\ *int oversampling;* Render an image of the current scene into any device. *mode* should be one of *PHONG, GOURAUD, FLAT* or *LINE*. - *void render\_field\_func(width, height, pix\_func, data, mode, oversampling, field)* *int width, height;*\ *void (\*pix\_func)();*\ *void \*data;*\ *int mode;*\ *int oversampling;*\ *int field;* Render the current scene as a field (half frame) into any device. *mode* should be one of *PHONG, GOURAUD, FLAT* or *LINE* and *field* should be either *ODD* or *EVEN*. - *void sipp\_render\_terminate()* Abort (hopefully gracefully) an ongoing rendering. This is designed to be called from the callback function. ## Shadowmaps - *void shadowmaps\_create(size);* *int size;* Render the depthmaps for the current scene and the currently active lightsources. - *void shadowmaps\_destruct();* Delete all active depthmaps. ## The basic shader - *void basic\_shader(world, normal, texture, view\_vec, lights, surface, color, opacity)* *Vector \*world;*\ *Vector \*normal;*\ *Vector \*texture;*\ *Vector \*view\_vec;*\ *Lightsource \*lights;*\ *Surf\_desc \*surface;*\ *Color \*color;*\ *Color \*opacity;* The basic shader function that is provided with the library. ## SEE ALSO [sipp\_shaders(3)](/sipp_shaders/3.md) - a number of shaders for SIPP.\ [sipp\_geometric(3)](/sipp_geometric/3.md) - Vector and matrix functions for SIPP.\ [sipp\_primitives(3)](/sipp_primitives/3.md) - a collection of geometric 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)