positionNear3DPoint

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(const tSigned32* point, tSigned32 horizontalRange, tSigned32 verticalRange) const;

Parameters

	point		This parameter must point to an array of three elements. These are interpreted as x,y,z, where z is height.
	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

When there is more than one piece of ground mesh within the specified ranges a resolved point will be chosen purely on the basis of distance in x and y. The z component is treated purely as a range.

The method uses a 'generate and test' approach to resolving the queried position, first testing position positions directly above and below the queried position, and then generating and testing positions at face boundaries.

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

next: iMesh::preprocessGenerationCompleted()