findClosestUnobstructedPosition

previous: iMesh::constructPath_Reversed()

Contents, API Reference, Interfaces, iMesh, findClosestUnobstructedPosition

iMesh::findClosestUnobstructedPosition()

Description

Finds the closest unobstructed position, if one exists within a specified region around a given position.

Syntax

cPosition findClosestUnobstructedPosition(const iShape* shape, const iCollisionContext* context, const cPosition& position, tSigned32 maximumDistance) const;

Parameters

	shape		The collision shape to use for this query.
	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.
	position		The centre of the region within which to search for an unobstructed position.
	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 collision preprocess has been generated on this mesh for the collision shape specified.

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 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.
(This is essentially the same mechanism as is used for the path away queries, so see The path away query for further explanation of this mechanism, with screen shots.)

next: iMesh::findPathAway()