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

#include <Frustum.h>

Public Types
enum	PlaneType : ezUInt8 { NearPlane, LeftPlane, RightPlane, FarPlane, BottomPlane, TopPlane, PLANE_COUNT }

enum	FrustumCorner : ezUInt8 { NearTopLeft, NearTopRight, NearBottomLeft, NearBottomRight, FarTopLeft, FarTopRight, FarBottomLeft, FarBottomRight, CORNER_COUNT = 8 }

Public Member Functions
	ezFrustum ()
	The constructor does NOT initialize the frustum planes, make sure to call SetFrustum() before trying to use it.

const ezPlane &	GetPlane (ezUInt8 uiPlane) const
	Returns the n-th plane of the frustum.

ezPlane &	AccessPlane (ezUInt8 uiPlane)
	Returns the n-th plane of the frustum and allows modification.

bool	IsValid () const
	Checks that all planes are valid.

void	TransformFrustum (const ezMat4 &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.

ezFrustum	GetTransformedFrustum (const ezMat4 &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.

ezResult	ComputeCornerPoints (ezVec3 out_pPoints[FrustumCorner::CORNER_COUNT]) const
	Computes the frustum corner points. More...

ezVolumePosition::Enum	GetObjectPosition (const ezVec3 *pVertices, ezUInt32 uiNumVertices) const
	Checks whether the given object is inside or outside the frustum. More...

ezVolumePosition::Enum	GetObjectPosition (const ezVec3 *pVertices, ezUInt32 uiNumVertices, const ezMat4 &mObjectTransform) const
	Same as GetObjectPosition(), but applies a transformation to the given object first. This allows to do culling on instanced objects. More...

ezVolumePosition::Enum	GetObjectPosition (const ezBoundingSphere &sphere) const
	Checks whether the given object is inside or outside the frustum. More...

ezVolumePosition::Enum	GetObjectPosition (const ezBoundingBox &box) const
	Checks whether the given object is inside or outside the frustum. More...

bool	Overlaps (const ezSimdBBox &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. More...

bool	Overlaps (const ezSimdBSphere &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. More...

Static Public Member Functions
static ezFrustum	MakeInvalid ()
	Returns an invalid frustum with all planes set to zero.

static ezFrustum	MakeFromPlanes (const ezPlane *pPlanes)
	Sets the frustum manually by specifying the planes directly. More...

static ezResult	TryMakeFromPlanes (ezFrustum &out_frustum, const ezPlane *pPlanes)
	Sets the frustum manually by specifying the planes directly. More...

static ezFrustum	MakeFromMVP (const ezMat4 &mModelViewProjection, ezClipSpaceDepthRange::Enum depthRange=ezClipSpaceDepthRange::Default, ezHandedness::Enum handedness=ezHandedness::Default)
	Creates the frustum by extracting the planes from the given (model-view / projection) matrix. More...

static ezResult	TryMakeFromMVP (ezFrustum &out_frustum, const ezMat4 &mModelViewProjection, ezClipSpaceDepthRange::Enum depthRange=ezClipSpaceDepthRange::Default, ezHandedness::Enum handedness=ezHandedness::Default)
	Creates the frustum by extracting the planes from the given (model-view / projection) matrix. More...

static ezFrustum	MakeFromFOV (const ezVec3 &vPosition, const ezVec3 &vForwards, const ezVec3 &vUp, ezAngle fovX, ezAngle fovY, float fNearPlane, float fFarPlane)
	Creates a frustum from the given camera position, direction vectors and the field-of-view along X and Y. More...

static ezResult	TryMakeFromFOV (ezFrustum &out_frustum, const ezVec3 &vPosition, const ezVec3 &vForwards, const ezVec3 &vUp, ezAngle fovX, ezAngle fovY, float fNearPlane, float fFarPlane)
	Creates a frustum from the given camera position, direction vectors and the field-of-view along X and Y. More...

static ezFrustum	MakeFromCorners (const ezVec3 pCorners[FrustumCorner::CORNER_COUNT])
	Creates a frustum from 8 corner points. More...

static ezResult	TryMakeFromCorners (ezFrustum &out_frustum, const ezVec3 pCorners[FrustumCorner::CORNER_COUNT])
	Creates a frustum from 8 corner points. More...

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

ezResult ezFrustum::ComputeCornerPoints ( ezVec3 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]

ezVolumePosition::Enum ezFrustum::GetObjectPosition ( const ezBoundingBox & box ) const

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

Test:: Not yet tested

◆ GetObjectPosition() [2/4]

ezVolumePosition::Enum ezFrustum::GetObjectPosition ( const ezBoundingSphere & sphere ) const

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

Test:: Not yet tested

◆ GetObjectPosition() [3/4]

ezVolumePosition::Enum ezFrustum::GetObjectPosition	(	const ezVec3 *	pVertices,
		ezUInt32	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]

ezVolumePosition::Enum ezFrustum::GetObjectPosition	(	const ezVec3 *	pVertices,
		ezUInt32	uiNumVertices,
		const ezMat4 &	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()

ezFrustum ezFrustum::MakeFromCorners ( const ezVec3 pCorners[FrustumCorner::CORNER_COUNT] )

static

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

ezFrustum ezFrustum::MakeFromFOV	(	const ezVec3 &	vPosition,
		const ezVec3 &	vForwards,
		const ezVec3 &	vUp,
		ezAngle	fovX,
		ezAngle	fovY,
		float	fNearPlane,
		float	fFarPlane
	)

static

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

ezFrustum ezFrustum::MakeFromMVP	(	const ezMat4 &	mModelViewProjection,
		ezClipSpaceDepthRange::Enum	depthRange = `ezClipSpaceDepthRange::Default`,
		ezHandedness::Enum	handedness = `ezHandedness::Default`
	)

static

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

ezFrustum ezFrustum::MakeFromPlanes ( const ezPlane * pPlanes )

static

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 ezFrustum may not always work as expected.

◆ Overlaps() [1/2]

EZ_FORCE_INLINE bool ezFrustum::Overlaps ( const ezSimdBBox & 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]

EZ_FORCE_INLINE bool ezFrustum::Overlaps ( const ezSimdBSphere & 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()

ezResult ezFrustum::TryMakeFromCorners	(	ezFrustum &	out_frustum,
		const ezVec3	pCorners[FrustumCorner::CORNER_COUNT]
	)

static

Creates a frustum from 8 corner points.

Returns EZ_SUCESS with a valid outFrustum if the operation was successful and EZ_FAILURE otherwise.

◆ TryMakeFromFOV()

ezResult ezFrustum::TryMakeFromFOV	(	ezFrustum &	out_frustum,
		const ezVec3 &	vPosition,
		const ezVec3 &	vForwards,
		const ezVec3 &	vUp,
		ezAngle	fovX,
		ezAngle	fovY,
		float	fNearPlane,
		float	fFarPlane
	)

static

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 EZ_SUCESS with a valid outFrustum if the operation was successful and EZ_FAILURE otherwise.

◆ TryMakeFromMVP()

ezResult ezFrustum::TryMakeFromMVP	(	ezFrustum &	out_frustum,
		const ezMat4 &	mModelViewProjection,
		ezClipSpaceDepthRange::Enum	depthRange = `ezClipSpaceDepthRange::Default`,
		ezHandedness::Enum	handedness = `ezHandedness::Default`
	)

static

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 EZ_SUCESS with a valid outFrustum if the operation was successful and EZ_FAILURE otherwise.

◆ TryMakeFromPlanes()

ezResult ezFrustum::TryMakeFromPlanes	(	ezFrustum &	out_frustum,
		const ezPlane *	pPlanes
	)

static

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 ezFrustum may not always work as expected.

Returns EZ_SUCESS with a valid outFrustum if the operation was successful and EZ_FAILURE otherwise.

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

/home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/Math/Frustum.h
/home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/Math/Implementation/Frustum.cpp
/home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/Math/Implementation/Frustum_inl.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ ComputeCornerPoints()

◆ GetObjectPosition() [1/4]

◆ GetObjectPosition() [2/4]

◆ GetObjectPosition() [3/4]

◆ GetObjectPosition() [4/4]

◆ MakeFromCorners()

◆ MakeFromFOV()

◆ MakeFromMVP()

◆ MakeFromPlanes()

◆ Overlaps() [1/2]

◆ Overlaps() [2/2]

◆ TryMakeFromCorners()

◆ TryMakeFromFOV()

◆ TryMakeFromMVP()

◆ TryMakeFromPlanes()