pointlist(3) Geometry Center (October 12, 1992) 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
Page 1 (printed 12/22/98)
pointlist(3) Geometry Center (October 12, 1992) pointlist(3)
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
Page 2 (printed 12/22/98)
