Frustum Class Reference

#include <frustum.h>

Detailed Description

This class implements a view frustum for use in culling scene objects and rendering the scene graph.

Public Types

NearTopLeft

The corner points of the frustum.

NearTopRight

NearBottomLeft

NearBottomRight

FarTopLeft

FarTopRight

FarBottomLeft

FarBottomRight

CameraPosition

The apex of the frustum.

PlaneLeftCenter

The center points of the frustum planes.

PlaneRightCenter

PlaneTopCenter

PlaneBottomCenter

PlaneNearCenter

PlaneFarCenter

PointCount

The total number of frustum points.

FirstCornerPoint = NearTopLeft

LastCornerPoint = FarBottomRight

CornerPointCount = 8

PlaneLeft

PlaneRight

PlaneNear

PlaneFar

PlaneTop

PlaneBottom

PlaneCount

The total number of frustum planes.

PlaneMaskLeft = ( 1 << PlaneLeft )

PlaneMaskRight = ( 1 << PlaneRight )

PlaneMaskTop = ( 1 << PlaneTop )

PlaneMaskBottom = ( 1 << PlaneBottom )

PlaneMaskNear = ( 1 << PlaneNear )

PlaneMaskFar = ( 1 << PlaneFar )

PlaneMaskAll = 0xFFFFFFFF

enum {
  NearTopLeft,
  NearTopRight,
  NearBottomLeft,
  NearBottomRight,
  FarTopLeft,
  FarTopRight,
  FarBottomLeft,
  FarBottomRight,
  CameraPosition,
  PlaneLeftCenter,
  PlaneRightCenter,
  PlaneTopCenter,
  PlaneBottomCenter,
  PlaneNearCenter,
  PlaneFarCenter,
  PointCount,
  FirstCornerPoint = NearTopLeft,
  LastCornerPoint = FarBottomRight,
  CornerPointCount = 8
}

Used to index into point array. More...

enum {
  PlaneLeft,
  PlaneRight,
  PlaneNear,
  PlaneFar,
  PlaneTop,
  PlaneBottom,
  PlaneCount
}

Used to index into the plane array. More...

enum {
  PlaneMaskLeft = ( 1 << PlaneLeft ),
  PlaneMaskRight = ( 1 << PlaneRight ),
  PlaneMaskTop = ( 1 << PlaneTop ),
  PlaneMaskBottom = ( 1 << PlaneBottom ),
  PlaneMaskNear = ( 1 << PlaneNear ),
  PlaneMaskFar = ( 1 << PlaneFar ),
  PlaneMaskAll = 0xFFFFFFFF
}

Used to mask out planes for testing. More...

Public Member Functions

Constructors

Frustum ()

Default constructor with an uninitialized frustum.

Frustum (const Frustum &frustum)

Copy constructor.

Operators

Frustum & operator= (const Frustum &frustum)

Convenience operator for copying frustums.

Initialization

Functions used to initialize the frustum.

void set (const Frustum &frustum)

Set the frustum via a copy.

void set (F32 fovInRadians, F32 aspectRatio, F32 nearDist, F32 farDist, const MatrixF &mat=MatrixF(true))

Sets the frustum from the field of view, screen aspect ratio, and the near and far distances.

void set (F32 nearLeft, F32 nearRight, F32 nearTop, F32 nearBottom, F32 nearDist, F32 farDist, const MatrixF &transform=MatrixF(true))

Sets the frustum from the near plane dimensions and near and far distances.

void set (const MatrixF &projMatrix, bool normalize)

Sets the frustum by extracting the planes from a projection, view-projection, or world-view-projection matrix.

void setNearDist (F32 nearDist)

Changes the near distance of the frustum.

void setFarDist (F32 farDist)

Changes the far distance of the frustum.

void setNearFarDist (F32 nearDist, F32 farDist)

Changes the near and far distance of the frustum.

F32 getFarDist () const

Returns the far clip distance used to create the frustum planes.

F32 getNearDist () const

Returns the far clip distance used to create the frustum planes.

F32 getNearLeft () const

F32 getNearRight () const

F32 getNearTop () const

F32 getNearBottom () const

Transformation

These functions for transforming the frustum from one space to another.

void setTransform (const MatrixF &transform)

Sets a new transform for the frustum.

const MatrixF & getTransform () const

Returns the current transform matrix for the frustum.

void scaleFromCenter (F32 scale)

Scales up the frustum from its center point.

void mul (const MatrixF &mat)

Transforms the frustum by F = F * mat.

void mulL (const MatrixF &mat)

Transforms the frustum by F = mat * F.

void invert ()

Flip the plane normals which has the result of reversing the culling results.

bool isInverted () const

Returns true if the frustum planes point outwards.

const Point3F & getPosition () const

Returns the origin point of the frustum.

const Box3F & getBounds () const

Returns the axis aligned bounding box of the frustum points typically used for early rejection.

void getProjectionMatrix (MatrixF *proj) const

Generates a projection matrix from the frustum.

Culling

Various functions used to cull shapes against the view frustum. For best results always perform an overlap test against the frustum bounds before using these routines.

bool intersects (const Box3F &bounds) const

Returns true if the box is completely within or intersecting one or more of the frustum planes.

bool pointInFrustum (const Point3F &point) const

Returns true if the point is completely within the frustum planes.

bool sphereInFrustum (const Point3F &center, F32 radius) const

Returns true if the center point of the sphere is not less than radius distance from one of the frustum planes.

U32 testPlanes (const Box3F &bounds, U32 planeMask, F32 expand=0.0f) const

Returns the bitmask of what planes were hit.

Points and Planes

const Point3F * getPoints () const

Returns a pointer to the array of frustum points of PointCount size.

const PlaneF * getPlanes () const

Returns a pointer to the array of frustum planes of PlaneCount size.

void getCenterPoint (Point3F *center) const

Returns the center point of the frustum by averaging all the corner points.

Protected Member Functions

void _updatePlanes ()

Called to initialize the planes after frustum settings are changed.

void _updateBounds ()

Called to recalculate the bounds from the frustum points when the planes are updated or transformed.

Protected Attributes

Point3F mPoints [PointCount]

The points of the frustum that make up the the clipping planes.

PlaneF mPlanes [PlaneCount]

The clipping planes used during culling.

Box3F mBounds

The axis aligned bounding box which contains the extents of the frustum.

MatrixF mTransform

Used to transform the frustum points from camera space into the desired clipping space.

F32 mNearLeft

The size of the near plane used to generate the frustum points and planes.

F32 mNearRight

F32 mNearTop

F32 mNearBottom

F32 mNearDist

F32 mFarDist

Member Enumeration Documentation

anonymous enum

Used to index into point array.

Enumerator:

NearTopLeft	The corner points of the frustum.
NearTopRight
NearBottomLeft
NearBottomRight
FarTopLeft
FarTopRight
FarBottomLeft
FarBottomRight
CameraPosition	The apex of the frustum.
PlaneLeftCenter	The center points of the frustum planes.
PlaneRightCenter
PlaneTopCenter
PlaneBottomCenter
PlaneNearCenter
PlaneFarCenter
PointCount	The total number of frustum points.
FirstCornerPoint
LastCornerPoint
CornerPointCount

anonymous enum

Used to index into the plane array.

Note that these are ordered for optimal early rejection. By culling with the left and right planes first you cull most of the objects in the typical horizontal scene.

Enumerator:

PlaneLeft
PlaneRight
PlaneNear
PlaneFar
PlaneTop
PlaneBottom
PlaneCount	The total number of frustum planes.

anonymous enum

Used to mask out planes for testing.

Enumerator:

PlaneMaskLeft
PlaneMaskRight
PlaneMaskTop
PlaneMaskBottom
PlaneMaskNear
PlaneMaskFar
PlaneMaskAll

Constructor & Destructor Documentation

Frustum::Frustum ( )

Default constructor with an uninitialized frustum.

Frustum::Frustum ( const Frustum & frustum )

Copy constructor.

Member Function Documentation

void Frustum::_updatePlanes ( ) [protected]

Called to initialize the planes after frustum settings are changed.

void Frustum::_updateBounds ( ) [protected]

Called to recalculate the bounds from the frustum points when the planes are updated or transformed.

Frustum& Frustum::operator= ( const Frustum & frustum )

Convenience operator for copying frustums.

void Frustum::set ( const Frustum & frustum )

Set the frustum via a copy.

void Frustum::set	(	F32	fovInRadians,
		F32	aspectRatio,
		F32	nearDist,
		F32	farDist,
		const MatrixF &	mat = `MatrixF(true)`
	)

Sets the frustum from the field of view, screen aspect ratio, and the near and far distances.

You can pass an matrix to transform the frustum.

void Frustum::set	(	F32	nearLeft,
		F32	nearRight,
		F32	nearTop,
		F32	nearBottom,
		F32	nearDist,
		F32	farDist,
		const MatrixF &	transform = `MatrixF(true)`
	)

Sets the frustum from the near plane dimensions and near and far distances.

void Frustum::set	(	const MatrixF &	projMatrix,
		bool	normalize
	)

Sets the frustum by extracting the planes from a projection, view-projection, or world-view-projection matrix.

void Frustum::setNearDist ( F32 nearDist )

Changes the near distance of the frustum.

void Frustum::setFarDist ( F32 farDist )

Changes the far distance of the frustum.

void Frustum::setNearFarDist	(	F32	nearDist,
		F32	farDist
	)

Changes the near and far distance of the frustum.

F32 Frustum::getFarDist ( ) const [inline]

Returns the far clip distance used to create the frustum planes.

F32 Frustum::getNearDist ( ) const [inline]

Returns the far clip distance used to create the frustum planes.

F32 Frustum::getNearLeft ( ) const [inline]

F32 Frustum::getNearRight ( ) const [inline]

F32 Frustum::getNearTop ( ) const [inline]

F32 Frustum::getNearBottom ( ) const [inline]

void Frustum::setTransform ( const MatrixF & transform )

Sets a new transform for the frustum.

const MatrixF & Frustum::getTransform ( ) const [inline]

Returns the current transform matrix for the frustum.

void Frustum::scaleFromCenter ( F32 scale )

Scales up the frustum from its center point.

void Frustum::mul ( const MatrixF & mat )

Transforms the frustum by F = F * mat.

void Frustum::mulL ( const MatrixF & mat )

Transforms the frustum by F = mat * F.

void Frustum::invert ( )

Flip the plane normals which has the result of reversing the culling results.

bool Frustum::isInverted ( ) const

Returns true if the frustum planes point outwards.

const Point3F & Frustum::getPosition ( ) const [inline]

Returns the origin point of the frustum.

const Box3F & Frustum::getBounds ( ) const [inline]

Returns the axis aligned bounding box of the frustum points typically used for early rejection.

void Frustum::getProjectionMatrix ( MatrixF * proj ) const

Generates a projection matrix from the frustum.

bool Frustum::intersects ( const Box3F & bounds ) const

Returns true if the box is completely within or intersecting one or more of the frustum planes.

bool Frustum::pointInFrustum ( const Point3F & point ) const

Returns true if the point is completely within the frustum planes.

bool Frustum::sphereInFrustum	(	const Point3F &	center,
		F32	radius
	)			const

Returns true if the center point of the sphere is not less than radius distance from one of the frustum planes.

U32 Frustum::testPlanes	(	const Box3F &	bounds,
		U32	planeMask,
		F32	expand = `0.0f`
	)			const

Returns the bitmask of what planes were hit.

const Point3F * Frustum::getPoints ( ) const [inline]

Returns a pointer to the array of frustum points of PointCount size.

const PlaneF * Frustum::getPlanes ( ) const [inline]

Returns a pointer to the array of frustum planes of PlaneCount size.

void Frustum::getCenterPoint ( Point3F * center ) const

Returns the center point of the frustum by averaging all the corner points.

Member Data Documentation

Point3F Frustum::mPoints[PointCount] [protected]

The points of the frustum that make up the the clipping planes.

PlaneF Frustum::mPlanes[PlaneCount] [protected]

The clipping planes used during culling.

Box3F Frustum::mBounds [protected]

The axis aligned bounding box which contains the extents of the frustum.

MatrixF Frustum::mTransform [protected]

Used to transform the frustum points from camera space into the desired clipping space.

F32 Frustum::mNearLeft [protected]

The size of the near plane used to generate the frustum points and planes.

F32 Frustum::mNearRight [protected]

F32 Frustum::mNearTop [protected]

F32 Frustum::mNearBottom [protected]

F32 Frustum::mNearDist [protected]

F32 Frustum::mFarDist [protected]