xiiFrustum Class Reference

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

#include <Frustum.h>

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

Public Member Functions
	xiiFrustum ()
	The constructor does NOT initialize the frustum planes, make sure to call SetFrustum() before trying to use it.
const xiiPlane &	GetPlane (xiiUInt8 uiPlane) const
	Returns the n-th plane of the frustum.
xiiPlane &	AccessPlane (xiiUInt8 uiPlane)
	Returns the n-th plane of the frustum and allows modification.
bool	IsValid () const
	Checks that all planes are valid.
void	TransformFrustum (const xiiMat4 &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.
xiiFrustum	GetTransformedFrustum (const xiiMat4 &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.
xiiResult	ComputeCornerPoints (xiiVec3 out_pPoints[FrustumCorner::CORNER_COUNT]) const
	Computes the frustum corner points.
xiiVolumePosition::Enum	GetObjectPosition (const xiiVec3 *pVertices, xiiUInt32 uiNumVertices) const
	Checks whether the given object is inside or outside the frustum.
xiiVolumePosition::Enum	GetObjectPosition (const xiiVec3 *pVertices, xiiUInt32 uiNumVertices, const xiiMat4 &mObjectTransform) const
	Same as GetObjectPosition(), but applies a transformation to the given object first. This allows to do culling on instanced objects.
xiiVolumePosition::Enum	GetObjectPosition (const xiiBoundingSphere &sphere) const
	Checks whether the given object is inside or outside the frustum.
xiiVolumePosition::Enum	GetObjectPosition (const xiiBoundingBox &box) const
	Checks whether the given object is inside or outside the frustum.
bool	Overlaps (const xiiSimdBBox &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 xiiSimdBSphere &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 xiiFrustum	MakeInvalid ()
	Returns an invalid frustum with all planes set to zero.
static xiiFrustum	MakeFromPlanes (const xiiPlane *pPlanes)
	Sets the frustum manually by specifying the planes directly.
static xiiResult	TryMakeFromPlanes (xiiFrustum &out_frustum, const xiiPlane *pPlanes)
	Sets the frustum manually by specifying the planes directly.
static xiiFrustum	MakeFromMVP (const xiiMat4 &mModelViewProjection, xiiClipSpaceDepthRange::Enum depthRange=xiiClipSpaceDepthRange::Default, xiiHandedness::Enum handedness=xiiHandedness::Default)
	Creates the frustum by extracting the planes from the given (model-view / projection) matrix.
static xiiResult	TryMakeFromMVP (xiiFrustum &out_frustum, const xiiMat4 &mModelViewProjection, xiiClipSpaceDepthRange::Enum depthRange=xiiClipSpaceDepthRange::Default, xiiHandedness::Enum handedness=xiiHandedness::Default)
	Creates the frustum by extracting the planes from the given (model-view / projection) matrix.
static xiiFrustum	MakeFromFOV (const xiiVec3 &vPosition, const xiiVec3 &vForwards, const xiiVec3 &vUp, xiiAngle fovX, xiiAngle 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 xiiResult	TryMakeFromFOV (xiiFrustum &out_frustum, const xiiVec3 &vPosition, const xiiVec3 &vForwards, const xiiVec3 &vUp, xiiAngle fovX, xiiAngle 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 xiiFrustum	MakeFromCorners (const xiiVec3 pCorners[FrustumCorner::CORNER_COUNT])
	Creates a frustum from 8 corner points.
static xiiResult	TryMakeFromCorners (xiiFrustum &out_frustum, const xiiVec3 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()

xiiResult xiiFrustum::ComputeCornerPoints

(

xiiVec3

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]

xiiVolumePosition::Enum xiiFrustum::GetObjectPosition

(

const xiiBoundingBox &

box

)

const

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

Test

Not yet tested

GetObjectPosition() [2/4]

xiiVolumePosition::Enum xiiFrustum::GetObjectPosition

(

const xiiBoundingSphere &

sphere

)

const

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

Test

Not yet tested

GetObjectPosition() [3/4]

xiiVolumePosition::Enum xiiFrustum::GetObjectPosition	(	const xiiVec3 *	pVertices,
		xiiUInt32	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]

xiiVolumePosition::Enum xiiFrustum::GetObjectPosition	(	const xiiVec3 *	pVertices,
		xiiUInt32	uiNumVertices,
		const xiiMat4 &	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()

xiiFrustum xiiFrustum::MakeFromCorners ( const xiiVec3 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()

xiiFrustum xiiFrustum::MakeFromFOV ( const xiiVec3 & vPosition, const xiiVec3 & vForwards, const xiiVec3 & vUp, xiiAngle fovX, xiiAngle 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()

xiiFrustum xiiFrustum::MakeFromMVP ( const xiiMat4 & mModelViewProjection, xiiClipSpaceDepthRange::Enum depthRange = xiiClipSpaceDepthRange::Default, xiiHandedness::Enum handedness = xiiHandedness::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()

xiiFrustum xiiFrustum::MakeFromPlanes ( const xiiPlane * 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 xiiFrustum may not always work as expected.

Overlaps() [1/2]

XII_FORCE_INLINE bool xiiFrustum::Overlaps

(

const xiiSimdBBox &

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]

XII_FORCE_INLINE bool xiiFrustum::Overlaps

(

const xiiSimdBSphere &

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()

xiiResult xiiFrustum::TryMakeFromCorners ( xiiFrustum & out_frustum, const xiiVec3 pCorners[FrustumCorner::CORNER_COUNT] )

staticnodiscard

Creates a frustum from 8 corner points.

Returns XII_SUCESS with a valid outFrustum if the operation was successful and XII_FAILURE otherwise.

TryMakeFromFOV()

xiiResult xiiFrustum::TryMakeFromFOV ( xiiFrustum & out_frustum, const xiiVec3 & vPosition, const xiiVec3 & vForwards, const xiiVec3 & vUp, xiiAngle fovX, xiiAngle 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 XII_SUCESS with a valid outFrustum if the operation was successful and XII_FAILURE otherwise.

TryMakeFromMVP()

xiiResult xiiFrustum::TryMakeFromMVP ( xiiFrustum & out_frustum, const xiiMat4 & mModelViewProjection, xiiClipSpaceDepthRange::Enum depthRange = xiiClipSpaceDepthRange::Default, xiiHandedness::Enum handedness = xiiHandedness::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 XII_SUCESS with a valid outFrustum if the operation was successful and XII_FAILURE otherwise.

TryMakeFromPlanes()

xiiResult xiiFrustum::TryMakeFromPlanes ( xiiFrustum & out_frustum, const xiiPlane * 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 xiiFrustum may not always work as expected.

Returns XII_SUCESS with a valid outFrustum if the operation was successful and XII_FAILURE otherwise.

---

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

• /home/runner/work/XII/XII/Source/Engine/Foundation/Math/Frustum.h
• /home/runner/work/XII/XII/Source/Engine/Foundation/Math/Implementation/Frustum.cpp
• /home/runner/work/XII/XII/Source/Engine/Foundation/Math/Implementation/Frustum_inl.h