Contents, API Reference, Interfaces, iMesh, positionNear3DPoint
Enables you to resolve a position in 3d space to a nearby position on the surface of this ground mesh.
cPosition positionNear3DPoint(int32_t x, int32_t y, int32_t z, int32_t horizontalRange, int32_t verticalRange) const;
X coordinate of the 3D query point.
Y coordinate of the 3D query point.
Z coordinate (height) of the 3D query point.
Looks for a position with x and y components within plus or minus horizontalRange of the target point x and y.
Looks for a position with ground height within plus or minus verticalRange of the target point z.
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.)
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).
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.
PathEngine.Position positionNear3DPoint(int x, int y, int z, int horizontalRange, int verticalRange);
Position positionNear3DPoint(int x, int y, int z, int horizontalRange, int verticalRange);