sipp - simple polygon processor, a 3d-graphics library

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

sipp_shaders(3) - a number of shaders for SIPP.

sipp_geometric(3) - Vector and matrix functions for SIPP.

sipp_primitives(3) - a collection of geometric 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)