A class that represents a mathematical plane. More...

#include <Plane.h>

Public Types
using	ComponentType = Type

Public Member Functions
	XII_DECLARE_POD_TYPE ()

	xiiPlaneTemplate ()
	Default constructor. Does not initialize the plane.

xiiVec4Template< Type >	GetAsVec4 () const
	Returns a xiiVec4 with the plane normal in x,y,z and the negative distance in w.

xiiResult	SetFromPoints (const xiiVec3Template< Type > &v1, const xiiVec3Template< Type > &v2, const xiiVec3Template< Type > &v3)
	Creates the plane-equation from three points on the plane.

xiiResult	SetFromPoints (const xiiVec3Template< Type > *const pVertices)
	Creates the plane-equation from three points on the plane, given as an array.

xiiResult	SetFromPoints (const xiiVec3Template< Type > *const pVertices, xiiUInt32 uiMaxVertices)
	Creates the plane-equation from a set of unreliable points lying on the same plane. Some points might be equal or too close to each other for the typical algorithm. Returns false, if no reliable set of points could be found. Does try to create a plane anyway.

xiiResult	SetFromDirections (const xiiVec3Template< Type > &vTangent1, const xiiVec3Template< Type > &vTangent2, const xiiVec3Template< Type > &vPointOnPlane)
	Creates a plane from two direction vectors that span the plane, and one point on it.

Type	GetDistanceTo (const xiiVec3Template< Type > &vPoint) const
	Returns the distance of the point to the plane.

Type	GetMinimumDistanceTo (const xiiVec3Template< Type > *pPoints, xiiUInt32 uiNumPoints, xiiUInt32 uiStride=sizeof(xiiVec3Template< Type >)) const
	Returns the minimum distance that any of the given points had to the plane.

Type	GetMinimumDistanceTo (const xiiBoundingBoxTemplate< Type > &box) const
	Returns the minimum distance between given box and a plane.

Type	GetMaximumDistanceTo (const xiiBoundingBoxTemplate< Type > &box) const
	Returns the maximum distance between given box and a plane.

void	GetMinMaxDistanceTo (Type &out_fMin, Type &out_fMax, const xiiVec3Template< Type > *pPoints, xiiUInt32 uiNumPoints, xiiUInt32 uiStride=sizeof(xiiVec3Template< Type >)) const
	Returns the minimum and maximum distance that any of the given points had to the plane.

xiiPositionOnPlane::Enum	GetPointPosition (const xiiVec3Template< Type > &vPoint) const
	Returns on which side of the plane the point lies.

xiiPositionOnPlane::Enum	GetPointPosition (const xiiVec3Template< Type > &vPoint, Type fPlaneHalfWidth) const
	Returns on which side of the plane the point lies.

xiiPositionOnPlane::Enum	GetObjectPosition (const xiiVec3Template< Type > *const pPoints, xiiUInt32 uiVertices) const
	Returns on which side of the plane the set of points lies. Might be on both sides.

xiiPositionOnPlane::Enum	GetObjectPosition (const xiiVec3Template< Type > *const pPoints, xiiUInt32 uiVertices, Type fPlaneHalfWidth) const
	Returns on which side of the plane the set of points lies. Might be on both sides.

xiiPositionOnPlane::Enum	GetObjectPosition (const xiiBoundingSphereTemplate< Type > &sphere) const
	Returns on which side of the plane the sphere is located.

xiiPositionOnPlane::Enum	GetObjectPosition (const xiiBoundingBoxTemplate< Type > &box) const
	Returns on which side of the plane the box is located.

const xiiVec3Template< Type >	ProjectOntoPlane (const xiiVec3Template< Type > &vPoint) const
	Projects a point onto a plane (along the planes normal).

const xiiVec3Template< Type >	Mirror (const xiiVec3Template< Type > &vPoint) const
	Returns the mirrored point. E.g. on the other side of the plane, at the same distance.

const xiiVec3Template< Type >	GetCoplanarDirection (const xiiVec3Template< Type > &vDirection) const
	Take the given direction vector and returns a modified one that is coplanar to the plane.

bool	IsIdentical (const xiiPlaneTemplate< Type > &rhs) const
	Checks whether this plane and the other are identical.

bool	IsEqual (const xiiPlaneTemplate< Type > &rhs, Type fEpsilon=xiiMath::DefaultEpsilon< Type >()) const
	Checks whether this plane and the other are equal within some threshold.

bool	IsValid () const
	Checks whether the plane has valid values (not NaN, normalized normal).

bool	IsNaN () const
	Checks whether any component is NaN.

bool	IsFinite () const
	Checks whether any component is Infinity.

void	Transform (const xiiMat3Template< Type > &m)
	Transforms the plane with the given matrix.

void	Transform (const xiiMat4Template< Type > &m)
	Transforms the plane with the given matrix.

void	Flip ()
	Negates Normal/Distance to switch which side of the plane is front and back.

bool	FlipIfNecessary (const xiiVec3Template< Type > &vPoint, bool bPlaneShouldFacePoint=true)
	Negates Normal/Distance to switch which side of the plane is front and back. Returns true, if the plane had to be flipped.

bool	GetRayIntersection (const xiiVec3Template< Type > &vRayStartPos, const xiiVec3Template< Type > &vRayDir, Type out_pIntersectionDistance=nullptr, xiiVec3Template< Type > out_pIntersection=nullptr) const
	Returns true, if the ray hit the plane. The intersection time describes at which multiple of the ray direction the ray hit the plane.

bool	GetRayIntersectionBiDirectional (const xiiVec3Template< Type > &vRayStartPos, const xiiVec3Template< Type > &vRayDir, Type out_pIntersectionDistance=nullptr, xiiVec3Template< Type > out_pIntersection=nullptr) const
	Returns true, if the ray intersects the plane. Intersection time and point are stored in the out-parameters. Allows for intersections at negative times (shooting into the opposite direction).

bool	GetLineSegmentIntersection (const xiiVec3Template< Type > &vLineStartPos, const xiiVec3Template< Type > &vLineEndPos, Type out_pHitFraction=nullptr, xiiVec3Template< Type > out_pIntersection=nullptr) const
	Returns true, if there is any intersection with the plane between the line's start and end position. Returns the fraction along the line and the actual intersection point.

Static Public Member Functions
static xiiPlaneTemplate< Type >	MakeInvalid ()
	Returns an invalid plane with a zero normal.

static xiiPlaneTemplate< Type >	MakeFromNormalAndPoint (const xiiVec3Template< Type > &vNormal, const xiiVec3Template< Type > &vPointOnPlane)
	Creates a plane from a normal and a point on the plane.

static xiiPlaneTemplate< Type >	MakeFromPoints (const xiiVec3Template< Type > &v1, const xiiVec3Template< Type > &v2, const xiiVec3Template< Type > &v3)
	Creates a plane from three points.

static xiiResult	GetPlanesIntersectionPoint (const xiiPlaneTemplate< Type > &p0, const xiiPlaneTemplate< Type > &p1, const xiiPlaneTemplate< Type > &p2, xiiVec3Template< Type > &out_vResult)
	Computes the one point where all three planes intersect. Returns XII_FAILURE if no such point exists.

static xiiResult	FindSupportPoints (const xiiVec3Template< Type > *const pVertices, xiiInt32 iMaxVertices, xiiInt32 &out_i1, xiiInt32 &out_i2, xiiInt32 &out_i3)
	Returns three points from an unreliable set of points, that reliably form a plane. Returns false, if there are none.

Public Attributes
xiiVec3Template< Type >	m_vNormal

Type	m_fNegDistance

Detailed Description

template<typename Type>
struct xiiPlaneTemplate< Type >

A class that represents a mathematical plane.

Member Function Documentation

◆ GetMinimumDistanceTo()

template<typename Type>

Type xiiPlaneTemplate< Type >::GetMinimumDistanceTo	(	const xiiVec3Template< Type > *	pPoints,
		xiiUInt32	uiNumPoints,
		xiiUInt32	uiStride = sizeof(xiiVec3Template<Type>) ) const

Returns the minimum distance that any of the given points had to the plane.

'Minimum' means the (non-absolute) distance of a point to the plane. So a point behind the plane will always have a 'lower distance' than a point in front of the plane, even if that is closer to the plane's surface.

◆ GetMinMaxDistanceTo()

template<typename Type>

void xiiPlaneTemplate< Type >::GetMinMaxDistanceTo	(	Type &	out_fMin,
		Type &	out_fMax,
		const xiiVec3Template< Type > *	pPoints,
		xiiUInt32	uiNumPoints,
		xiiUInt32	uiStride = sizeof(xiiVec3Template<Type>) ) const

Returns the minimum and maximum distance that any of the given points had to the plane.

'Minimum' (and 'maximum') means the (non-absolute) distance of a point to the plane. So a point behind the plane will always have a 'lower distance' than a point in front of the plane, even if that is closer to the plane's surface.

◆ GetRayIntersection()

template<typename Type>

bool xiiPlaneTemplate< Type >::GetRayIntersection	(	const xiiVec3Template< Type > &	vRayStartPos,
		const xiiVec3Template< Type > &	vRayDir,
		Type *	out_pIntersectionDistance = nullptr,
		xiiVec3Template< Type > *	out_pIntersection = nullptr ) const

nodiscard

Returns true, if the ray hit the plane. The intersection time describes at which multiple of the ray direction the ray hit the plane.

An intersection will be reported regardless of whether the ray starts 'behind' or 'in front of' the plane, as long as it points at it. vRayDir does not need to be normalized.
out_vIntersection = vRayStartPos + out_fIntersection * vRayDir

Intersections with out_fIntersection less than zero will be discarded and not reported as intersections. If such intersections are desired, use GetRayIntersectionBiDirectional instead.

◆ MakeFromNormalAndPoint()

template<typename Type>

xiiPlaneTemplate< Type > xiiPlaneTemplate< Type >::MakeFromNormalAndPoint	(	const xiiVec3Template< Type > &	vNormal,
		const xiiVec3Template< Type > &	vPointOnPlane )

staticnodiscard

Creates a plane from a normal and a point on the plane.

Note: This function asserts that the normal is normalized.

◆ MakeFromPoints()

template<typename Type>

xiiPlaneTemplate< Type > xiiPlaneTemplate< Type >::MakeFromPoints	(	const xiiVec3Template< Type > &	v1,
		const xiiVec3Template< Type > &	v2,
		const xiiVec3Template< Type > &	v3 )

staticnodiscard

Creates a plane from three points.

Note: Asserts that the 3 points properly form a plane. Only use this function when you are certain that the input data isn't degenerate. If the data cannot be trusted, use SetFromPoints() and check the result.

◆ SetFromPoints()

template<typename Type>

xiiResult xiiPlaneTemplate< Type >::SetFromPoints	(	const xiiVec3Template< Type > *const	pVertices,
		xiiUInt32	uiMaxVertices )

Creates the plane-equation from a set of unreliable points lying on the same plane. Some points might be equal or too close to each other for the typical algorithm. Returns false, if no reliable set of points could be found. Does try to create a plane anyway.

The given vertices can be partially equal or lie on the same line. The algorithm will try to find 3 vertices, that form a plane, and deduce the normal from them. This algorithm is much slower, than all the other methods, so only use it, when you know, that your data can contain such configurations.

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

/home/runner/work/XII/XII/Source/Engine/Foundation/Math/Declarations.h
/home/runner/work/XII/XII/Source/Engine/Foundation/Math/Plane.h
/home/runner/work/XII/XII/Source/Engine/Foundation/Math/Implementation/AllClasses_inl.h
/home/runner/work/XII/XII/Source/Engine/Foundation/Math/Implementation/Plane_inl.h

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ GetMinimumDistanceTo()

◆ GetMinMaxDistanceTo()

◆ GetRayIntersection()

◆ MakeFromNormalAndPoint()

◆ MakeFromPoints()

◆ SetFromPoints()