pfFrustum(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
NAMEpfFrustum - Operations on frusta
FUNCTION SPECIFICATION
#include <Performer/pr/pfGeoMath.h>
pfFrustum::pfFrustum()
static pfType * pfFrustum::getClassType(void);
void pfFrustum::makePersp(float left, float right,
float bottom, float top);
void pfFrustum::makeInfPersp(float left, float right,
float bottom, float top);
void pfFrustum::makeOrtho(float left, float right,
float bottom, float top);
void pfFrustum::makeSimple(float fov);
int pfFrustum::getFrustType(void);
void pfFrustum::getFOV(float* fovh, float* fovv);
void pfFrustum::setAspect(int which,
float widthHeightRatio);
float pfFrustum::getAspect(void);
void pfFrustum::setNearFar(float near, float far);
void pfFrustum::getNearFar(float* near, float* far);
void pfFrustum::getNear(pfVec3 &ll, pfVec3 &lr, pfVec3 &ul,
pfVec3 &ur);
void pfFrustum::getFar(pfVec3 &ll, pfVec3 &lr, pfVec3 &ul,
pfVec3 &ur);
int pfFrustum::getEye(pfVec3 &eye);
void pfFrustum::getPtope(pfPolytope *ptope);
void pfFrustum::getGLProjMat(pfMatrix &mat);
void pfFrustum::apply(void);
int pfFrustum::contains(const pfVec3 &pt);
Page 1
pfFrustum(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
int pfFrustum::contains(const pfBox *box);
int pfFrustum::contains(const pfSphere *sph);
int pfFrustum::contains(const pfCylinder *cyl);
void pfFrustum::orthoXform(const pfFrustum* src,
const pfMatrix &mat);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfFrustum is derived from the parent class
pfPolytope, so each of these member functions of class pfPolytope are
also directly usable with objects of class pfFrustum. This is also true
for ancestor classes of class pfPolytope.
pfType* pfPolytope::getClassType(void);
int pfPolytope::getNumFacets(void);
int pfPolytope::setFacet(int i, const pfPlane *facet);
int pfPolytope::getFacet(int i, pfPlane *facet);
int pfPolytope::removeFacet(int i);
void pfPolytope::orthoXform(const pfPolytope *src,
const pfMatrix &mat);
int pfPolytope::contains(const pfVec3 &pt);
int pfPolytope::contains(const pfSphere *sphere);
int pfPolytope::contains(const pfBox *box);
int pfPolytope::contains(const pfCylinder *cyl);
int pfPolytope::contains(const pfPolytope *ptope1);
Since the class pfPolytope is itself derived from the parent class
pfObject, objects of class pfFrustum can also be used with these
functions designed for objects of class pfObject.
void* pfObject::operator new(size_t);
void* pfObject::operator new(size_t, void *arena);
void* pfObject::operator new(size_t, pfFluxMemory *fmem);
void pfObject::setUserData(void *data);
void pfObject::setUserData(int slot, void *data);
void* pfObject::getUserData(pfObject *obj);
void* pfObject::getUserData(pfObject *obj, int slot);
int pfObject::getNumUserData();
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfFrustum can also be used with these
functions designed for objects of class pfMemory.
void* pfMemory::getData(const void *ptr);
pfType * pfMemory::getType();
int pfMemory::isOfType(pfType *type);
Page 2
pfFrustum(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
int pfMemory::isExactType(pfType *type);
const char * pfMemory::getTypeName();
int pfMemory::copy(pfMemory *src);
int pfMemory::compare(const pfMemory *mem);
void pfMemory::print(uint which, uint verbose, char *prefix,
FILE *file);
int pfMemory::getArena(void *ptr);
void* pfMemory::getArena();
int pfMemory::ref();
int pfMemory::unref();
int pfMemory::unrefDelete();
int pfMemory::unrefGetRef();
int pfMemory::getRef();
int pfMemory::checkDelete();
int pfMemory::isFluxed();
void * pfMemory::getArena();
int pfMemory::getSize();
DESCRIPTION
A pfFrustum represents a viewing and or culling volume bounded by left,
right, top, bottom, near and far planes.
new(arena) allocates a pfFrustum from the specified memory arena, or from
the process heap if arena is NULL. new allocates a pfFrustum from the
default memory arena (see pfGetSharedArena). Like other pfObjects,
pfFrusta cannot be created statically, automatically on the stack or in
arrays and should be deleted with pfDelete rather than the delete
operator.
A new pfFrustum defaults to a simple perspective frustum (see
::makeSimple) with FOV = 45 degrees, and near and far distances of 1 and
1000.
pfFrustum::getClassType returns the pfType* for the class pfFrustum. The
pfType* returned by pfFrustum::getClassType is the same as the pfType*
returned by invoking the virtual function getType on any instance of
class pfFrustum. Because OpenGL Performer allows subclassing of built-in
types, when decisions are made based on the type of an object, it is
usually better to use the member function isOfType to test if an object
is of a type derived from a Performer type rather than to test for strict
equality of the pfType*'s.
pfFrustum::makePersp configures the pfFrustum as a perspective frustum
with the eye at (0,0,0) and the points (left, near, bottom) and (right,
near, top) being the lower-left and upper-right corners of the viewing
plane. The coordinate system used is: left -> right = +X axis, near ->
far = +Y axis, bottom -> top = +Z axis. The far plane lies at Y = far.
Note that the field of view of a frustum configured with
pfFrustum::makePersp is dependent on the current near plane distance.
However, subsequent changes to the near plane distance with
pfFrustum::setNearFar do not affect the field of view, simplifying clip
plane modification.
Page 3
pfFrustum(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
pfFrustum::makePersp is similar to the IRIS GL window(3g) command and can
generate off-axis projections that are often used for stereo and "video-
wall" displays. With an off-axis frustum, the line from the eyepoint
passing through the center of the image is not perpendicular to the
projection plane.
Example 1:
/*
* Make two off-axis projections which together provide
* horizontal and vertical FOVs of 90 and 45 degrees.
*/
t = pfTan(22.5f);
left->setNearFar( 1.0f, 1000.0f);
left->makePersp(-1.0f, 0.0f, -t, t);
right->setNearFar(1.0f, 1000.0f);
right->makePersp(0.0f, 1.0f, -t, t);
pfFrustum::makeInfPersp configures the pfFrustum as an infinite
perspective frustum (a frustum with no far plane) for projection.
However, this frustum type still culls against the far plane. This type
of frustum may be useful for shadow volumes.
pfFrustum::makeOrtho configures the pfFrustum as an orthogonal frustum.
The 6 sides of the frustum are: x = left, x = right, z = bottom, z = top,
y = near, y = far. pfFrustum::makeOrtho is similar to the IRIS GL
ortho2(3g) command. The near and far distances of an orthogonal frustum
are set by pfFrustum::setNearFar.
pfFrustum::makeSimple configures the pfFrustum as an on-axis perspective
frustum with horizontal and vertical fields-of-view of fov degrees. With
an on-axis frustum, the line connecting the center of projection with the
eyepoint is perpendicular to the projection plane. pfFrustum::makeSimple
is similar to the IRIS GL perspective(3g) command. The near and far
distances of a simple frustum are set by pfFrustum::setNearFar. For
viewports with non-square aspect ratios, pfFrustum::setAspect may be used
to automatically fit either the horizontal or vertical fields of view to
the viewport (see below).
pfFrustum::getFrustType returns a symbolic token indicating the frustum
type of the pfFrustum and is one of: PFFRUST_SIMPLE, PFFRUST_ORTHOGONAL,
or PFFRUST_PERSPECTIVE. The frustum type is set by the
pfFrustum::make<*> routines. Note that it is possible to make a simple
frustum with pfFrustum::makePersp if left == -right and bottom == -top.
pfFrustum::setNearFar sets the near and far distances of the pfFrustum.
It will also recalculate the frustum's geometry based on the frustum
type. If frust is perspective, its field of view will not be changed,
only the near and far planes will be modified. pfFrustum::getNearFar
Page 4
pfFrustum(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
copies the near and far distances of the pfFrustum into near and far.
pfFrustum::setAspect adjusts the horizontal or vertical extent of the
pfFrustum to fit the aspect ratio specified by widthHeightRatio. which
is a symbolic token specifying how to modify frust and is one of:
PFFRUST_CALC_NONE Disable aspect ratio calculation
PFFRUST_CALC_HORIZ Modify horizontal extent of frustum to
match the aspect ratio
PFFRUST_CALC_VERT Modify vertical extent of frustum to
match the aspect ratio
pfFrustum::setAspect is useful for matching a frustum to a viewport:
Example 2:
getviewport(&l, &r, &b, &t);
aspect = (float)(r - l) / (float)(t - b);
/*
* Fit vertical frustum extent to viewport so that horizontal
* FOV is 45 degrees and vertical is based on 'aspect'.
*/
frust->makeSimple(45.0f);
frust->setAspect(PFFRUST_CALC_VERT, aspect);
Frustum aspect ratio matching is not persistent. You must call
pfFrustum::setAspect each time the frustum changes shape in order to
maintain matched frustum/viewport.
pfFrustum::getAspect returns the aspect ratio of the pfFrustum.
pfFrustum::getFOV copies the total horizontal and vertical fields of view
into fovh and fovv respectively. The fields of view for an orthogonal
frustum are both 0.0.
pfFrustum::getNear returns the four corners of the near (viewing or
projection) plane putting the lower-left, lower-right, upper-left and
upper-right vertices into ll, lr, ul, and ur, respectively.
pfFrustum::getFar returns the four corners of the far plane putting the
lower-left, lower-right, upper-left and upper-right vertices into ll, lr,
ul, and ur, respectively.
pfFrustum::getEye copies the eye position of the frustum the pfFrustum
into eye.
pfFrustum::getPtope copies the 6 half spaces which define the pfFrustum
Page 5
pfFrustum(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
into the pfPolytope ptope.
pfFrustum::getGLProjMat returns the projection matrix corresponding to
the pfFrustum in the coordinate system of the Graphics Library, ignoring
any transformations applied to frust with pfFrustum::orthoXform.
pfFrustum::apply configures the hardware projection matrix with the
projection defined by the pfFrustum. Modifications made to frust do not
have effect until pfFrustum::apply is called.
pfFrustum::apply is a display-listable command. If a pfDispList has been
opened by pfDispList::open, pfFrustum::apply will not have immediate
effect but will be captured by the pfDispList and will only have effect
when that pfDispList is later drawn with pfDispList::draw.
pfFrustum::contains(const pfVec3 pt, ...) returns TRUE or FALSE
depending on whether the point pt is in the interior of the specified
frustum.
pfFrustum::contains(struct pfBox *), pfFrustum::contains(struct pfSphere
*), and pfFrustum::contains(struct pfCylinder *) test whether the
specified pfFrustum contains a non-empty portion of the volume specified
by the argument, a box, sphere or cylinder, respectively. The various
member functions pfFrustum::contains test whether the pfFrustum contains
a non-empty portion of a box, sphere, or cylinder.
The return value from 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 pfFrustum is empty.
PFIS_MAYBE: The intersection of the primitive and the
pfFrustum might be non-empty.
PFIS_MAYBE | PFIS_TRUE: The intersection of the primitive and the
pfFrustum is definitely non-empty.
PFIS_MAYBE | PFIS_TRUE | PFIS_ALL_IN: The primitive
is non-empty and lies entirely inside the pfFrustum.
The primary use of pfFrustum::contains within OpenGL Performer is in
culling the database to the view frustum each frame, where speed is
paramount. If this computation cannot be done easily, the function
returns PFIS_MAYBE.
pfFrustum::orthoXform transforms the frustum using the matrix mat: dst =
src * mat. If mat is not orthogonal the results are undefined.
Page 6
pfFrustum(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
NOTESpfFrustum construction orients the frustum with +Z up, +X to the right,
and +Y into the screen which is different than the OpenGL viewing
coordinate systems which has +Y up, +X to the right and -Z into the
screen.
SEE ALSO
pfBox, pfDelete, pfDispList, pfMatrix, pfObject, pfPlaneIsectSeg,
pfPolytope, pfSphere, pfState, pfVec3, ortho, perspective, window
Page 7
