iMesh::findClosestUnobstructedPositionEx()

Description

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).

Syntax

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;

Parameters

Requirements

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

Remarks

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:

• More than one root position can be supplied (and together with iMesh::resolvePositionsNear3DPoint(), this then means that you can effectively do a search for closest unobstructed space position from arbitrary 3D positions)
• The query region is specified as a generalised 3D range, and therefore does not have to be centred on the target position
• An additional 'connectivity constraint' can be supplied

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);