GfFrustum Class Reference

#include <frustum.h>

Public Types
enum	ProjectionType { Orthographic, Perspective }

Public Member Functions
GF_API	GfFrustum ()
	GfFrustum (GfFrustum const &o)
	Copy constructor. More...
	GfFrustum (GfFrustum &&o) noexcept
	Move constructor. More...
GF_API	GfFrustum (const GfVec3d &position, const GfRotation &rotation, const GfRange2d &window, const GfRange1d &nearFar, GfFrustum::ProjectionType projectionType, double viewDistance=5.0)
GF_API	GfFrustum (const GfMatrix4d &camToWorldXf, const GfRange2d &window, const GfRange1d &nearFar, GfFrustum::ProjectionType projectionType, double viewDistance=5.0)
GfFrustum &	operator= (GfFrustum const &o) noexcept
	Copy assignment. More...
GfFrustum &	operator= (GfFrustum &&o) noexcept
	Move assignment. 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)
GF_API void	SetPerspective (double fieldOfView, bool isFovVertical, double aspectRatio, double nearDistance, double farDistance)
GF_API bool	GetPerspective (double *fieldOfViewHeight, double *aspectRatio, double *nearDistance, double *farDistance) const
GF_API bool	GetPerspective (bool isFovVertical, double *fieldOfView, double *aspectRatio, double *nearDistance, double *farDistance) const
GF_API double	GetFOV (bool isFovVertical=false)
GF_API void	SetOrthographic (double left, double right, double bottom, double top, double nearPlane, double farPlane)
GF_API bool	GetOrthographic (double *left, double *right, double *bottom, double *top, double *nearPlane, double *farPlane) const
GF_API void	FitToSphere (const GfVec3d &center, double radius, double slack=0.0)
GF_API GfFrustum &	Transform (const GfMatrix4d &matrix)
GF_API GfVec3d	ComputeViewDirection () const
GF_API GfVec3d	ComputeUpVector () const
GF_API void	ComputeViewFrame (GfVec3d *side, GfVec3d *up, GfVec3d *view) const
GF_API GfVec3d	ComputeLookAtPoint () const
GF_API GfMatrix4d	ComputeViewMatrix () const
GF_API GfMatrix4d	ComputeViewInverse () const
GF_API GfMatrix4d	ComputeProjectionMatrix () const
GF_API double	ComputeAspectRatio () const
GF_API std::vector< GfVec3d >	ComputeCorners () const
GF_API std::vector< GfVec3d >	ComputeCornersAtDistance (double d) const
GF_API GfFrustum	ComputeNarrowedFrustum (const GfVec2d &windowPos, const GfVec2d &size) const
GF_API GfFrustum	ComputeNarrowedFrustum (const GfVec3d &worldPoint, const GfVec2d &size) const
GF_API GfRay	ComputeRay (const GfVec2d &windowPos) const
GF_API GfRay	ComputeRay (const GfVec3d &worldSpacePos) const
GF_API GfRay	ComputePickRay (const GfVec2d &windowPos) const
GF_API GfRay	ComputePickRay (const GfVec3d &worldSpacePos) const

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)
const GfRotation &	GetRotation () const
GF_API void	SetPositionAndRotationFromMatrix (const GfMatrix4d &camToWorldXf)
void	SetWindow (const GfRange2d &window)
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
GF_API bool	Intersects (const GfVec3d &point) const
GF_API bool	Intersects (const GfVec3d &p0, const GfVec3d &p1) const
GF_API bool	Intersects (const GfVec3d &p0, const GfVec3d &p1, const GfVec3d &p2) const
static GF_API bool	IntersectsViewVolume (const GfBBox3d &bbox, const GfMatrix4d &vpMat)

Detailed Description

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 position of the viewpoint.
• The rotation applied to the default view frame, which is looking along the -z axis with the +y axis as the "up" direction.
• The 2D window on the reference plane that defines the left, right, top, and bottom planes of the viewing frustum, as described below.
• The distances to the near and far planes.
• The projection type
• The view distance.

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 world-space 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 45-degree 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.

Definition at line 88 of file frustum.h.

Member Enumeration Documentation

enum GfFrustum::ProjectionType

This enum is used to determine the type of projection represented by a frustum.

Enumerator
Orthographic	Orthographic projection.
Perspective	Perspective projection.

Definition at line 92 of file frustum.h.

Constructor & Destructor Documentation

GF_API GfFrustum::GfFrustum

(

)

This constructor creates an instance with default viewing parameters:

• The position is the origin.
• The rotation is the identity rotation. (The view is along the -z axis, with the +y axis as "up").
• The window is -1 to +1 in both dimensions.
• The near/far interval is (1, 10).
• The view distance is 5.0.
• The projection type is GfFrustum::Perspective.

GfFrustum::GfFrustum ( GfFrustum const &  o )

inline

Copy constructor.

Definition at line 108 of file frustum.h.

GfFrustum::GfFrustum ( GfFrustum &&  o )

inlinenoexcept

Move constructor.

Definition at line 122 of file frustum.h.

GF_API GfFrustum::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::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 y-Up camera, also see SetPositionAndRotationFromMatrix) and the given viewing parameters.

GF_API GfFrustum::~GfFrustum

(

)

Destructor.

Member Function Documentation

GF_API double GfFrustum::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> GfFrustum::ComputeCorners

(

)

const

Returns the world-space corners of the frustum as a vector of 8 points, ordered as:

• Left bottom near
• Right bottom near
• Left top near
• Right top near
• Left bottom far
• Right bottom far
• Left top far
• Right top far

GF_API std::vector<GfVec3d> GfFrustum::ComputeCornersAtDistance

(

double

d

)

const

Returns the world-space corners of the intersection of the frustum with a plane parallel to the near/far plane at distance d from the apex, ordered as:

• Left bottom
• Right bottom
• Left top
• Right top In particular, it gives the partial result of ComputeCorners when given near or far distance.

GF_API GfVec3d GfFrustum::ComputeLookAtPoint

(

)

const

Computes and returns the world-space look-at point from the eye point (position), view direction (rotation), and view distance.

GF_API GfFrustum GfFrustum::ComputeNarrowedFrustum	(	const GfVec2d &	windowPos,
		const GfVec2d &	size
	)		const

Returns a frustum that is a narrowed-down version of this frustum. The new frustum has the same near and far planes, but the other planes are adjusted to be centered on windowPos with the new width and height obtained from the existing width and height by multiplying by size[0] and size[1], respectively. Finally, the new frustum is clipped against this frustum so that it is completely contained in the existing frustum.

windowPos is given in normalized coords (-1 to +1 in both dimensions). size is given as a scalar (0 to 1 in both dimensions).

If the windowPos or size given is outside these ranges, it may result in returning a collapsed frustum.

This method is useful for computing a volume to use for interactive picking.

GF_API GfFrustum GfFrustum::ComputeNarrowedFrustum	(	const GfVec3d &	worldPoint,
		const GfVec2d &	size
	)		const

Returns a frustum that is a narrowed-down version of this frustum. The new frustum has the same near and far planes, but the other planes are adjusted to be centered on worldPoint with the new width and height obtained from the existing width and height by multiplying by size[0] and size[1], respectively. Finally, the new frustum is clipped against this frustum so that it is completely contained in the existing frustum.

worldPoint is given in world space coordinates. size is given as a scalar (0 to 1 in both dimensions).

If the size given is outside this range, it may result in returning a collapsed frustum.

If the worldPoint is at or behind the eye of the frustum, it will return a frustum equal to this frustum.

This method is useful for computing a volume to use for interactive picking.

GF_API GfRay GfFrustum::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.

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.

GF_API GfRay GfFrustum::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.

GF_API GfMatrix4d GfFrustum::ComputeProjectionMatrix

(

)

const

Returns a GL-style projection matrix corresponding to the frustum's projection.

GF_API GfRay GfFrustum::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.

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 GfRay GfFrustum::ComputeRay

(

const GfVec3d &

worldSpacePos

)

const

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 GfFrustum::ComputeUpVector

(

)

const

Returns the normalized world-space up vector, which is computed by rotating the y axis by the frustum's rotation.

GF_API GfVec3d GfFrustum::ComputeViewDirection

(

)

const

Returns the normalized world-space view direction vector, which is computed by rotating the -z axis by the frustum's rotation.

GF_API void GfFrustum::ComputeViewFrame	(	GfVec3d *	side,
		GfVec3d *	up,
		GfVec3d *	view
	)		const

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.

up
^   ^
|  / 
| / view
|/
+- - - - > side

GF_API GfMatrix4d GfFrustum::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 GfFrustum::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 GfFrustum::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 GfFrustum::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.

Note

The default value for 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.

const GfRange1d& GfFrustum::GetNearFar ( ) const

inline

Returns the near/far interval.

Definition at line 283 of file frustum.h.

GF_API bool GfFrustum::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 GfFrustum::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 GfFrustum::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.

const GfVec3d& GfFrustum::GetPosition ( ) const

inline

Returns the position of the frustum in world space.

Definition at line 234 of file frustum.h.

GfFrustum::ProjectionType GfFrustum::GetProjectionType ( ) const

inline

Returns the projection type.

Definition at line 304 of file frustum.h.

static double GfFrustum::GetReferencePlaneDepth ( )

inlinestatic

Returns the depth of the reference plane.

Definition at line 272 of file frustum.h.

const GfRotation& GfFrustum::GetRotation ( ) const

inline

Returns the orientation of the frustum in world space as a rotation to apply to the -z axis.

Definition at line 248 of file frustum.h.

double GfFrustum::GetViewDistance ( ) const

inline

Returns the view distance.

Definition at line 293 of file frustum.h.

const GfRange2d& GfFrustum::GetWindow ( ) const

inline

Returns the window rectangle in the reference plane.

Definition at line 267 of file frustum.h.

GF_API bool GfFrustum::Intersects

(

const GfBBox3d &

bbox

)

const

Returns true if the given axis-aligned bbox is inside or intersecting the frustum. Otherwise, it returns false. Useful when doing picking or frustum culling.

GF_API bool GfFrustum::Intersects

(

const GfVec3d &

point

)

const

Returns true if the given point is inside or intersecting the frustum. Otherwise, it returns false.

GF_API bool GfFrustum::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. Otherwise, it returns false.

GF_API bool GfFrustum::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. Otherwise, it returns false.

static GF_API bool GfFrustum::IntersectsViewVolume ( const GfBBox3d &  bbox, const GfMatrix4d &  vpMat  )

static

Returns true if the bbox volume intersects the view volume given by the view-projection 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 view-projection 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 early-out tests such as draw or intersection culling.

bool GfFrustum::operator!= ( const GfFrustum &  f ) const

inline

Definition at line 215 of file frustum.h.

GfFrustum& GfFrustum::operator= ( GfFrustum const &  o )

inlinenoexcept

Copy assignment.

Definition at line 152 of file frustum.h.

GfFrustum& GfFrustum::operator= ( GfFrustum &&  o )

inlinenoexcept

Move assignment.

Definition at line 174 of file frustum.h.

bool GfFrustum::operator== ( const GfFrustum &  f ) const

inline

Definition at line 203 of file frustum.h.

void GfFrustum::SetNearFar ( const GfRange1d &  nearFar )

inline

Sets the near/far interval.

Definition at line 277 of file frustum.h.

GF_API void GfFrustum::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 GfFrustum::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:

top    = tan(fieldOfViewHeight / 2)
bottom = -top
right  = top * aspectRatio
left   = -right
near   = nearDistance
far    = farDistance

GF_API void GfFrustum::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:

• if isFovVertical:
• top = tan(fieldOfView / 2)
• right = top * aspectRatio
• if NOT isFovVertical:
• right = tan(fieldOfView / 2)
• top = right / aspectRation
• bottom = -top
• left = -right
• near = nearDistance
• far = farDistance

void GfFrustum::SetPosition ( const GfVec3d &  position )

inline

Sets the position of the frustum in world space.

Definition at line 228 of file frustum.h.

GF_API void GfFrustum::SetPositionAndRotationFromMatrix

(

const GfMatrix4d &

camToWorldXf

)

Sets the position and rotation of the frustum from a camera matrix (always from a y-Up camera). The resulting frustum's transform will always represent a right-handed and orthonormal coordinate sytem (scale, shear, and projection are removed from the given camToWorldXf).

void GfFrustum::SetProjectionType ( GfFrustum::ProjectionType  projectionType )

inline

Sets the projection type.

Definition at line 298 of file frustum.h.

void GfFrustum::SetRotation ( const GfRotation &  rotation )

inline

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".

Definition at line 241 of file frustum.h.

void GfFrustum::SetViewDistance ( double  viewDistance )

inline

Sets the view distance.

Definition at line 288 of file frustum.h.

void GfFrustum::SetWindow ( const GfRange2d &  window )

inline

Sets the window rectangle in the reference plane that defines the left, right, top, and bottom planes of the frustum.

Definition at line 261 of file frustum.h.

GF_API GfFrustum& 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 perspective-projected.

Note

Note that this definition means that the transformed frustum does not preserve scales very well. Do not use this function to transform a frustum that is to be used for precise operations such as intersection testing.

Friends And Related Function Documentation

size_t hash_value ( const GfFrustum &  f )

friend

Definition at line 191 of file frustum.h.

---

The documentation for this class was generated from the following file:

• pxr/base/gf/frustum.h