pfFrustum(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFrustum(3pf)NAME
pfNewFrust, pfGetFrustClassType, pfMakePerspFrust, pfMakeInfPerspFrust,
pfMakeOrthoFrust, pfMakeSimpleFrust, pfGetFrustType, pfGetFrustFOV,
pfFrustAspect, pfGetFrustAspect, pfFrustNearFar, pfGetFrustNearFar,
pfGetFrustNear, pfGetFrustFar, pfGetFrustEye, pfGetFrustPtope,
pfGetFrustGLProjMat, pfApplyFrust, pfFrustContainsPt, pfFrustContainsBox,
pfFrustContainsSphere, pfFrustContainsCyl, pfOrthoXformFrust - Operations
on frusta
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfFrustum * pfNewFrust(void* arena);
pfType * pfGetFrustClassType(void);
void pfMakePerspFrust(pfFrustum* frust, float left, float right,
float bottom, float top);
void pfMakeInfPerspFrust(pfFrustm* frust, float left,
float right, float bottom, float top);
void pfMakeOrthoFrust(pfFrustum* frust, float left, float right,
float bottom, float top);
void pfMakeSimpleFrust(pfFrustum* frust, float fov);
int pfGetFrustType(const pfFrustum* frust);
void pfGetFrustFOV(const pfFrustum* frust, float* fovh,
float* fovv);
void pfFrustAspect(pfFrustum* frust, int which,
float widthHeightRatio);
float pfGetFrustAspect(const pfFrustum* frust);
void pfFrustNearFar(pfFrustum* frust, float near, float far);
void pfGetFrustNearFar(const pfFrustum* frust, float* near,
float* far);
void pfGetFrustNear(const pfFrustum* frust, pfVec3 ll,
pfVec3 lr, pfVec3 ul, pfVec3 ur);
void pfGetFrustFar(const pfFrustum* frust, pfVec3 ll, pfVec3 lr,
pfVec3 ul, pfVec3 ur);
int pfGetFrustEye(const pfFrustum* frust, pfVec3 eye);
Page 1
pfFrustum(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFrustum(3pf)
void pfGetFrustPtope(const pfFrustum* frust, pfPolytope *ptope);
void pfGetFrustGLProjMat(const pfFrustum* frust, pfMatrix mat);
void pfApplyFrust(const pfFrustum *frust);
int pfFrustContainsPt(const pfFrustum *fr, const pfVec3 pt);
int pfFrustContainsBox(const pfFrustum *frust,
const pfBox *box);
int pfFrustContainsSphere(const pfFrustum *fr,
const pfSphere *sph);
int pfFrustContainsCyl(const pfFrustum *frust,
const pfCylinder *cyl);
void pfOrthoXformFrust(pfFrustum* dst, 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. Casting an object
of class pfFrustum to an object of class pfPolytope is taken care of
automatically. This is also true for casts to objects of ancestor
classes of class pfPolytope.
int pfGetPtopeNumFacets(pfPolytope *ptope);
int pfPtopeFacet(pfPolytope *ptope, int i, const pfPlane *facet);
int pfGetPtopeFacet(pfPolytope *ptope, int i, pfPlane *facet);
int pfRemovePtopeFacet(pfPolytope *ptope, int i);
void pfOrthoXformPtope(pfPolytope *ptope, const pfPolytope *src,
const pfMatrix mat);
int pfPtopeContainsPt(const pfPolytope *ptope, const pfVec3 pt);
int pfPtopeContainsSphere(const pfPolytope *ptope,
const pfSphere *sphere);
int pfPtopeContainsBox(const pfPolytope *ptope, const pfBox *box);
int pfPtopeContainsCyl(const pfPolytope *ptope,
const pfCylinder *cyl);
int pfPtopeContainsPtope(const pfPolytope *ptope,
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 pfUserDataSlot(pfObject *obj, int slot, void *data);
void pfUserData(pfObject *obj, void *data);
Page 2
pfFrustum(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFrustum(3pf)
void* pfGetUserDataSlot(pfObject *obj, int slot);
void* pfGetUserData(pfObject *obj);
int pfGetNumUserData(pfObject *obj);
int pfGetNamedUserDataSlot(const char *name);
const char* pfGetUserDataSlotName(int slot);
int pfGetNumNamedUserDataSlots(void);
int pfGetGLHandle(pfObject *obj);
int pfDeleteGLHandle(pfObject *obj);
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.
pfType * pfGetType(const void *ptr);
int pfIsOfType(const void *ptr, pfType *type);
int pfIsExactType(const void *ptr, pfType *type);
const char * pfGetTypeName(const void *ptr);
int pfRef(void *ptr);
int pfUnref(void *ptr);
int pfUnrefDelete(void *ptr);
int pfUnrefGetRef(void *ptr);
int pfGetRef(const void *ptr);
int pfCopy(void *dst, void *src);
int pfDelete(void *ptr);
int pfIsFluxed(void *ptr);
int pfCompare(const void *ptr1, const void *ptr2);
void pfPrint(const void *ptr, uint which, uint verbose,
FILE *file);
void * pfGetArena(void *ptr);
PARAMETERS
frust identifies a pfFrustum.
DESCRIPTION
A pfFrustum represents a viewing and or culling volume bounded by left,
right, top, bottom, near and far planes.
pfNewFrust creates and returns a handle to a pfFrustum. arena specifies
a malloc arena out of which the pfFrustum is allocated or NULL for
allocation off the process heap. pfFrusta can be deleted with pfDelete.
A new pfFrustum defaults to a simple perspective frustum (see
pfMakeSimpleFrust) with FOV = 45 degrees, and near and far distances of 1
and 1000.
pfGetFrustClassType returns the pfType* for the class pfFrustum. The
pfType* returned by pfGetFrustClassType is the same as the pfType*
returned by invoking pfGetType 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 pfIsOfType to test if an object is of a type derived from a
Page 3
pfFrustum(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFrustum(3pf)
Performer type rather than to test for strict equality of the pfType*'s.
pfMakePerspFrust configures frust 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 pfMakePerspFrust is
dependent on the current near plane distance. However, subsequent changes
to the near plane distance with pfFrustNearFar do not affect the field of
view, simplifying clip plane modification.
pfMakePerspFrust 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);
pfFrustNearFar(left, 1.0f, 1000.0f);
pfMakePerspFrust(left, -1.0f, 0.0f, -t, t);
pfFrustNearFar(right, 1.0f, 1000.0f);
pfMakePerspFrust(right, 0.0f, 1.0f, -t, t);
pfMakeInfPerspFrust configures frust 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.
pfMakeOrthoFrust configures frust as an orthogonal frustum. The 6 sides
of the frustum are: x = left, x = right, z = bottom, z = top, y = near, y
= far. pfMakeOrthoFrust is similar to the IRIS GL ortho2(3g) command.
The near and far distances of an orthogonal frustum are set by
pfFrustNearFar.
pfMakeSimpleFrust configures frust 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. pfMakeSimpleFrust is similar
to the IRIS GL perspective(3g) command. The near and far distances of a
simple frustum are set by pfFrustNearFar. For viewports with non-square
aspect ratios, pfFrustAspect may be used to automatically fit either the
Page 4
pfFrustum(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFrustum(3pf)
horizontal or vertical fields of view to the viewport (see below).
pfGetFrustType returns a symbolic token indicating the frustum type of
frust and is one of: PFFRUST_SIMPLE, PFFRUST_ORTHOGONAL, or
PFFRUST_PERSPECTIVE. The frustum type is set by the pfMake<*>Frust
routines. Note that it is possible to make a simple frustum with
pfMakePerspFrust if left == -right and bottom == -top.
pfFrustNearFar sets the near and far distances of frust. 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. pfGetFrustNearFar copies the near and far
distances of frust into near and far.
pfFrustAspect adjusts the horizontal or vertical extent of frust 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
pfFrustAspect 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'.
*/
pfMakeSimpleFrust(frust, 45.0f);
pfFrustAspect(frust, PFFRUST_CALC_VERT, aspect);
Frustum aspect ratio matching is not persistent. You must call
pfFrustAspect each time the frustum changes shape in order to maintain
matched frustum/viewport.
pfGetFrustAspect returns the aspect ratio of frust.
pfGetFrustFOV 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.
Page 5
pfFrustum(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFrustum(3pf)
pfGetFrustNear 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.
pfGetFrustFar 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.
pfGetFrustEye copies the eye position of the frustum frust into eye.
pfGetFrustPtope copies the 6 half spaces which define frust into the
pfPolytope ptope.
pfGetFrustGLProjMat returns the projection matrix corresponding to frust
in the coordinate system of the Graphics Library, ignoring any
transformations applied to frust with pfOrthoXformFrust.
pfApplyFrust configures the hardware projection matrix with the
projection defined by frust. Modifications made to frust do not have
effect until pfApplyFrust is called.
pfApplyFrust is a display-listable command. If a pfDispList has been
opened by pfOpenDList, pfApplyFrust will not have immediate effect but
will be captured by the pfDispList and will only have effect when that
pfDispList is later drawn with pfDrawDList.
pfFrustContainsPt returns TRUE or FALSE depending on whether the point pt
is in the interior of the specified frustum.
pfFrustContainsBox, pfFrustContainsSphere and pfFrustContainsCyl test
whether the specified pfFrustum contains a non-empty portion of the
volume specified by the second argument, a box, sphere or cylinder,
respectively.
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 pfFrustContainsSphere and pfFrustContainsBox within
OpenGL Performer is in culling the database to the view frustum each
frame, where speed is paramount. If this computation cannot be done
Page 6
pfFrustum(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfFrustum(3pf)
easily, the function returns PFIS_MAYBE.
pfOrthoXformFrust transforms the frustum using the matrix mat: dst = src
* mat. If mat is not orthogonal the results are undefined.
NOTES
pfFrustum 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
