pfPlane(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfPlane(3pf)NAME
pfMakePtsPlane, pfMakeNormPtPlane, pfDisplacePlane, pfClosestPtOnPlane,
pfPlaneIsectSeg, pfHalfSpaceIsectSeg, pfHalfSpaceContainsPt,
pfHalfSpaceContainsBox, pfHalfSpaceContainsSphere,
pfHalfSpaceContainsCyl, pfOrthoXformPlane - Set and operate on planes
FUNCTION SPECIFICATION
#include <Performer/pr.h>
void pfMakePtsPlane(pfPlane *dst, const pfVec3 pt1, const pfVec3 pt2,
const pfVec3 pt3);
void pfMakeNormPtPlane(pfPlane *dst, const pfVec3 norm,
const pfVec3 pos);
void pfDisplacePlane(pfPlane *dst, float d);
void pfClosestPtOnPlane(const pfPlane *pln, const pfVec3 pt,
pfVec3 dst);
int pfPlaneIsectSeg(const pfPlane *pln, const pfSeg *seg, float *d);
int pfHalfSpaceIsectSeg(const pfPlane* hs, const pfSeg* seg,
float* d1, float* d2);
int pfHalfSpaceContainsPt(const pfPlane* p, const pfVec3 pt);
int pfHalfSpaceContainsBox(const pfPlane* p, const pfBox *box);
int pfHalfSpaceContainsSphere(const pfPlane *hs, const pfSphere *sph);
int pfHalfSpaceContainsCyl(const pfPlane *hs, const pfCylinder *cyl);
void pfOrthoXformPlane(pfPlane *dst, const pfPlane *pln,
const pfMatrix xform);
typedef struct
{
pfVec3 normal;
float offset;
} pfPlane;
DESCRIPTION
A pfPlane represents an infinite 2D plane as a normal and a distance
offset from the origin in the normal direction. A point on the plane
satisfies the equation normal dot (x, y, z) = offset. pfPlane is a
public struct whose data members normal and offset may be operated on
directly.
Page 1
pfPlane(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfPlane(3pf)
pfMakePtsPlane sets dst to the plane which passes through the three
points pt1, pt2 and pt3.
pfMakeNormPtPlane sets dst to the plane which passes through the point pt
with normal norm.
pfDisplacePlane moves the plane dst by a distance d in the direction of
the plane normal.
pfClosestPtOnPlane returns in dst the closest point to pt which lies in
the plane pln. The line segment connecting pt and dst is perpendicular
to pln.
pfHalfSpaceContainsPt returns TRUE or FALSE depending on whether the
point pt is in the interior of the specified half-space. The half-space
is defined with plane normal pointing to the exterior.
pfHalfSpaceContainsSphere, pfHalfSpaceContainsBox and
pfHalfSpaceContainsCyl test whether the half space specified by pfPlane
contains a non-empty portion of the volume specified by the second
argument, a sphere, box or cylinder, respectively.
The return value from the these functions is the OR of one or more bit
fields. The returned value may be:
PFIS_FALSE:
The intersection of the primitive and the half space is empty.
PFIS_MAYBE:
The intersection of the primitive and the half space might be
non-empty.
PFIS_MAYBE | PFIS_TRUE:
The intersection of the primitive and the half space is
definitely non-empty.
PFIS_MAYBE | PFIS_TRUE | PFIS_ALL_IN:
The primitive is non-empty and lies entirely inside the half
space.
indicating indicate that the second argument is entirely outside,
potentially partly inside, partially inside or entirely inside the half
space specified by the pfPlane.
pfPlaneIsectSeg tests the line segment seg for intersection with the half
space pln. The possible test results are:
PFIS_FALSE:
seg lies entirely in the exterior.
Page 2
pfPlane(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfPlane(3pf)
PFIS_MAYBE | PFIS_TRUE | PFIS_START_IN:
The starting point of seg lies in the interior.
PFIS_MAYBE | PFIS_TRUE | PFIS_END_IN:
The ending point of seg lies in the interior.
If d is non-NULL, on return it contains the position along the line
segment (0 <= d <= seg->length) at which the intersection occurred.
pfHalfSpaceIsectSeg intersects the line segment seg with the half space
hs and has return values the same as pfPlaneIsectSeg except that it also
returns a non-zero value when both points are inside the half-space. In
this case it returns:
PFIS_MAYBE | PFIS_TRUE | PFIS_ALL_IN | PFIS_START_IN | PFIS_END_IN:
Both end points of seg lie in the interior.
If d1 and d2 are non-NULL, on return from pfHalfSpaceIsectSeg they
contain the starting and ending positions of the line segment (0 <= d1 <=
d2 <= seg->length) intersected with the half space.
pfOrthoXformPlane sets dst to the plane as transformed by the orthogonal
transformation xform; dst = pln * xform. If xform is not an orthogonal
transformation the results are undefined.
NOTES
The bit fields returned by the contains functions are structured so that
bitwise AND-ing the results of sequential tests can be used to compute
composite results, e.g. testing exclusion against a number of half
spaces.
SEE ALSO
pfBox, pfMatrix, pfSeg, pfSphere, pfVec3
Page 3
