placeProjected3DObstruction

previous: iMesh::placeLargeStaticObstacle()

Contents, API Reference, Interfaces, iMesh, placeProjected3DObstruction

iMesh::placeProjected3DObstruction()

Description

Constructs an Interface iAgent object to represent the way in which a piece of 3D geometry obstructs a specified ground layer.

Syntax

std::unique_ptr<iAgent> placeProjected3DObstruction(const iFaceVertexMesh* facesToProject, const cPosition& rootFrom, int32_t agentHeight) const

Parameters

	facesToProject		Pointer to an object derived from Interface iFaceVertexMesh for a set of 3D faces to be projected. This object must be non-empty (i.e. mesh->faces() must not be zero). PathEngine does not hold any reference to the object after the method has completed, and the client application remains responsible for deleting the object.
	rootFrom		A position nearby or underneath the 3D obstruction to indicate which part of the mesh the obstruction should be projected to.
	agentHeight		Nominal agent height to be applied for the purpose of this method. Geometry within this distance above rootFrom will be included in the projection. Must be greater than zero.

Return Value

If the projected obstruction shape is empty (e.g. because the 3D obstruction geometry is completely above the specified agent height), a null pointer is returned.

If no 'root point' can be resolved for the projected obstruction shape (e.g. because there is no mesh connectivity between rootFrom and the centre of the projected shape, or in certain pathological cases such as sliver geometry having no contained integer point), a null pointer is returned.

Otherwise, a newly created Interface iAgent is returned for the placed obstruction.
Note that this returned agent can only be used as an obstruction, i.e. the agent cannot subsequently be moved, and collision and pathfinding queries cannot be made for the agent, but the agent can be included in collision contexts and burnt into meshes.

Remarks

The interface class mechanism used to pass 3D geometry data for the facesToProject object is the same mechanism as is used to pass mesh data in to PathEngine in the 2D and 3D content processing.
It is up to the application as to exactly how this object is setup, but this could be a implemented, for example, as a wrapper class that just references some existing application side data structure.
(See this page for an example.)

The 3D coordinates in the facesToProject object are in 'pathfinding world coordinates' (i.e. not relative to rootFrom).
These coordinates are then subject to the overall PathEngine world constraint. (See PathEngine Coordinates.)

Before projection, the geometry is first clipped to a vertical range determined based on the height of the ground at rootFrom, and the agentHeight value specified.
A 2D convex hull is then thrown around the resulting set of vertices, and used to construct an Interface iAgent object in similar way as with iMesh::placeLargeStaticObstacle().

Some discussion of PathEngine's runtime shape management functionality, in general, can be found here.

C# Mapping

Agent placeProjected3DObstruction(FaceVertexMesh facesToProject, PathEngine.Position rootFrom, int agentHeight);

Java Mapping

Agent placeProjected3DObstruction(FaceVertexMesh facesToProject, Position rootFrom, int agentHeight);

next: iMesh::pointIsIn3DFace()