pfuPath(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages pfuPath(3pf)NAME
pfuNewPath, pfuClosePath, pfuCopyPath, pfuSharePath, pfuPrintPath,
pfuFollowPath, pfuAddArc, pfuAddDelay, pfuAddFile, pfuAddFillet,
pfuAddPath, pfuAddSpeed - Simple path-following utility
FUNCTION SPECIFICATION
#include <Performer/pfutil.h>
pfuPath * pfuNewPath(void);
pfuPath * pfuClosePath(pfuPath *path);
pfuPath * pfuCopyPath(pfuPath *copy);
pfuPath * pfuSharePath(pfuPath *share);
int pfuPrintPath(pfuPath *path);
int pfuFollowPath(pfuPath *path, float seconds, pfVec3 where,
pfVec3 orient);
int pfuAddArc(pfuPath *path, pfVec3 center, float radius,
pfVec2 angles);
int pfuAddDelay(pfuPath *path, float delay);
int pfuAddFile(pfuPath *path, char *name);
int pfuAddFillet(pfuPath *path, float radius);
int pfuAddPath(pfuPath *path, pfVec3 start, pfVec3 final);
int pfuAddSpeed(pfuPath *path, float desired, float rate);
DESCRIPTION
The pfuPath functions provide a simple way to move one or more simulated
vehicles or eyepoints along a mathematically defined path. The path is a
general series of arcs and line segments. Once a path is created, it can
be followed each simulation frame to provide position and orientation
information.
pfuNewPath allocates and initializes a new pfuPath structure. Once the
path is opened, segments (both straight and curved) can be added using
the pfuAddPath and pfuAddArc commands as described below. The initial
path speed is set at 1.0 database units per second.
pfuClosePath connects the end point of the final segment of path path
with the start point of the path's first segment. This creates a closed
(also known as looping) path that can be followed endlessly. Paths can be
either open or closed, but they should only be closed once. The closed
path is returned.
Page 1
pfuPath(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages pfuPath(3pf)
pfuCopyPath creates and returns a new pfuPath structure that has path
segments which are an exact copy of those in the path indicated by the
path argument. This is a deep copy, and will create a new instance of
each element in the original path definition.
pfuSharePath creates a new pfuPath structure, but causes the linked list
of path segments in the path structure path to be shared by both old and
new path structures. This allows multiple simulated objects to follow the
same path without the redundant allocation of path storage, and also
allows changes to the path segment definition to effect all pfuPath
structures that share it.
pfuPrintPath prints the path following control information for path
object path, and then prints the definition of each segment in the path
itself. All printing is done using the OpenGL Performer pfNotify
mechanism with a severity level of PFNFY_DEBUG.
pfuFollowPath performs the actual simulation of moving an object along
the path indicated by path. The seconds argument specifies the simulated
duration, and internal data in the pfuPath structure supplies the speed.
From this time and speed information, the vehicle's simulated distance of
travel is computed. Then, the vehicle is moved this distance along the
path segments defined within the pfuPath object. The resulting simulated
position is returned in the pfVec3 argument where and the orientation of
the vehicle is returned in orient.
pfuAddArc adds a circular arc path segment to the pfuPath structure path.
The arc is defined by the center and radius values, and a pair of angles.
The first angle, angle[0], is the start angle for the path, and is a
point on the circle defined by center and radius with the indicated
counterclockwise angle from the positive X axis. The second angle,
angle[1], represents the turn angle, the angle between the arc's start
and end points as measured from the designated center point. Positive
turn angles indicate counterclockwise turns, and negative angles
represent clockwise turns. An arc from the +X axis to the +Y axis would
be defined with a start angle of 0 degrees and a turn angle of 90
degrees. The same arc in the opposite direction of travel is defined by a
start angle of 90 degrees and a turn angle of -90 degrees.
pfuAddDelay adds a zero-length segment to path that causes the simulated
vehicle to stop for the delay seconds at that point in the path. Once
this much simulated time elapses, the simulation will continue with the
next segment in the path. Delay segments can be used to simulate motor
vehicles paused waiting for traffic signals and similar latent delay
sources along a path.
pfuAddFile adds a series of path segments defined by a simple ASCII file
format to the pfuPath structure path. This function provides an easy way
to load user specified paths for vehicles into simulation applications,
and is used in the popular SGI "Performer Town" demonstration program to
load the paths for the truck into the program.
Page 2
pfuPath(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages pfuPath(3pf)
pfuAddFillet is used to create circular arcs that join two adjacent
straight path segments. Fillet creation is a three step process.
1. A straight segment is added to a path using pfuAddPath. This is
the segment that will lead into the fillet.
2. A fillet request is added using pfuAddFillet. The fillet's
radius is defined in this call.
3. A second straight segment is added, again with pfuAddPath. This
segment must start where the segment of step one ended.
When the second segment is added in step three, a test is performed to
see if the first point in the second segment has the same X, Y, and Z
values as the last point in the previous segment. If so, and if there is
a fillet request between the two segments, then a matching fillet of the
specified radius is computed. In addition, the endpoints (and thus
lengths) of the two straight segments are adjusted so as to match with
the fillet endpoints.
For example, the request
line from (0,0) to (1,0)
fillet of radius 0.25
line from (1,0) to (1,1)
will cause the fillet arc and line segment lengths to be automatically
computed as
line from (0,0) to (0.75,0)
fillet of radius 0.25 with center (0.75,0.25) and angles 270 and 90.
line from (1,0.25) to (1,1)
This automatic fillet construction is seen to be very convenient once the
alternative manual fillet construction is attempted. When the fillet
radius is too large to allow the arc to be created (as would be the case
in the example above with a radius greater than one), a fillet is not
constructed and a sharp turn will exist in the path.
pfuAddPath adds a straight line segment to path. The line segment is
defined as extending from start to final. As mentioned above, if the
segment preceding the line segment is an unevaluated fillet, and the
value of start is equal to that of the final point of the segment before
the fillet, then an automatic fillet will be constructed if the fillet's
radius specification is sufficiently small to allow it.
pfuAddSpeed adds a speed changing segment to path. The new speed is
indicated by desired and the rate of adjustment from the current path
speed to the new speed is given by rate.
Page 3
pfuPath(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages pfuPath(3pf)NOTES
The libpfutil source code, object code and documentation are provided as
unsupported software. Routines are subject to change in future releases.
SEE ALSO
pfNotify
Page 4
