findClosestUnobstructedPosition

Contents, API Reference, Interfaces, iAgent, findClosestUnobstructedPosition

iAgent::findClosestUnobstructedPosition()

Description

Finds the closest unobstructed position, if one exists within a specified region around the agent's position.

Syntax

cPosition findClosestUnobstructedPosition(const iCollisionContext* context, tSigned32 maximumDistance) const;

Parameters

	context		The state of dynamic collision that will apply for this query. An empty context can be specified by passing a value of zero for this argument. Note that the agent is not considered to obstruct itself even if included in this context.
	maximumDistance		This parameter controls the size of the region within which to search for an unobstructed position. Must be greater than zero.

Requirements

Requires that the agent is moveable and that collision preprocess has been generated on the agent's mesh for the agent's collision shape.

Return Value

If an unobstructed point exists in the specified region then a cPosition is returned for that position.
Otherwise an explicitly invalid cPosition is returned, i.e. a position with cell set to -1.

Remarks

The region searched is an axis aligned rectangle defined by the agent's current position and maximumDistance, as follows:

x >= position.x - maximumDistance
x <= position.x + maximumDistance
y >= position.y - maximumDistance
y <= position.y + maximumDistance

Only positions reachable through the mesh within this region are searched. This prevents points on completely unconnected layers of overlapping geometry being returned.