pointlist(3)

NAME
pointlist - library for getting and setting the list of points in an OOGL object.

SYNOPSIS
#include "pointlist.h"
void pointlist_init();
HPoint3 *PointList_get( Geom *geom, Transform T, int CoordSystem );
HPoint3 *PointList_fillin( Geom *geom, Transform T, int CoordSystem,
	HPoint3 *plist );
void PointList_set( Geom *geom, int CoordSystem, HPoint3 *plist );
int PointList_length( Geom *geom );

DESCRIPTION

The pointlist library contains several routines for getting and setting the list of points in a Geomview object. This is useful for performings operations which operate solely on the points of an object, for example, transforming the entire object by transforming its points. pointlist_init() must be called prior to calling any of the other routines.

The value CoordSystem is the coordinate system in which the coordinates are specified. It may be set to one of two values declared in pointlist.h: POINTLIST_SELF and POINTLIST_PRIMITIVE. POINTLIST_SELF indicates that the coordinates will be in the coordinate system of the given Geom. POINTLIST_PRIMITIVE indicates that the coordinates will be in the coordinate system of the lowest-level OOGL primitive. These specifications are analogous to the keywords "self" and "primitive" in the Geomview command language (See geomview(5)). The discerning user will note that these coordinate systems will only cause different results if the geom is an inst or a list containing an inst. The not-so-discerning user needn't worry about it.

PointList_get() and PointList_fillin() have very similar functions. PointList_get() takes a geom and returns a pointer to an allocated array of HPoint3's containing the points of the object in the specified coordinate system. PointList_fillin() puts the points of the geom in the array plist and returns plist.

The arguement T is used internally by the routines (since they are recursive). Passing in anything other than the identity matrix is very very unwise and will (at best) probably produce unexpected results.

The only slightly special case is that of an inst containing more than one appearance of the base geom. In the inst data strucutre, there is actually only one list of points for the base geom no matter how many times it is instanced. In spite of this, the routines will return a list of points which contains the points of the base geom instanced once for each transform in the inst. For example, a inst object whose base geom is a cube and which contains two transforms will return a point list sixteen points long, since a cube has eight points.

PointList_set() is used to set the points to a geom to those contained in plist. In general, plist will be an array returned by PointList_get and somehow transformed by the calling program. The only slightly mysterious aspect of this routine is its handling of inst objects with more than one appearance of the base geom. In this case, the first set of points in the plist is used to redefine the points of the base geom. The rest of plist is ignored.

PointList_length() returns the total number of points in a geom, which is the length of the array returned by PointList_get() and the length of the plist arrays that must be passed to PointList_fillin() and PointList_set().

LINKING
To link your program with the pointlist library, you should specify -lpointlist followed by the usual list of OOGL libraries, as in
cc -L${LIBDIR} prog.c -lpointlist ${ALLOOGLLIBS}

SEE ALSO
geomview(5)

AUTHOR
Celeste Fowler			email:  fowler@geom.umn.edu
The Geometry Center		phone:  (612) 626-8304
1300 South Second Street
Minneapolis, MN  55454