Basic type: View frustum. More...
Public Types  
enum  ProjectionType { Orthographic, Perspective } 
This enum is used to determine the type of projection represented by a frustum. More...  
Public Member Functions  
GF_API  GfFrustum () 
This constructor creates an instance with default viewing parameters: More...  
GF_API  GfFrustum (const GfVec3d &position, const GfRotation &rotation, const GfRange2d &window, const GfRange1d &nearFar, GfFrustum::ProjectionType projectionType, double viewDistance=5.0) 
This constructor creates an instance with the given viewing parameters. More...  
GF_API  GfFrustum (const GfMatrix4d &camToWorldXf, const GfRange2d &window, const GfRange1d &nearFar, GfFrustum::ProjectionType projectionType, double viewDistance=5.0) 
This constructor creates an instance from a camera matrix (always of a yUp camera, also see SetPositionAndRotationFromMatrix) and the given viewing parameters. More...  
bool  operator== (const GfFrustum &f) const 
bool  operator!= (const GfFrustum &f) const 
GF_API  ~GfFrustum () 
Destructor. More...  
Convenience methods  
The methods in this group allow the frustum's data to be accessed and modified in terms of different representations that may be more convenient for certain applications.  
GF_API void  SetPerspective (double fieldOfViewHeight, double aspectRatio, double nearDistance, double farDistance) 
Sets up the frustum in a manner similar to gluPerspective() . More...  
GF_API void  SetPerspective (double fieldOfView, bool isFovVertical, double aspectRatio, double nearDistance, double farDistance) 
Sets up the frustum in a manner similar to gluPerspective(). More...  
GF_API bool  GetPerspective (double *fieldOfViewHeight, double *aspectRatio, double *nearDistance, double *farDistance) const 
Returns the current frustum in the format used by SetPerspective() . More...  
GF_API bool  GetPerspective (bool isFovVertical, double *fieldOfView, double *aspectRatio, double *nearDistance, double *farDistance) const 
Returns the current frustum in the format used by SetPerspective() . More...  
GF_API double  GetFOV (bool isFovVertical=false) 
Returns the horizontal or vertical fov of the frustum. More...  
GF_API void  SetOrthographic (double left, double right, double bottom, double top, double nearPlane, double farPlane) 
Sets up the frustum in a manner similar to glOrtho() . More...  
GF_API bool  GetOrthographic (double *left, double *right, double *bottom, double *top, double *nearPlane, double *farPlane) const 
Returns the current frustum in the format used by SetOrthographic() . More...  
GF_API void  FitToSphere (const GfVec3d ¢er, double radius, double slack=0.0) 
Modifies the frustum to tightly enclose a sphere with the given center and radius, using the current view direction. More...  
GF_API GfFrustum &  Transform (const GfMatrix4d &matrix) 
Transforms the frustum by the given matrix. More...  
GF_API GfVec3d  ComputeViewDirection () const 
Returns the normalized worldspace view direction vector, which is computed by rotating the z axis by the frustum's rotation. More...  
GF_API GfVec3d  ComputeUpVector () const 
Returns the normalized worldspace up vector, which is computed by rotating the y axis by the frustum's rotation. More...  
GF_API void  ComputeViewFrame (GfVec3d *side, GfVec3d *up, GfVec3d *view) const 
Computes the view frame defined by this frustum. More...  
GF_API GfVec3d  ComputeLookAtPoint () const 
Computes and returns the worldspace lookat point from the eye point (position), view direction (rotation), and view distance. More...  
GF_API GfMatrix4d  ComputeViewMatrix () const 
Returns a matrix that represents the viewing transformation for this frustum. More...  
GF_API GfMatrix4d  ComputeViewInverse () const 
Returns a matrix that represents the inverse viewing transformation for this frustum. More...  
GF_API GfMatrix4d  ComputeProjectionMatrix () const 
Returns a GLstyle projection matrix corresponding to the frustum's projection. More...  
GF_API double  ComputeAspectRatio () const 
Returns the aspect ratio of the frustum, defined as the width of the window divided by the height. More...  
GF_API std::vector< GfVec3d >  ComputeCorners () const 
Returns the worldspace corners of the frustum as a vector of 8 points, ordered as: More...  
GF_API std::vector< GfVec3d >  ComputeCornersAtDistance (double d) const 
Returns the worldspace corners of the intersection of the frustum with a plane parallel to the near/far plane at distance d from the apex, ordered as: More...  
GF_API GfFrustum  ComputeNarrowedFrustum (const GfVec2d &point, const GfVec2d &halfSize) const 
Returns a frustum that is a narroweddown version of this frustum, such that the frustum rectangle on the near plane encloses point with at most halfSize [0] distance on the left and right and at most halfSize [1] distance on the top and bottom. More...  
GF_API GfFrustum  ComputeNarrowedFrustum (const GfVec3d &worldPoint, const GfVec2d &halfSize) const 
Returns a frustum that is a narroweddown version of this frustum, such that the frustum rectangle on the near plane encloses point with at most halfSize [0] distance on the left and right and at most halfSize [1] distance on the top and bottom. More...  
GF_API GfRay  ComputeRay (const GfVec2d &windowPos) const 
Builds and returns a GfRay that starts at the viewpoint and extends through the given windowPos given in normalized coords (1 to +1 in both dimensions) window position. More...  
GF_API GfRay  ComputeRay (const GfVec3d &worldSpacePos) const 
Builds and returns a GfRay that connects the viewpoint to the given 3d point in worldspace. More...  
GF_API GfRay  ComputePickRay (const GfVec2d &windowPos) const 
Builds and returns a GfRay that can be used for picking at the given normalized (1 to +1 in both dimensions) window position. More...  
GF_API GfRay  ComputePickRay (const GfVec3d &worldSpacePos) const 
Builds and returns a GfRay that can be used for picking that connects the viewpoint to the given 3d point in worldspace. More...  
Friends  
size_t  hash_value (const GfFrustum &f) 
Value setting and access  
The methods in this group set and access the values that are used to define a frustum.  
void  SetPosition (const GfVec3d &position) 
Sets the position of the frustum in world space. More...  
const GfVec3d &  GetPosition () const 
Returns the position of the frustum in world space. More...  
void  SetRotation (const GfRotation &rotation) 
Sets the orientation of the frustum in world space as a rotation to apply to the default frame: looking along the z axis with the +y axis as "up". More...  
const GfRotation &  GetRotation () const 
Returns the orientation of the frustum in world space as a rotation to apply to the z axis. More...  
GF_API void  SetPositionAndRotationFromMatrix (const GfMatrix4d &camToWorldXf) 
Sets the position and rotation of the frustum from a camera matrix (always from a yUp camera). More...  
void  SetWindow (const GfRange2d &window) 
Sets the window rectangle in the reference plane that defines the left, right, top, and bottom planes of the frustum. More...  
const GfRange2d &  GetWindow () const 
Returns the window rectangle in the reference plane. More...  
void  SetNearFar (const GfRange1d &nearFar) 
Sets the near/far interval. More...  
const GfRange1d &  GetNearFar () const 
Returns the near/far interval. More...  
void  SetViewDistance (double viewDistance) 
Sets the view distance. More...  
double  GetViewDistance () const 
Returns the view distance. More...  
void  SetProjectionType (GfFrustum::ProjectionType projectionType) 
Sets the projection type. More...  
GfFrustum::ProjectionType  GetProjectionType () const 
Returns the projection type. More...  
static double  GetReferencePlaneDepth () 
Returns the depth of the reference plane. More...  
Intersection methods  
The methods in this group implement intersection operations between this frustum and a given primitive.  
GF_API bool  Intersects (const GfBBox3d &bbox) const 
Returns true if the given axisaligned bbox is inside or intersecting the frustum. More...  
GF_API bool  Intersects (const GfVec3d &point) const 
Returns true if the given point is inside or intersecting the frustum. More...  
GF_API bool  Intersects (const GfVec3d &p0, const GfVec3d &p1) const 
Returns true if the line segment formed by the given points is inside or intersecting the frustum. More...  
GF_API bool  Intersects (const GfVec3d &p0, const GfVec3d &p1, const GfVec3d &p2) const 
Returns true if the triangle formed by the given points is inside or intersecting the frustum. More...  
static GF_API bool  IntersectsViewVolume (const GfBBox3d &bbox, const GfMatrix4d &vpMat) 
Returns true if the bbox volume intersects the view volume given by the viewprojection matrix, erring on the side of false positives for efficiency. More...  
Basic type: View frustum.
This class represents a viewing frustum in three dimensional eye space. It may represent either a parallel (orthographic) or perspective projection. One can think of the frustum as being defined by 6 boundary planes.
The frustum is specified using these parameters:
The window and near/far parameters combine to define the view frustum as follows. Transform the z axis and the +y axis by the frustum rotation to get the worldspace view direction and up direction. Now consider the reference plane that is perpendicular to the view direction, a distance of referencePlaneDepth from the viewpoint, and whose y axis corresponds to the up direction. The window rectangle is specified in a 2D coordinate system embedded in this plane. The origin of the coordinate system is the point at which the view direction vector intersects the plane. Therefore, the point (0,1) in this plane is found by moving 1 unit along the up direction vector in this plane. The vector from the viewpoint to the resulting point will form a 45degree angle with the view direction.
The view distance is only useful for interactive applications. It can be used to compute a look at point which is useful when rotating around an object of interest.
enum ProjectionType 
GF_API GfFrustum  (  ) 
This constructor creates an instance with default viewing parameters:
GfFrustum::Perspective
. GF_API GfFrustum  (  const GfVec3d &  position, 
const GfRotation &  rotation,  
const GfRange2d &  window,  
const GfRange1d &  nearFar,  
GfFrustum::ProjectionType  projectionType,  
double  viewDistance = 5.0 

) 
This constructor creates an instance with the given viewing parameters.
GF_API GfFrustum  (  const GfMatrix4d &  camToWorldXf, 
const GfRange2d &  window,  
const GfRange1d &  nearFar,  
GfFrustum::ProjectionType  projectionType,  
double  viewDistance = 5.0 

) 
This constructor creates an instance from a camera matrix (always of a yUp camera, also see SetPositionAndRotationFromMatrix) and the given viewing parameters.
GF_API ~GfFrustum  (  ) 
Destructor.
GF_API double ComputeAspectRatio  (  )  const 
Returns the aspect ratio of the frustum, defined as the width of the window divided by the height.
If the height is zero or negative, this returns 0.
GF_API std::vector<GfVec3d> ComputeCorners  (  )  const 
Returns the worldspace corners of the frustum as a vector of 8 points, ordered as:
GF_API std::vector<GfVec3d> ComputeCornersAtDistance  (  double  d  )  const 
Returns the worldspace corners of the intersection of the frustum with a plane parallel to the near/far plane at distance d from the apex, ordered as:
GF_API GfVec3d ComputeLookAtPoint  (  )  const 
Computes and returns the worldspace lookat point from the eye point (position), view direction (rotation), and view distance.
Returns a frustum that is a narroweddown version of this frustum, such that the frustum rectangle on the near plane encloses point
with at most halfSize
[0] distance on the left and right and at most halfSize
[1] distance on the top and bottom.
(If point
is closer than the half size to a side of the frustum, that side is left alone. The point and sizes are in normalized 2D coordinates; they range from (1, 1) at the lower left corner of the nearplane window rectangle to (1,1) at the upper right corner.
point
is a 2d point expressed as a normalized window position.
This method is useful for computing a volume to use for interactive picking.
GF_API GfFrustum ComputeNarrowedFrustum  (  const GfVec3d &  worldPoint, 
const GfVec2d &  halfSize  
)  const 
Returns a frustum that is a narroweddown version of this frustum, such that the frustum rectangle on the near plane encloses point
with at most halfSize
[0] distance on the left and right and at most halfSize
[1] distance on the top and bottom.
(If point
is closer than the half size to a side of the frustum, that side is left alone. The point and sizes are in normalized 2D coordinates; they range from (1, 1) at the lower left corner of the nearplane window rectangle to (1,1) at the upper right corner.
point
is a 3d point expressed in world coordinates
This method is useful for computing a volume to use for interactive picking.
Builds and returns a GfRay
that can be used for picking at the given normalized (1 to +1 in both dimensions) window position.
Contrasted with ComputeRay(), that method returns a ray whose origin is the eyepoint, while this method returns a ray whose origin is on the near plane.
Builds and returns a GfRay
that can be used for picking that connects the viewpoint to the given 3d point in worldspace.
GF_API GfMatrix4d ComputeProjectionMatrix  (  )  const 
Returns a GLstyle projection matrix corresponding to the frustum's projection.
Builds and returns a GfRay
that starts at the viewpoint and extends through the given windowPos given in normalized coords (1 to +1 in both dimensions) window position.
Contrasted with ComputePickRay(), this method returns a ray whose origin is the eyepoint, while that method returns a ray whose origin is on the near plane.
Builds and returns a GfRay
that connects the viewpoint to the given 3d point in worldspace.
Contrasted with ComputePickRay(), this method returns a ray whose origin is the eyepoint, while that method returns a ray whose origin is on the near plane.
GF_API GfVec3d ComputeUpVector  (  )  const 
Returns the normalized worldspace up vector, which is computed by rotating the y axis by the frustum's rotation.
GF_API GfVec3d ComputeViewDirection  (  )  const 
Returns the normalized worldspace view direction vector, which is computed by rotating the z axis by the frustum's rotation.
Computes the view frame defined by this frustum.
The frame consists of the view direction, up vector and side vector, as shown in this diagram.
GF_API GfMatrix4d ComputeViewInverse  (  )  const 
Returns a matrix that represents the inverse viewing transformation for this frustum.
That is, it returns the matrix that converts points from eye (frustum) space to world space.
GF_API GfMatrix4d ComputeViewMatrix  (  )  const 
Returns a matrix that represents the viewing transformation for this frustum.
That is, it returns the matrix that converts points from world space to eye (frustum) space.
GF_API void FitToSphere  (  const GfVec3d &  center, 
double  radius,  
double  slack = 0.0 

) 
Modifies the frustum to tightly enclose a sphere with the given center and radius, using the current view direction.
The planes of the frustum are adjusted as necessary. The given amount of slack is added to the sphere's radius is used around the sphere to avoid boundary problems.
GF_API double GetFOV  (  bool  isFovVertical = false  ) 
Returns the horizontal or vertical fov of the frustum.
The fov of the frustum is not necessarily the same value as displayed in the viewer. The displayed fov is a function of the focal length or FOV avar. The frustum's fov may be different due to things like lens breathing.
If the frustum is not of type GfFrustum::Perspective
, the returned FOV will be 0.0.
isFovVertical
is false so calling GetFOV
without an argument will return the horizontal field of view which is compatible with menv2x's old GfFrustum::GetFOV routine.

inline 
GF_API bool GetOrthographic  (  double *  left, 
double *  right,  
double *  bottom,  
double *  top,  
double *  nearPlane,  
double *  farPlane  
)  const 
Returns the current frustum in the format used by SetOrthographic()
.
If the current frustum is not an orthographic projection, this returns false
and leaves the parameters untouched.
GF_API bool GetPerspective  (  double *  fieldOfViewHeight, 
double *  aspectRatio,  
double *  nearDistance,  
double *  farDistance  
)  const 
Returns the current frustum in the format used by SetPerspective()
.
If the current frustum is not a perspective projection, this returns false
and leaves the parameters untouched.
GF_API bool GetPerspective  (  bool  isFovVertical, 
double *  fieldOfView,  
double *  aspectRatio,  
double *  nearDistance,  
double *  farDistance  
)  const 
Returns the current frustum in the format used by SetPerspective()
.
If the current frustum is not a perspective projection, this returns false
and leaves the parameters untouched.

inline 

inline 

inlinestatic 

inline 

inline 

inline 
GF_API bool Intersects  (  const GfBBox3d &  bbox  )  const 
Returns true if the given axisaligned bbox is inside or intersecting the frustum.
Otherwise, it returns false. Useful when doing picking or frustum culling.
GF_API bool Intersects  (  const GfVec3d &  point  )  const 
Returns true if the given point is inside or intersecting the frustum.
Otherwise, it returns false.
Returns true
if the line segment formed by the given points is inside or intersecting the frustum.
Otherwise, it returns false.
Returns true
if the triangle formed by the given points is inside or intersecting the frustum.
Otherwise, it returns false.

static 
Returns true
if the bbox volume intersects the view volume given by the viewprojection matrix, erring on the side of false positives for efficiency.
This method is intended for cases where a GfFrustum is not available or when the viewprojection matrix yields a view volume that is not expressable as a GfFrustum.
Because it errs on the side of false positives, it is suitable for earlyout tests such as draw or intersection culling.

inline 
GF_API void SetOrthographic  (  double  left, 
double  right,  
double  bottom,  
double  top,  
double  nearPlane,  
double  farPlane  
) 
Sets up the frustum in a manner similar to glOrtho()
.
Sets the projection to GfFrustum::Orthographic
and sets the window and near/far specifications based on the given values.
GF_API void SetPerspective  (  double  fieldOfViewHeight, 
double  aspectRatio,  
double  nearDistance,  
double  farDistance  
) 
Sets up the frustum in a manner similar to gluPerspective()
.
It sets the projection type to GfFrustum::Perspective
and sets the window specification so that the resulting symmetric frustum encloses an angle of fieldOfViewHeight
degrees in the vertical direction, with aspectRatio
used to figure the angle in the horizontal direction. The near and far distances are specified as well. The window coordinates are computed as:
GF_API void SetPerspective  (  double  fieldOfView, 
bool  isFovVertical,  
double  aspectRatio,  
double  nearDistance,  
double  farDistance  
) 
Sets up the frustum in a manner similar to gluPerspective().
It sets the projection type to GfFrustum::Perspective
and sets the window specification so that:
If isFovVertical is true, the resulting symmetric frustum encloses an angle of fieldOfView
degrees in the vertical direction, with aspectRatio
used to figure the angle in the horizontal direction.
If isFovVertical is false, the resulting symmetric frustum encloses an angle of fieldOfView
degrees in the horizontal direction, with aspectRatio
used to figure the angle in the vertical direction.
The near and far distances are specified as well. The window coordinates are computed as follows:

inline 
GF_API void SetPositionAndRotationFromMatrix  (  const GfMatrix4d &  camToWorldXf  ) 
Sets the position and rotation of the frustum from a camera matrix (always from a yUp camera).
The resulting frustum's transform will always represent a righthanded and orthonormal coordinate sytem (scale, shear, and projection are removed from the given camToWorldXf
).

inline 

inline 

inline 

inline 
GF_API GfFrustum& Transform  (  const GfMatrix4d &  matrix  ) 
Transforms the frustum by the given matrix.
The transformation matrix is applied as follows: the position and the direction vector are transformed with the given matrix. Then the length of the new direction vector is used to rescale the near and far plane and the view distance. Finally, the points that define the reference plane are transformed by the matrix. This method assures that the frustum will not be sheared or perspectiveprojected.