plFrustum Class Reference

Represents the frustum of some camera and can be used for culling objects. More...

#include <Frustum.h>

Public Types
enum	PlaneType : plUInt8 {   NearPlane , LeftPlane , RightPlane , FarPlane ,   BottomPlane , TopPlane , PLANE_COUNT }
enum	FrustumCorner : plUInt8 {   NearTopLeft , NearTopRight , NearBottomLeft , NearBottomRight ,   FarTopLeft , FarTopRight , FarBottomLeft , FarBottomRight ,   CORNER_COUNT = 8 }

Public Member Functions
	plFrustum ()
	The constructor does NOT initialize the frustum planes, make sure to call SetFrustum() before trying to use it.
const plPlane &	GetPlane (plUInt8 uiPlane) const
	Returns the n-th plane of the frustum.
plPlane &	AccessPlane (plUInt8 uiPlane)
	Returns the n-th plane of the frustum and allows modification.
bool	IsValid () const
	Checks that all planes are valid.
void	TransformFrustum (const plMat4 &mTransform)
	Transforms the frustum by the given matrix. This allows to adjust the frustum to a new orientation when a camera is moved or when it is necessary to cull from a different position.
plFrustum	GetTransformedFrustum (const plMat4 &mTransform) const
	Returns frustum transformed by given matrix.
void	InvertFrustum ()
	Flips all frustum planes around. Might be necessary after creating the frustum from a mirror projection matrix.
plResult	ComputeCornerPoints (plVec3 out_pPoints[FrustumCorner::CORNER_COUNT]) const
	Computes the frustum corner points.
plVolumePosition::Enum	GetObjectPosition (const plVec3 *pVertices, plUInt32 uiNumVertices) const
	Checks whether the given object is inside or outside the frustum.
plVolumePosition::Enum	GetObjectPosition (const plVec3 *pVertices, plUInt32 uiNumVertices, const plMat4 &mObjectTransform) const
	Same as GetObjectPosition(), but applies a transformation to the given object first. This allows to do culling on instanced objects.
plVolumePosition::Enum	GetObjectPosition (const plBoundingSphere &sphere) const
	Checks whether the given object is inside or outside the frustum.
plVolumePosition::Enum	GetObjectPosition (const plBoundingBox &box) const
	Checks whether the given object is inside or outside the frustum.
bool	Overlaps (const plSimdBBox &object) const
	Returns true if the object is fully inside the frustum or partially overlaps it. Returns false when the object is fully outside the frustum.
bool	Overlaps (const plSimdBSphere &object) const
	Returns true if the object is fully inside the frustum or partially overlaps it. Returns false when the object is fully outside the frustum.

Static Public Member Functions
static plFrustum	MakeFromPlanes (const plPlane *pPlanes)
	Sets the frustum manually by specifying the planes directly.
static plResult	TryMakeFromPlanes (plFrustum &out_frustum, const plPlane *pPlanes)
	Sets the frustum manually by specifying the planes directly.
static plFrustum	MakeFromMVP (const plMat4 &mModelViewProjection, plClipSpaceDepthRange::Enum depthRange=plClipSpaceDepthRange::Default, plHandedness::Enum handedness=plHandedness::Default)
	Creates the frustum by extracting the planes from the given (model-view / projection) matrix.
static plResult	TryMakeFromMVP (plFrustum &out_frustum, const plMat4 &mModelViewProjection, plClipSpaceDepthRange::Enum depthRange=plClipSpaceDepthRange::Default, plHandedness::Enum handedness=plHandedness::Default)
	Creates the frustum by extracting the planes from the given (model-view / projection) matrix.
static plFrustum	MakeFromFOV (const plVec3 &vPosition, const plVec3 &vForwards, const plVec3 &vUp, plAngle fovX, plAngle fovY, float fNearPlane, float fFarPlane)
	Creates a frustum from the given camera position, direction vectors and the field-of-view along X and Y.
static plResult	TryMakeFromFOV (plFrustum &out_frustum, const plVec3 &vPosition, const plVec3 &vForwards, const plVec3 &vUp, plAngle fovX, plAngle fovY, float fNearPlane, float fFarPlane)
	Creates a frustum from the given camera position, direction vectors and the field-of-view along X and Y.
static plFrustum	MakeFromCorners (const plVec3 pCorners[FrustumCorner::CORNER_COUNT])
	Creates a frustum from 8 corner points.
static plResult	TryMakeFromCorners (plFrustum &out_frustum, const plVec3 pCorners[FrustumCorner::CORNER_COUNT])
	Creates a frustum from 8 corner points.

Detailed Description

Represents the frustum of some camera and can be used for culling objects.

The frustum always consists of exactly 6 planes (near, far, left, right, top, bottom).

The frustum planes point outwards, ie. when an object is in front of one of the planes, it is considered to be outside the frustum.

Planes can be automatically extracted from a projection matrix or passed in manually. In the latter case, make sure to pass them in in the order defined in the PlaneType enum.

Member Function Documentation

ComputeCornerPoints()

plResult plFrustum::ComputeCornerPoints

(

plVec3

out_pPoints[FrustumCorner::CORNER_COUNT]

)

const

Computes the frustum corner points.

Note: If the frustum contains an infinite far plane, the far plane corners (out_points[4..7]) will be at infinity.

GetObjectPosition() [1/4]

plVolumePosition::Enum plFrustum::GetObjectPosition

(

const plBoundingBox &

box

)

const

Checks whether the given object is inside or outside the frustum.

Test

Not yet tested

GetObjectPosition() [2/4]

plVolumePosition::Enum plFrustum::GetObjectPosition

(

const plBoundingSphere &

sphere

)

const

Checks whether the given object is inside or outside the frustum.

Test

Not yet tested

GetObjectPosition() [3/4]

plVolumePosition::Enum plFrustum::GetObjectPosition	(	const plVec3 *	pVertices,
		plUInt32	uiNumVertices ) const

Checks whether the given object is inside or outside the frustum.

A concave object might be classified as 'intersecting' although it is outside the frustum, if it overlaps the planes just right. However an object that overlaps the frustum is definitely never classified as 'outside'.

Test

Not yet tested

GetObjectPosition() [4/4]

plVolumePosition::Enum plFrustum::GetObjectPosition	(	const plVec3 *	pVertices,
		plUInt32	uiNumVertices,
		const plMat4 &	mObjectTransform ) const

Same as GetObjectPosition(), but applies a transformation to the given object first. This allows to do culling on instanced objects.

Test

Not yet tested

MakeFromCorners()

plFrustum plFrustum::MakeFromCorners ( const plVec3 pCorners[FrustumCorner::CORNER_COUNT] )

staticnodiscard

Creates a frustum from 8 corner points.

Asserts that the frustum is valid after construction. Thus the given points must form a proper frustum.

MakeFromFOV()

plFrustum plFrustum::MakeFromFOV ( const plVec3 & vPosition, const plVec3 & vForwards, const plVec3 & vUp, plAngle fovX, plAngle fovY, float fNearPlane, float fFarPlane )

staticnodiscard

Creates a frustum from the given camera position, direction vectors and the field-of-view along X and Y.

The up vector does not need to be exactly orthogonal to the forwards vector, it will get recomputed properly. FOV X and Y define the entire field-of-view, so a FOV of 180 degree would mean the entire half-space in front of the camera.

MakeFromMVP()

plFrustum plFrustum::MakeFromMVP ( const plMat4 & mModelViewProjection, plClipSpaceDepthRange::Enum depthRange = plClipSpaceDepthRange::Default, plHandedness::Enum handedness = plHandedness::Default )

staticnodiscard

Creates the frustum by extracting the planes from the given (model-view / projection) matrix.

If the matrix is just the projection matrix, the frustum will be in local space. Pass the full ModelViewProjection matrix to create the frustum in world-space. If the projection matrix contained in ModelViewProjection is an infinite plane projection matrix, the resulting frustum will yield a far plane with infinite distance.

MakeFromPlanes()

plFrustum plFrustum::MakeFromPlanes ( const plPlane * pPlanes )

staticnodiscard

Sets the frustum manually by specifying the planes directly.

Note

Make sure to pass in the planes in the order of the PlaneType enum, otherwise plFrustum may not always work as expected.

Overlaps() [1/2]

PL_FORCE_INLINE bool plFrustum::Overlaps

(

const plSimdBBox &

object

)

const

Returns true if the object is fully inside the frustum or partially overlaps it. Returns false when the object is fully outside the frustum.

This function is more efficient than GetObjectPosition() and should be preferred when possible.

Overlaps() [2/2]

PL_FORCE_INLINE bool plFrustum::Overlaps

(

const plSimdBSphere &

object

)

const

Returns true if the object is fully inside the frustum or partially overlaps it. Returns false when the object is fully outside the frustum.

This function is more efficient than GetObjectPosition() and should be preferred when possible.

TryMakeFromCorners()

plResult plFrustum::TryMakeFromCorners ( plFrustum & out_frustum, const plVec3 pCorners[FrustumCorner::CORNER_COUNT] )

staticnodiscard

Creates a frustum from 8 corner points.

Returns PL_SUCESS with a valid outFrustum if the operation was successful and PL_FAILURE otherwise.

TryMakeFromFOV()

plResult plFrustum::TryMakeFromFOV ( plFrustum & out_frustum, const plVec3 & vPosition, const plVec3 & vForwards, const plVec3 & vUp, plAngle fovX, plAngle fovY, float fNearPlane, float fFarPlane )

staticnodiscard

Creates a frustum from the given camera position, direction vectors and the field-of-view along X and Y.

The up vector does not need to be exactly orthogonal to the forwards vector, it will get recomputed properly. FOV X and Y define the entire field-of-view, so a FOV of 180 degree would mean the entire half-space in front of the camera.

Returns PL_SUCESS with a valid outFrustum if the operation was successful and PL_FAILURE otherwise.

TryMakeFromMVP()

plResult plFrustum::TryMakeFromMVP ( plFrustum & out_frustum, const plMat4 & mModelViewProjection, plClipSpaceDepthRange::Enum depthRange = plClipSpaceDepthRange::Default, plHandedness::Enum handedness = plHandedness::Default )

staticnodiscard

Creates the frustum by extracting the planes from the given (model-view / projection) matrix.

If the matrix is just the projection matrix, the frustum will be in local space. Pass the full ModelViewProjection matrix to create the frustum in world-space. If the projection matrix contained in ModelViewProjection is an infinite plane projection matrix, the resulting frustum will yield a far plane with infinite distance.

Returns PL_SUCESS with a valid outFrustum if the operation was successful and PL_FAILURE otherwise.

TryMakeFromPlanes()

plResult plFrustum::TryMakeFromPlanes ( plFrustum & out_frustum, const plPlane * pPlanes )

staticnodiscard

Sets the frustum manually by specifying the planes directly.

Note

Make sure to pass in the planes in the order of the PlaneType enum, otherwise plFrustum may not always work as expected.

Returns PL_SUCESS with a valid outFrustum if the operation was successful and PL_FAILURE otherwise.

---

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

• Code/Engine/Foundation/Math/Frustum.h
• Code/Engine/Foundation/Math/Implementation/Frustum.cpp
• Code/Engine/Foundation/Math/Implementation/Frustum_inl.h