PathEngine home previous: iMesh::positionIsValid()next: iMesh::preprocessGenerationCompleted()
Contents, API Reference, Interfaces, iMesh, positionNear3DPoint

iMesh::positionNear3DPoint()

Description

Enables you to resolve a position in 3d space to a nearby position on the surface of this ground mesh.

Syntax

cPosition positionNear3DPoint(int32_t x, int32_t y, int32_t z, int32_t horizontalRange, int32_t verticalRange) const;

Parameters

x X coordinate of the 3D query point.
y Y coordinate of the 3D query point.
z Z coordinate (height) of the 3D query point.
horizontalRange Looks for a position with x and y components within plus or minus horizontalRange of the target point x and y.
verticalRange Looks for a position with ground height within plus or minus verticalRange of the target point z.

Requirements

The range resulting from adding and subtracting horizontalRange to the horizontal components of point must not overflow the supported range for world coordinates.
(See PathEngine Coordinates.)

Return Value

A cPosition representing a point on the mesh (approximately) within the specified range.
If there is no such position then an explicitly invalid position is returned (i.e. a cPosition with cell set to -1).

Remarks

The method uses a 'generate and test' approach to resolving the queried position, base on positions generated directly above and below the queried position, and just inside the ground mesh boundaries.
The closest position to the supplied query point is then returned.

In most situations where there is geometry close to the query point, this method should do a good job of resolving a suitable ground position, and is therefore a good choice for things like resolving positions corresponding to mouse clicks, and so forth.

In certain situations where ground immediately below the queried point is outside the vertical range and then dips or rises back into the query volume within the horizontal range, the method may not find the geometrically closest point within that query volume and (in certain pathological conditions) may even fail to resolve a point even though a potential candidate does exist.
('Query volume', here refers to the volume obtained by adding horizontal and vertical ranges to the queried position.)

See Converting to and from PathEngine's Position Representation for an overview of all the position conversion methods.

C# Mapping

PathEngine.Position positionNear3DPoint(int x, int y, int z, int horizontalRange, int verticalRange);

Java Mapping

Position positionNear3DPoint(int x, int y, int z, int horizontalRange, int verticalRange);

Documentation for PathEngine release 6.04 - Copyright © 2002-2024 PathEnginenext: iMesh::preprocessGenerationCompleted()