PathEngine home previous: iMesh::findClosestUnobstructedPosition()next: iMesh::findPathAway()
Contents, API Reference, Interfaces, iMesh, findClosestUnobstructedPositionEx



Finds the closest unobstructed position to a specified target, within a specified query range and within local mesh as defined by a set of supplied root positions, if one exists (with an optional connectivity constraint based on connected regions preprocess).


cPosition findClosestUnobstructedPositionEx(const iShape& shape, const iCollisionContext* context, cPosition const * rootPositions_Buffer, uint32_t rootPositions_BufferEntries, const cHorizontalRange& queryRegion, int32_t targetX, int32_t targetY, int32_t const * permittedConnectedRegions_Buffer, uint32_t permittedConnectedRegions_BufferEntries) const;


shape The agent 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 nullptr for this argument.
rootPositions_Buffer, rootPositions_BufferEntries (See Passing Arrays.) A set of root positions.
queryRegion Minimum and maximum bounds for the query in X and Y. (Values must be inside the PathEngine horizontal coordinate range limit, and this range must contain all of the supplied root positions.)
targetX Target X coordinate. (Must be within the PathEngine horizontal coordinate range limit.)
targetY Target Y coordinate. (Must be within the PathEngine horizontal coordinate range limit.)
permittedConnectedRegions_Buffer, permittedConnectedRegions_BufferEntries (See Passing Arrays.) If non empty then a connectivity constraint is applied, with this set of connected regions. If empty, then no connectivity constraint is applied.


Requires that unobstructed space has been generated on this mesh for the query shape.

If a connectivity constraint is applied (i.e. if permittedConnectedRegions is non empty) then connected region preprocess must also be present for that shape.

Return Value

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


This method searches for the nearest point (in terms of the horizontal distance component) to the specified target coordinates.

The position array arguments supply a set of root positions, which must all be inside queryRegion.
The query will then only search for candidates within mesh which is locally reachable through ground mesh within this queryRegion.

(The main intended use-case for this, at the time of writing, is to pass through a set of root positions obtained from iMesh::resolvePositionsNear3DPoint(), as a way of resolving an unobstructed position through a specified point in 3D space, but you can also just call this method with a single root position as a way to get other advanced query functionality not provided by the base iMesh::findClosestUnobstructedPosition() query, or obtain multiple root positions available from some other source, perhaps with external filtering to ensure that the root positions all fall inside the specified query range.)

The target position (specified with targetX and targetY) then specify the position from which distances should be measured, i.e. the query attempts to find the closest unobstructed position to this point.

Note that this method differs from the simpler iMesh::findClosestUnobstructedPosition() version in that:

If a connectivity constraint is supplied then only positions that are within the specified set of connected regions will be considered.

If there is a preprocessed obstacle set included in context then connected regions will be checked against the connected region preprocess from this preprocessed obstacle set (and the supplied region IDs should then come from that preprocessed obstacle set), otherwise connected regions will be checked against base mesh connected region preprocess.

Note that the query supports more than one connected region ID to enable the calling application to keep track of a set of connected regions that are reachable through off-mesh connections, if desired (but this could also be used, more generally, just to find positions that are reachable from more than one connected region).

C# Mapping

PathEngine.Position findClosestUnobstructedPositionEx(Shape shape, CollisionContext context, PathEngine.Position[] rootPositions, PathEngine.HorizontalRange queryRegion, int targetX, int targetY, int[] permittedConnectedRegions);

Documentation for PathEngine release 6.03 - Copyright © 2002-2021 PathEnginenext: iMesh::findPathAway()