#include <positiononlivepath.h>

Class Description

This class aggregates all necessary information to describe a position on a LivePath, namely:

a PositionOnPath and
PathEventList related information.

Be careful with instances of this class: they are intended to be kept alive but, up to now, only the instance in Bot is maintained accordingly to LivePath updates. As a consequence, all the other instances can not be used through several frames.

You are not intended to create or manage instances of this class. Nevertheless, it is fully documented since you will probably need to read and interpret it.

Examples:: gamekit/Tutorial_CrowdDispersion.cpp.

Main API Functions
	PositionOnLivePath ()

void	BindToPathEventList (PathEventList *pathEventList)

PathEventList *	GetPathEventList () const

void	Clear ()

void	ClearEventListLocation ()

Comparison Operators
bool	operator== (const PositionOnLivePath &positionOnLivePath) const

bool	operator!= (const PositionOnLivePath &positionOnLivePath) const

Raw Path Related Functions
Path *	GetPath ()

const Path *	GetPath () const

const Vec3f &	GetPosition () const

const PositionOnPath &	GetPositionOnPath () const

PositionOnPathStatus	GetPositionOnPathStatus () const

PathEdgeType	GetPathEdgeType () const

bool	IsAtFirstNodeOfPath () const

bool	IsAtLastNodeOfPath () const

bool	IsAtFirstEdgeOfPath () const

bool	IsAtLastEdgeOfPath () const

KyUInt32	GetPathEdgeIndex () const

KyUInt32	GetEdgeIdxToMoveOnForward () const

PathEdgeType	GetEdgeTypeToMoveOnForward () const

PathEdgeType	GetEdgeTypeToMoveOnBackward () const

KyUInt32	GetEdgeIdxToMoveOnBackward () const

bool	DoesPrecede (const PositionOnLivePath &other) const

bool	IsStrictlyBefore (const PositionOnLivePath &other) const

void	InitOnPathFirstNode (Path *path)
	The 5 Init functions initialize the positionOnPath, but they also clear all the data concerning the location on the PathEventList. More...

void	InitOnPathLastNode (Path *path)

void	InitOnPathNode (Path *path, KyUInt32 pathNodeIdx)

void	InitOnPathEdge (Path *path, const Vec3f &positionOnEdge, KyUInt32 pathEdgeIdx)

void	InitOnPositionOnPath (const PositionOnPath &positionOnPath)

void	FindLocationOnEventListFromScratch ()
	This function computes the location on the PathEventList from the PositionOnPath. More...

PathEventList Related Functions
OnEventListStatus	GetOnEventListStatus () const

PathEvent	GetPathEvent (KyUInt32 pathEventIdx) const

PathEvent	GetCurrentPathEvent () const

KyUInt32	GetOnEventListIndex () const
	This function has to be used carefully: More...

KyUInt32	GetNextPathEventIdx () const
	This function has to be used carefully: More...

KyUInt32	GetPrevPathEventIdx () const
	This function has to be used carefully: More...

bool	IsAtLowerBoundOfLivePath () const

bool	IsAtUpperBoundOfLivePath () const

bool	IsAtACheckPoint () const
	Indicates if the PositionOnLIvePath is at an event that is a check point. More...

const PositionOnPath *	GetUpcomingEventPositionOnPath () const
	Returns a pointer to the PositionOnPath along the path after positionOnLivePath. More...

const NavTag *	GetCurrentOrNextNavTag () const
	Returns a pointer to the navTag along the path after the position on path. More...

const NavTag *	GetCurrentOrPreviousNavTag () const
	Returns a pointer to the navTag along the path before the position on path. More...

Move Functions
void	MoveForward (KyFloat32 distanceMove)
	This function moves forward the position along distanceMove meters measured on the broken-line. More...

void	MoveBackward (KyFloat32 distanceMove)
	This function moves backward the position along distanceMove meters measured on the broken-line. More...

void	MoveForward_StopAtPathNode (KyFloat32 distanceMove)
	This function moves forward the position along distanceMove meters measured on the broken-line. More...

void	MoveBackward_StopAtPathNode (KyFloat32 distanceMove)
	This function moves backward the position along distanceMove meters measured on the broken-line. More...

void	MoveForward_StopAtEvent (KyFloat32 distanceMove)
	This function moves forward the position along distanceMove meters measured on the broken-line. More...

void	MoveBackward_StopAtEvent (KyFloat32 distanceMove)
	This function moves backward the position along distanceMove meters measured on the broken-line. More...

void	MoveForward_StopAtEventOrAtPathNode (KyFloat32 distanceMove)
	This function moves forward the position along distanceMove meters measured on the broken-line. More...

void	MoveBackward_StopAtEventOrAtPathNode (KyFloat32 distanceMove)
	This function moves backward the position along distanceMove meters measured on the broken-line. More...

void	MoveToNextEventOrPathNode ()
	This function moves forward the position until an event or a pathNode is reached. More...

void	MoveToPrevEventOrPathNode ()
	This function moves backward the position until an event or a pathNode is reached. More...

void	MoveForward_StopAtCheckPoint (KyFloat32 distanceMove)
	This function moves forward the position along distanceMove meters measured on the broken-line. More...

void	MoveForwardToNextPathNode ()
	This function moves forward the position up to the next Path node. More...

void	MoveBackwardToPrevPathNode ()
	This function moves backward the position up to the previous Path node. More...

void	MoveToPathEvent (KyUInt32 pathEventIdx)
	This function moves the position to the specified path event. More...

void	MoveForwardToNextPathEvent ()
	This function moves forward the position up to the next path event. More...

void	MoveBackwardToPrevPathEvent ()
	This function moves backward the position up to the previous path event. More...

void	MoveForwardToNextPathEdge ()
	This function moves forward the position up to the start of the next path edge. More...

void	MoveBackwardToPrevPathEdge ()
	This function moves forward the position up to the start of the next path edge. More...

void	MoveForwardToNextPathEventInterval ()
	This function moves forward the position up to the next path event interval. More...

void	MoveForwardToNextCheckPoint ()
	This function moves forward the position up to the next path event that is a check point. More...

void	MoveBackwardToPrevCheckPoint ()
	This function moves backward the position up to the previous path event that is a check point. More...

KyFloat32	MoveForwardToClosestPositionOnPath (const Vec3f &position)
	Move forward to the closest position on path from originalPosition. More...

void	MoveForwardToNextPathEventWithPredicate (IMovePositionOnLivePathPredicate *predicate)
	This function will move positionOnLivePath forward until the predicate returns false. More...

void	MoveBackwardToPreviousEventWithPredicate (IMovePositionOnLivePathPredicate *predicate)
	This function will move positionOnLivePath backward until the predicate returns false. More...

void	SetNewPositionOnPathForward (const PositionOnPath &newPositionOnPathForward)
	Moves this PositionOnLivePath forward to the provided PositionOnPath and updates PathEventList related informations. More...

void	SetNewPositionOnPathBackward (const PositionOnPath &newPositionOnPathBackward)
	Moves this PositionOnLivePath backward to the provided PositionOnPath and updates PathEventList related informations. More...

Move Functions with Cost
template<class TraverseLogic >
void	MoveForwardAndGetCost_StopAtEventOrAtPathNode (void *traverseLogicUserData, KyFloat32 distanceMove, RayCanGoMarginMode rayCanGoMarginMode, KyFloat32 &cost)
	This function moves forward the position along distanceMove meters measured on the broken-line. More...

Unsafe Version of Functions
KyUInt32	GetNextPathEventIdx_Unsafe () const
	These functions are unsafe in regard to the pre-conditions mentioned in the functions of similar name without the _Unsafe prefix. More...

KyUInt32	GetPrevPathEventIdx_Unsafe () const

void	MoveForwardToNextPathEvent_Unsafe ()

void	MoveBackwardToPrevPathEvent_Unsafe ()

void	MoveForwardToNextPathEventInterval_Unsafe ()

Deprecated functions
const NavTag *	GetUpcomingEventNavTag () const

const NavTag *	GetPreviousEventNavTag () const

Member Function Documentation

void Kaim::PositionOnLivePath::FindLocationOnEventListFromScratch ( )

This function computes the location on the PathEventList from the PositionOnPath.

const NavTag * Kaim::PositionOnLivePath::GetCurrentOrNextNavTag ( ) const

inline

Returns a pointer to the navTag along the path after the position on path.

If position on path is on a PathEvent, it returns the NavTag between this PathEvent and the next PathEvent. If it lies strictly within two PathEvents, it returns the NavTag along this PathEventInterval Note: if position on path is at the upper bound of the validity interval, it will return nullptr.

const NavTag * Kaim::PositionOnLivePath::GetCurrentOrPreviousNavTag ( ) const

inline

Returns a pointer to the navTag along the path before the position on path.

If position on path is on a PathEvent, it returns the NavTag between this PathEvent and the previous PathEvent. If it lies strictly within two PathEvents, it returns the NavTag along this PathEventInterval Note: if position on path is at the lower bound of the validity interval, it will return nullptr.

KyUInt32 Kaim::PositionOnLivePath::GetNextPathEventIdx ( ) const

inline

This function has to be used carefully:

if this in on an PathEvent different from the UpperBound, it returns the index of the next PathEvent,
if this in on an EventInterval, it returns the index of the ending PathEvent. Can return KyUInt32MAXVAL if current instance is on the Upper bound or if it is not located on the PathEventList. if IsEventListStatusValid() == false, does nothing

KyUInt32 Kaim::PositionOnLivePath::GetNextPathEventIdx_Unsafe ( ) const

These functions are unsafe in regard to the pre-conditions mentioned in the functions of similar name without the _Unsafe prefix.

KyUInt32 Kaim::PositionOnLivePath::GetOnEventListIndex ( ) const

inline

This function has to be used carefully:

if the GetOnEventListStatus() == OnEvent, it returns the index of the PathEvent in the PathEventList,
if the GetOnEventListStatus() == OnEventInterval, it returns the index of the PathEventInterval in the PathEventList.

KyUInt32 Kaim::PositionOnLivePath::GetPrevPathEventIdx ( ) const

inline

This function has to be used carefully:

if this in on an PathEvent different from the LowerBound, it returns the index of the previous PathEvent,
if this in on an EventInterval, it returns the index of the starting PathEvent. Can return KyUInt32MAXVAL if current instance is on the Upper bound or if it is not located on the PathEventList. if IsEventListStatusValid() == false, does nothing

const PositionOnPath * Kaim::PositionOnLivePath::GetUpcomingEventPositionOnPath ( ) const

inline

Returns a pointer to the PositionOnPath along the path after positionOnLivePath.

If positionOnLivePath is on a PathEvent, it returns the current PositionOnPath of the event. If it lies strictly within two PathEvents, it returns the PositionOnPath at the end of this PathEventInterval Note: if position on path is at the upper bound of the validity interval, it will return nullptr.

void Kaim::PositionOnLivePath::InitOnPathFirstNode ( Path * path )

inline

The 5 Init functions initialize the positionOnPath, but they also clear all the data concerning the location on the PathEventList.

You can then call FindLocationOnEventListFromScratch() to have this object on a valid state.

bool Kaim::PositionOnLivePath::IsAtACheckPoint ( ) const

inline

Indicates if the PositionOnLIvePath is at an event that is a check point.

void Kaim::PositionOnLivePath::MoveBackward ( KyFloat32 distanceMove )

inline

This function moves backward the position along distanceMove meters measured on the broken-line.

If the LowerBound of the PathValidityInterval is reached, this instance is stopped at this lower bound.

Precondition: distanceMove >= 0.0f if IsEventListStatusValid() == false, does nothing

void Kaim::PositionOnLivePath::MoveBackward_StopAtEvent ( KyFloat32 distanceMove )

inline

This function moves backward the position along distanceMove meters measured on the broken-line.

If a PathEvent is reached before covering the distanceMove, this instance is stopped at this path event.

Precondition: distanceMove >= 0.0f if IsEventListStatusValid() == false, does nothing

void Kaim::PositionOnLivePath::MoveBackward_StopAtEventOrAtPathNode ( KyFloat32 distanceMove )

inline

This function moves backward the position along distanceMove meters measured on the broken-line.

If a PathEvent or a Path node is reached before covering the distanceMove, this instance is stopped at this PathEvent or Path node.

Precondition: distanceMove >= 0.0f if IsEventListStatusValid() == false, does nothing

void Kaim::PositionOnLivePath::MoveBackward_StopAtPathNode ( KyFloat32 distanceMove )

inline

This function moves backward the position along distanceMove meters measured on the broken-line.

If a Path node is reached before covering the distanceMove, this instance is stopped at this Path node. If the LowerBound of the PathValidityInterval is reached, this instance is stopped at this lower bound.

Precondition: distanceMove >= 0.0f if IsEventListStatusValid() == false, does nothing

void Kaim::PositionOnLivePath::MoveBackwardToPrevCheckPoint ( )

This function moves backward the position up to the previous path event that is a check point.

If located on the LowerBound, does nothing. if IsEventListStatusValid() == false, does nothing

void Kaim::PositionOnLivePath::MoveBackwardToPreviousEventWithPredicate ( IMovePositionOnLivePathPredicate * predicate )

This function will move positionOnLivePath backward until the predicate returns false.

If it reaches the LowerBound, it stops.

void Kaim::PositionOnLivePath::MoveBackwardToPrevPathEdge ( )

inline

This function moves forward the position up to the start of the next path edge.

If located on the LowerBound, does nothing. if IsEventListStatusValid() == false, does nothing.

void Kaim::PositionOnLivePath::MoveBackwardToPrevPathEvent ( )

inline

This function moves backward the position up to the previous path event.

If located on the LowerBound, does nothing. if IsEventListStatusValid() == false, does nothing.

void Kaim::PositionOnLivePath::MoveBackwardToPrevPathNode ( )

inline

This function moves backward the position up to the previous Path node.

If located on the LowerBound, does nothing. if IsEventListStatusValid() == false, does nothing.

void Kaim::PositionOnLivePath::MoveForward ( KyFloat32 distanceMove )

inline