sipp(3)

NAME

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

SYNOPSIS

#include <sipp.h>
[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 ren

dered 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 light

sources can be of three basic types: directional, point or spot

light. 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 pro

vide his own shading function for a surface. This makes it easy

to experiment with various shading models and to do special ef

fects. The shader controls both the color and opacity of a sur

face. 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 any

thing 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 transfor

mation 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 ac

cessed directly, but rather through the abstract functions de

scribed 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 in

cluded 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 defini

tion 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 sur

face */

} Surf_desc;

Surf_desc_hdr

Header used on surface descriptions when an appli

cation 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 light

source. 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 re

turns 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 speci

fied 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 de

scription 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 shad

ing 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 func

tion 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. Re

turns 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 ob

ject. The lists of surfaces and subobjects in obj are not copied,

only a new reference with its own transformation matrix is creat

ed.

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 ma

trix will be copied to that location and a pointer to it (identi

cal 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 ax

is. 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 ax

is. 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 ax

is. 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 transfor

mation 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 spot

light.

void lightsource_put(lightsrc, x, y, z);

Lightsource *lightsrc;
double x, y, z;

Specify a new position or direction to a light

source.

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 light

source 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 de

vice. 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) - 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.

AUTHORS

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

3 July , 1992

SIPP(3)