Members in this module are used to create mesh data that is then used to create Detour navigation meshes. More...

Classes
class	rcContext
	Provides an interface for optional logging and performance tracking of the Recast build process. More...

struct	rcConfig
	Specifies a configuration to use when performing Recast builds. More...

struct	rcHeightfield
	A dynamic heightfield representing obstructed space. More...

struct	rcCompactHeightfield
	A compact, static heightfield representing unobstructed space. More...

struct	rcHeightfieldLayerSet
	Represents a set of heightfield layers. More...

struct	rcContourSet
	Represents a group of related contours. More...

struct	rcPolyMesh
	Represents a polygon mesh suitable for use in building a navigation mesh. More...

struct	rcPolyMeshDetail
	Contains triangle meshes that represent detailed height data associated with the polygons in its associated polygon mesh object. More...

Allocation Functions
Functions used to allocate and de-allocate Recast objects. See also rcAllocSetCustom
rcHeightfield *	rcAllocHeightfield ()
	Allocates a heightfield object using the Recast allocator. More...

void	rcFreeHeightField (rcHeightfield *heightfield)
	Frees the specified heightfield object using the Recast allocator. More...

rcCompactHeightfield *	rcAllocCompactHeightfield ()
	Allocates a compact heightfield object using the Recast allocator. More...

void	rcFreeCompactHeightfield (rcCompactHeightfield *compactHeightfield)
	Frees the specified compact heightfield object using the Recast allocator. More...

rcHeightfieldLayerSet *	rcAllocHeightfieldLayerSet ()
	Allocates a heightfield layer set using the Recast allocator. More...

void	rcFreeHeightfieldLayerSet (rcHeightfieldLayerSet *layerSet)
	Frees the specified heightfield layer set using the Recast allocator. More...

rcContourSet *	rcAllocContourSet ()
	Allocates a contour set object using the Recast allocator. More...

void	rcFreeContourSet (rcContourSet *contourSet)
	Frees the specified contour set using the Recast allocator. More...

rcPolyMesh *	rcAllocPolyMesh ()
	Allocates a polygon mesh object using the Recast allocator. More...

void	rcFreePolyMesh (rcPolyMesh *polyMesh)
	Frees the specified polygon mesh using the Recast allocator. More...

rcPolyMeshDetail *	rcAllocPolyMeshDetail ()
	Allocates a detail mesh object using the Recast allocator. More...

void	rcFreePolyMeshDetail (rcPolyMeshDetail *detailMesh)
	Frees the specified detail mesh using the Recast allocator. More...

Heightfield Functions
See also rcHeightfield
void	rcCalcBounds (const float verts, int numVerts, float minBounds, float *maxBounds)
	Calculates the bounding box of an array of vertices. More...

void	rcCalcGridSize (const float minBounds, const float maxBounds, float cellSize, int sizeX, int sizeZ)
	Calculates the grid size based on the bounding box and grid cell size. More...

bool	rcCreateHeightfield (rcContext context, rcHeightfield &heightfield, int sizeX, int sizeZ, const float minBounds, const float *maxBounds, float cellSize, float cellHeight)
	Initializes a new heightfield. More...

void	rcMarkWalkableTriangles (rcContext context, float walkableSlopeAngle, const float verts, int numVerts, const int tris, int numTris, unsigned char triAreaIDs)
	Sets the area id of all triangles with a slope below the specified value to RC_WALKABLE_AREA. More...

void	rcClearUnwalkableTriangles (rcContext context, float walkableSlopeAngle, const float verts, int numVerts, const int tris, int numTris, unsigned char triAreaIDs)
	Sets the area id of all triangles with a slope greater than or equal to the specified value to RC_NULL_AREA. More...

bool	rcAddSpan (rcContext *context, rcHeightfield &heightfield, int x, int z, unsigned short spanMin, unsigned short spanMax, unsigned char areaID, int flagMergeThreshold)
	Adds a span to the specified heightfield. More...

bool	rcRasterizeTriangle (rcContext context, const float v0, const float v1, const float v2, unsigned char areaID, rcHeightfield &heightfield, int flagMergeThreshold=1)
	Rasterizes a single triangle into the specified heightfield. More...

bool	rcRasterizeTriangles (rcContext context, const float verts, int numVerts, const int tris, const unsigned char triAreaIDs, int numTris, rcHeightfield &heightfield, int flagMergeThreshold=1)
	Rasterizes an indexed triangle mesh into the specified heightfield. More...

bool	rcRasterizeTriangles (rcContext context, const float verts, int numVerts, const unsigned short tris, const unsigned char triAreaIDs, int numTris, rcHeightfield &heightfield, int flagMergeThreshold=1)
	Rasterizes an indexed triangle mesh into the specified heightfield. More...

bool	rcRasterizeTriangles (rcContext context, const float verts, const unsigned char *triAreaIDs, int numTris, rcHeightfield &heightfield, int flagMergeThreshold=1)
	Rasterizes a triangle list into the specified heightfield. More...

void	rcFilterLowHangingWalkableObstacles (rcContext *context, int walkableClimb, rcHeightfield &heightfield)
	Marks non-walkable spans as walkable if their maximum is within `walkableClimb` of the span below them. More...

void	rcFilterLedgeSpans (rcContext *context, int walkableHeight, int walkableClimb, rcHeightfield &heightfield)
	Marks spans that are ledges as not-walkable. More...

void	rcFilterWalkableLowHeightSpans (rcContext *context, int walkableHeight, rcHeightfield &heightfield)
	Marks walkable spans as not walkable if the clearance above the span is less than the specified walkableHeight. More...

int	rcGetHeightFieldSpanCount (rcContext *context, const rcHeightfield &heightfield)
	Returns the number of spans contained in the specified heightfield. More...

Compact Heightfield Functions
See also rcCompactHeightfield
bool	rcBuildCompactHeightfield (rcContext *context, int walkableHeight, int walkableClimb, const rcHeightfield &heightfield, rcCompactHeightfield &compactHeightfield)
	Builds a compact heightfield representing open space, from a heightfield representing solid space. More...

bool	rcErodeWalkableArea (rcContext *context, int erosionRadius, rcCompactHeightfield &compactHeightfield)
	Erodes the walkable area within the heightfield by the specified radius. More...

bool	rcMedianFilterWalkableArea (rcContext *context, rcCompactHeightfield &compactHeightfield)
	Applies a median filter to walkable area types (based on area id), removing noise. More...

void	rcMarkBoxArea (rcContext context, const float boxMinBounds, const float *boxMaxBounds, unsigned char areaId, rcCompactHeightfield &compactHeightfield)
	Applies an area id to all spans within the specified bounding box. More...

void	rcMarkConvexPolyArea (rcContext context, const float verts, int numVerts, float minY, float maxY, unsigned char areaId, rcCompactHeightfield &compactHeightfield)
	Applies the area id to the all spans within the specified convex polygon. More...

int	rcOffsetPoly (const float verts, int numVerts, float offset, float outVerts, int maxOutVerts)
	Expands a convex polygon along its vertex normals by the given offset amount. More...

void	rcMarkCylinderArea (rcContext context, const float position, float radius, float height, unsigned char areaId, rcCompactHeightfield &compactHeightfield)
	Applies the area id to all spans within the specified y-axis-aligned cylinder. More...

bool	rcBuildDistanceField (rcContext *ctx, rcCompactHeightfield &chf)
	Builds the distance field for the specified compact heightfield. More...

bool	rcBuildRegions (rcContext *ctx, rcCompactHeightfield &chf, int borderSize, int minRegionArea, int mergeRegionArea)
	Builds region data for the heightfield using watershed partitioning. More...

bool	rcBuildLayerRegions (rcContext *ctx, rcCompactHeightfield &chf, int borderSize, int minRegionArea)
	Builds region data for the heightfield by partitioning the heightfield in non-overlapping layers. More...

bool	rcBuildRegionsMonotone (rcContext *ctx, rcCompactHeightfield &chf, int borderSize, int minRegionArea, int mergeRegionArea)
	Builds region data for the heightfield using simple monotone partitioning. More...

void	rcSetCon (rcCompactSpan &span, int direction, int neighborIndex)
	Sets the neighbor connection data for the specified direction. More...

int	rcGetCon (const rcCompactSpan &span, int direction)
	Gets neighbor connection data for the specified direction. More...

int	rcGetDirOffsetX (int direction)
	Gets the standard width (x-axis) offset for the specified direction. More...

int	rcGetDirOffsetY (int direction)
	Gets the standard height (z-axis) offset for the specified direction. More...

int	rcGetDirForOffset (int offsetX, int offsetZ)
	Gets the direction for the specified offset. More...

Layer, Contour, Polymesh, and Detail Mesh Functions
See also rcHeightfieldLayer, rcContourSet, rcPolyMesh, rcPolyMeshDetail
bool	rcBuildHeightfieldLayers (rcContext *ctx, const rcCompactHeightfield &chf, int borderSize, int walkableHeight, rcHeightfieldLayerSet &lset)
	Builds a layer set from the specified compact heightfield. More...

bool	rcBuildContours (rcContext *ctx, const rcCompactHeightfield &chf, float maxError, int maxEdgeLen, rcContourSet &cset, int buildFlags=RC_CONTOUR_TESS_WALL_EDGES)
	Builds a contour set from the region outlines in the provided compact heightfield. More...

bool	rcBuildPolyMesh (rcContext *ctx, const rcContourSet &cset, const int nvp, rcPolyMesh &mesh)
	Builds a polygon mesh from the provided contours. More...

bool	rcMergePolyMeshes (rcContext ctx, rcPolyMesh *meshes, const int nmeshes, rcPolyMesh &mesh)
	Merges multiple polygon meshes into a single mesh. More...

bool	rcBuildPolyMeshDetail (rcContext *ctx, const rcPolyMesh &mesh, const rcCompactHeightfield &chf, float sampleDist, float sampleMaxError, rcPolyMeshDetail &dmesh)
	Builds a detail mesh from the provided polygon mesh. More...

bool	rcCopyPolyMesh (rcContext *ctx, const rcPolyMesh &src, rcPolyMesh &dst)
	Copies the poly mesh data from src to dst. More...

bool	rcMergePolyMeshDetails (rcContext ctx, rcPolyMeshDetail *meshes, const int nmeshes, rcPolyMeshDetail &mesh)
	Merges multiple detail meshes into a single detail mesh. More...

Description

Members in this module are used to create mesh data that is then used to create Detour navigation meshes.

The are a large number of possible ways to building navigation mesh data. One of the simple piplines is as follows:

Prepare the input triangle mesh.
Build a rcHeightfield.
Build a rcCompactHeightfield.
Build a rcContourSet.
Build a rcPolyMesh.
Build a rcPolyMeshDetail.
Use the rcPolyMesh and rcPolyMeshDetail to build a Detour navigation mesh tile.

The general life-cycle of the main classes is as follows:

Allocate the object using the Recast allocator. (E.g. rcAllocHeightfield)
Initialize or build the object. (E.g. rcCreateHeightfield)
Update the object as needed. (E.g. rcRasterizeTriangles)
Use the object as part of the pipeline.
Free the object using the Recast allocator. (E.g. rcFreeHeightField)

Function Documentation

◆ rcAddSpan()

bool rcAddSpan	(	rcContext *	context,
		rcHeightfield &	heightfield,
		int	x,
		int	z,
		unsigned short	spanMin,
		unsigned short	spanMax,
		unsigned char	areaID,
		int	flagMergeThreshold
	)

Adds a span to the specified heightfield.

The span addition can be set to favor flags. If the span is merged to another span and the new spanMax is within flagMergeThreshold units from the existing span, the span flags are merged.

Parameters

[in,out]	context	The build context to use during the operation.
[in,out]	heightfield	An initialized heightfield.
[in]	x	The column x index where the span is to be added. [Limits: 0 <= value < rcHeightfield::width]
[in]	z	The column z index where the span is to be added. [Limits: 0 <= value < rcHeightfield::height]
[in]	spanMin	The minimum height of the span. [Limit: < `spanMax`] [Units: vx]
[in]	spanMax	The maximum height of the span. [Limit: <= RC_SPAN_MAX_HEIGHT] [Units: vx]
[in]	areaID	The area id of the span. [Limit: <= RC_WALKABLE_AREA)
[in]	flagMergeThreshold	The merge threshold. [Limit: >= 0] [Units: vx]

Returns: True if the operation completed successfully.

◆ rcAllocCompactHeightfield()

rcCompactHeightfield* rcAllocCompactHeightfield ( )

Allocates a compact heightfield object using the Recast allocator.

Returns: A compact heightfield that is ready for initialization, or null on failure.

See also: rcBuildCompactHeightfield, rcFreeCompactHeightfield

◆ rcAllocContourSet()

rcContourSet* rcAllocContourSet ( )

Allocates a contour set object using the Recast allocator.

Returns: A contour set that is ready for initialization, or null on failure.

See also: rcBuildContours, rcFreeContourSet

◆ rcAllocHeightfield()

rcHeightfield* rcAllocHeightfield ( )

Allocates a heightfield object using the Recast allocator.

Returns: A heightfield that is ready for initialization, or null on failure.

See also: rcCreateHeightfield, rcFreeHeightField

◆ rcAllocHeightfieldLayerSet()

rcHeightfieldLayerSet* rcAllocHeightfieldLayerSet ( )

Allocates a heightfield layer set using the Recast allocator.

Returns: A heightfield layer set that is ready for initialization, or null on failure.

See also: rcBuildHeightfieldLayers, rcFreeHeightfieldLayerSet

◆ rcAllocPolyMesh()

rcPolyMesh* rcAllocPolyMesh ( )

Allocates a polygon mesh object using the Recast allocator.

Returns: A polygon mesh that is ready for initialization, or null on failure.

See also: rcBuildPolyMesh, rcFreePolyMesh

◆ rcAllocPolyMeshDetail()

rcPolyMeshDetail* rcAllocPolyMeshDetail ( )

Allocates a detail mesh object using the Recast allocator.

Returns: A detail mesh that is ready for initialization, or null on failure.

See also: rcBuildPolyMeshDetail, rcFreePolyMeshDetail

◆ rcBuildCompactHeightfield()

bool rcBuildCompactHeightfield	(	rcContext *	context,
		int	walkableHeight,
		int	walkableClimb,
		const rcHeightfield &	heightfield,
		rcCompactHeightfield &	compactHeightfield
	)

Builds a compact heightfield representing open space, from a heightfield representing solid space.

This is just the beginning of the process of fully building a compact heightfield. Various filters may be applied, then the distance field and regions built. E.g: rcBuildDistanceField and rcBuildRegions

See the rcConfig documentation for more information on the configuration parameters.

See also: rcAllocCompactHeightfield, rcHeightfield, rcCompactHeightfield, rcConfig

Parameters

[in,out]	context	The build context to use during the operation.
[in]	walkableHeight	Minimum floor to 'ceiling' height that will still allow the floor area to be considered walkable. [Limit: >= 3] [Units: vx]
[in]	walkableClimb	Maximum ledge height that is considered to still be traversable. [Limit: >=0] [Units: vx]
[in]	heightfield	The heightfield to be compacted.
[out]	compactHeightfield	The resulting compact heightfield. (Must be pre-allocated.)

Returns: True if the operation completed successfully.

◆ rcBuildContours()

bool rcBuildContours	(	rcContext *	ctx,
		const rcCompactHeightfield &	chf,
		const float	maxError,
		const int	maxEdgeLen,
		rcContourSet &	cset,
		const int	buildFlags
	)

Builds a contour set from the region outlines in the provided compact heightfield.

Parameters

[in,out]	ctx	The build context to use during the operation.
[in]	chf	A fully built compact heightfield.
[in]	maxError	The maximum distance a simplified contour's border edges should deviate the original raw contour. [Limit: >=0] [Units: wu]
[in]	maxEdgeLen	The maximum allowed length for contour edges along the border of the mesh. [Limit: >=0] [Units: vx]
[out]	cset	The resulting contour set. (Must be pre-allocated.)
[in]	buildFlags	The build flags. (See: rcBuildContoursFlags)

Returns: True if the operation completed successfully.

The raw contours will match the region outlines exactly. The maxError and maxEdgeLen parameters control how closely the simplified contours will match the raw contours.

Simplified contours are generated such that the vertices for portals between areas match up. (They are considered mandatory vertices.)

Setting maxEdgeLength to zero will disabled the edge length feature.

See the rcConfig documentation for more information on the configuration parameters.

See also: rcAllocContourSet, rcCompactHeightfield, rcContourSet, rcConfig

◆ rcBuildDistanceField()

bool rcBuildDistanceField	(	rcContext *	ctx,
		rcCompactHeightfield &	chf
	)

Builds the distance field for the specified compact heightfield.

Parameters

[in,out]	ctx	The build context to use during the operation.
[in,out]	chf	A populated compact heightfield.

Returns: True if the operation completed successfully.

This is usually the second to the last step in creating a fully built compact heightfield. This step is required before regions are built using rcBuildRegions or rcBuildRegionsMonotone.

After this step, the distance data is available via the rcCompactHeightfield::maxDistance and rcCompactHeightfield::dist fields.

See also: rcCompactHeightfield, rcBuildRegions, rcBuildRegionsMonotone

◆ rcBuildHeightfieldLayers()

bool rcBuildHeightfieldLayers	(	rcContext *	ctx,
		const rcCompactHeightfield &	chf,
		const int	borderSize,
		const int	walkableHeight,
		rcHeightfieldLayerSet &	lset
	)

Builds a layer set from the specified compact heightfield.

Parameters

[in,out]	ctx	The build context to use during the operation.
[in]	chf	A fully built compact heightfield.
[in]	borderSize	The size of the non-navigable border around the heightfield. [Limit: >=0] [Units: vx]
[in]	walkableHeight	Minimum floor to 'ceiling' height that will still allow the floor area to be considered walkable. [Limit: >= 3] [Units: vx]
[out]	lset	The resulting layer set. (Must be pre-allocated.)

Returns: True if the operation completed successfully.

See the rcConfig documentation for more information on the configuration parameters.

See also: rcAllocHeightfieldLayerSet, rcCompactHeightfield, rcHeightfieldLayerSet, rcConfig

◆ rcBuildLayerRegions()

bool rcBuildLayerRegions	(	rcContext *	ctx,
		rcCompactHeightfield &	chf,
		int	borderSize,
		int	minRegionArea
	)

Builds region data for the heightfield by partitioning the heightfield in non-overlapping layers.

Parameters

[in,out]	ctx	The build context to use during the operation.
[in,out]	chf	A populated compact heightfield.
[in]	borderSize	The size of the non-navigable border around the heightfield. [Limit: >=0] [Units: vx]
[in]	minRegionArea	The minimum number of cells allowed to form isolated island areas. [Limit: >=0] [Units: vx].

Returns: True if the operation completed successfully.

◆ rcBuildPolyMesh()

bool rcBuildPolyMesh	(	rcContext *	ctx,
		const rcContourSet &	cset,
		const int	nvp,
		rcPolyMesh &	mesh
	)

Builds a polygon mesh from the provided contours.

Parameters

[in,out]	ctx	The build context to use during the operation.
[in]	cset	A fully built contour set.
[in]	nvp	The maximum number of vertices allowed for polygons generated during the contour to polygon conversion process. [Limit: >= 3]
[out]	mesh	The resulting polygon mesh. (Must be re-allocated.)

Returns: True if the operation completed successfully.

Note: If the mesh data is to be used to construct a Detour navigation mesh, then the upper limit must be restricted to <= DT_VERTS_PER_POLYGON.

See also: rcAllocPolyMesh, rcContourSet, rcPolyMesh, rcConfig

◆ rcBuildPolyMeshDetail()

bool rcBuildPolyMeshDetail	(	rcContext *	ctx,
		const rcPolyMesh &	mesh,
		const rcCompactHeightfield &	chf,
		const float	sampleDist,
		const float	sampleMaxError,
		rcPolyMeshDetail &	dmesh
	)

Builds a detail mesh from the provided polygon mesh.

Parameters

[in,out]	ctx	The build context to use during the operation.
[in]	mesh	A fully built polygon mesh.
[in]	chf	The compact heightfield used to build the polygon mesh.
[in]	sampleDist	Sets the distance to use when sampling the heightfield. [Limit: >=0] [Units: wu]
[in]	sampleMaxError	The maximum distance the detail mesh surface should deviate from heightfield data. [Limit: >=0] [Units: wu]
[out]	dmesh	The resulting detail mesh. (Must be pre-allocated.)

Returns: True if the operation completed successfully.

See the rcConfig documentation for more information on the configuration parameters.

See also: rcAllocPolyMeshDetail, rcPolyMesh, rcCompactHeightfield, rcPolyMeshDetail, rcConfig

◆ rcBuildRegions()

bool rcBuildRegions	(	rcContext *	ctx,
		rcCompactHeightfield &	chf,
		const int	borderSize,
		const int	minRegionArea,
		const int	mergeRegionArea
	)

Builds region data for the heightfield using watershed partitioning.

Parameters

[in,out]	ctx	The build context to use during the operation.
[in,out]	chf	A populated compact heightfield.
[in]	borderSize	The size of the non-navigable border around the heightfield. [Limit: >=0] [Units: vx]
[in]	minRegionArea	The minimum number of cells allowed to form isolated island areas. [Limit: >=0] [Units: vx].
[in]	mergeRegionArea	Any regions with a span count smaller than this value will, if possible, be merged with larger regions. [Limit: >=0] [Units: vx]

Returns: True if the operation completed successfully.

Non-null regions will consist of connected, non-overlapping walkable spans that form a single contour. Contours will form simple polygons.

If multiple regions form an area that is smaller than minRegionArea, then all spans will be re-assigned to the zero (null) region.

Watershed partitioning can result in smaller than necessary regions, especially in diagonal corridors. mergeRegionArea helps reduce unnecessarily small regions.

See the rcConfig documentation for more information on the configuration parameters.

The region data will be available via the rcCompactHeightfield::maxRegions and rcCompactSpan::reg fields.

Warning: The distance field must be created using rcBuildDistanceField before attempting to build regions.

See also: rcCompactHeightfield, rcCompactSpan, rcBuildDistanceField, rcBuildRegionsMonotone, rcConfig

◆ rcBuildRegionsMonotone()

bool rcBuildRegionsMonotone	(	rcContext *	ctx,
		rcCompactHeightfield &	chf,
		const int	borderSize,
		const int	minRegionArea,
		const int	mergeRegionArea
	)

Builds region data for the heightfield using simple monotone partitioning.

Parameters

[in,out]	ctx	The build context to use during the operation.
[in,out]	chf	A populated compact heightfield.
[in]	borderSize	The size of the non-navigable border around the heightfield. [Limit: >=0] [Units: vx]
[in]	minRegionArea	The minimum number of cells allowed to form isolated island areas. [Limit: >=0] [Units: vx].
[in]	mergeRegionArea	Any regions with a span count smaller than this value will, if possible, be merged with larger regions. [Limit: >=0] [Units: vx]

Returns: True if the operation completed successfully.

Non-null regions will consist of connected, non-overlapping walkable spans that form a single contour. Contours will form simple polygons.

If multiple regions form an area that is smaller than minRegionArea, then all spans will be re-assigned to the zero (null) region.

Partitioning can result in smaller than necessary regions. mergeRegionArea helps reduce unnecessarily small regions.

See the rcConfig documentation for more information on the configuration parameters.

The region data will be available via the rcCompactHeightfield::maxRegions and rcCompactSpan::reg fields.

Warning: The distance field must be created using rcBuildDistanceField before attempting to build regions.

See also: rcCompactHeightfield, rcCompactSpan, rcBuildDistanceField, rcBuildRegionsMonotone, rcConfig

◆ rcCalcBounds()

void rcCalcBounds	(	const float *	verts,
		int	numVerts,
		float *	minBounds,
		float *	maxBounds
	)

Calculates the bounding box of an array of vertices.

Parameters

[in]	verts	An array of vertices. [(x, y, z) * `nv`]
[in]	numVerts	The number of vertices in the `verts` array.
[out]	minBounds	The minimum bounds of the AABB. [(x, y, z)] [Units: wu]
[out]	maxBounds	The maximum bounds of the AABB. [(x, y, z)] [Units: wu]

◆ rcCalcGridSize()

void rcCalcGridSize	(	const float *	minBounds,
		const float *	maxBounds,
		float	cellSize,
		int *	sizeX,
		int *	sizeZ
	)

Calculates the grid size based on the bounding box and grid cell size.

Parameters

[in]	minBounds	The minimum bounds of the AABB. [(x, y, z)] [Units: wu]
[in]	maxBounds	The maximum bounds of the AABB. [(x, y, z)] [Units: wu]
[in]	cellSize	The xz-plane cell size. [Limit: > 0] [Units: wu]
[out]	sizeX	The width along the x-axis. [Limit: >= 0] [Units: vx]
[out]	sizeZ	The height along the z-axis. [Limit: >= 0] [Units: vx]

◆ rcClearUnwalkableTriangles()

void rcClearUnwalkableTriangles	(	rcContext *	context,
		float	walkableSlopeAngle,
		const float *	verts,
		int	numVerts,
		const int *	tris,
		int	numTris,
		unsigned char *	triAreaIDs
	)

Sets the area id of all triangles with a slope greater than or equal to the specified value to RC_NULL_AREA.

Only sets the area id's for the un-walkable triangles. Does not alter the area id's for walkable triangles.

See the rcConfig documentation for more information on the configuration parameters.

See also: rcHeightfield, rcClearUnwalkableTriangles, rcRasterizeTriangles

Parameters

[in,out]	context	The build context to use during the operation.
[in]	walkableSlopeAngle	The maximum slope that is considered walkable. [Limits: 0 <= value < 90] [Units: Degrees]
[in]	verts	The vertices. [(x, y, z) * `nv`]
[in]	numVerts	The number of vertices.
[in]	tris	The triangle vertex indices. [(vertA, vertB, vertC) * `nt`]
[in]	numTris	The number of triangles.
[out]	triAreaIDs	The triangle area ids. [Length: >= `nt`]

◆ rcCopyPolyMesh()

bool rcCopyPolyMesh	(	rcContext *	ctx,
		const rcPolyMesh &	src,
		rcPolyMesh &	dst
	)

Copies the poly mesh data from src to dst.

Parameters

[in,out]	ctx	The build context to use during the operation.
[in]	src	The source mesh to copy from.
[out]	dst	The resulting detail mesh. (Must be pre-allocated, must be empty mesh.)

Returns: True if the operation completed successfully.

◆ rcCreateHeightfield()

bool rcCreateHeightfield	(	rcContext *	context,
		rcHeightfield &	heightfield,
		int	sizeX,
		int	sizeZ,
		const float *	minBounds,
		const float *	maxBounds,
		float	cellSize,
		float	cellHeight
	)

Initializes a new heightfield.

See the rcConfig documentation for more information on the configuration parameters.

See also: rcAllocHeightfield, rcHeightfield

Parameters

[in,out]	context	The build context to use during the operation.
[in,out]	heightfield	The allocated heightfield to initialize.
[in]	sizeX	The width of the field along the x-axis. [Limit: >= 0] [Units: vx]
[in]	sizeZ	The height of the field along the z-axis. [Limit: >= 0] [Units: vx]
[in]	minBounds	The minimum bounds of the field's AABB. [(x, y, z)] [Units: wu]
[in]	maxBounds	The maximum bounds of the field's AABB. [(x, y, z)] [Units: wu]
[in]	cellSize	The xz-plane cell size to use for the field. [Limit: > 0] [Units: wu]
[in]	cellHeight	The y-axis cell size to use for field. [Limit: > 0] [Units: wu]

Returns: True if the operation completed successfully.

◆ rcErodeWalkableArea()

bool rcErodeWalkableArea	(	rcContext *	context,
		int	erosionRadius,
		rcCompactHeightfield &	compactHeightfield
	)

Erodes the walkable area within the heightfield by the specified radius.

Basically, any spans that are closer to a boundary or obstruction than the specified radius are marked as un-walkable.

This method is usually called immediately after the heightfield has been built.

See also: rcCompactHeightfield, rcBuildCompactHeightfield, rcConfig::walkableRadius

Parameters

[in,out]	context	The build context to use during the operation.
[in]	erosionRadius	The radius of erosion. [Limits: 0 < value < 255] [Units: vx]
[in,out]	compactHeightfield	The populated compact heightfield to erode.

Returns: True if the operation completed successfully.

◆ rcFilterLedgeSpans()

void rcFilterLedgeSpans	(	rcContext *	context,
		int	walkableHeight,
		int	walkableClimb,
		rcHeightfield &	heightfield
	)

Marks spans that are ledges as not-walkable.

A ledge is a span with one or more neighbors whose maximum is further away than walkableClimb from the current span's maximum. This method removes the impact of the overestimation of conservative voxelization so the resulting mesh will not have regions hanging in the air over ledges.

A span is a ledge if: rcAbs(currentSpan.smax - neighborSpan.smax) > walkableClimb

See also: rcHeightfield, rcConfig

Parameters

[in,out]	context	The build context to use during the operation.
[in]	walkableHeight	Minimum floor to 'ceiling' height that will still allow the floor area to be considered walkable. [Limit: >= 3] [Units: vx]
[in]	walkableClimb	Maximum ledge height that is considered to still be traversable. [Limit: >=0] [Units: vx]
[in,out]	heightfield	A fully built heightfield. (All spans have been added.)

◆ rcFilterLowHangingWalkableObstacles()

void rcFilterLowHangingWalkableObstacles	(	rcContext *	context,
		int	walkableClimb,
		rcHeightfield &	heightfield
	)

Marks non-walkable spans as walkable if their maximum is within walkableClimb of the span below them.

This removes small obstacles and rasterization artifacts that the agent would be able to walk over such as curbs. It also allows agents to move up terraced structures like stairs.

Obstacle spans are marked walkable if: obstacleSpan.smax - walkableSpan.smax < walkableClimb

Warning: Will override the effect of rcFilterLedgeSpans. If both filters are used, call rcFilterLedgeSpans only after applying this filter.

See also: rcHeightfield, rcConfig

Parameters

[in,out]	context	The build context to use during the operation.
[in]	walkableClimb	Maximum ledge height that is considered to still be traversable. [Limit: >=0] [Units: vx]
[in,out]	heightfield	A fully built heightfield. (All spans have been added.)

◆ rcFilterWalkableLowHeightSpans()

void rcFilterWalkableLowHeightSpans	(	rcContext *	context,
		int	walkableHeight,
		rcHeightfield &	heightfield
	)

Marks walkable spans as not walkable if the clearance above the span is less than the specified walkableHeight.

For this filter, the clearance above the span is the distance from the span's maximum to the minimum of the next higher span in the same column. If there is no higher span in the column, the clearance is computed as the distance from the top of the span to the maximum heightfield height.

See also: rcHeightfield, rcConfig

Parameters

[in,out]	context	The build context to use during the operation.
[in]	walkableHeight	Minimum floor to 'ceiling' height that will still allow the floor area to be considered walkable. [Limit: >= 3] [Units: vx]
[in,out]	heightfield	A fully built heightfield. (All spans have been added.)

◆ rcFreeCompactHeightfield()

void rcFreeCompactHeightfield ( rcCompactHeightfield * compactHeightfield )

Frees the specified compact heightfield object using the Recast allocator.

Parameters

[in] compactHeightfield A compact heightfield allocated using rcAllocCompactHeightfield

See also: rcAllocCompactHeightfield

◆ rcFreeContourSet()

void rcFreeContourSet ( rcContourSet * contourSet )

Frees the specified contour set using the Recast allocator.

Parameters

[in] contourSet A contour set allocated using rcAllocContourSet

See also: rcAllocContourSet

◆ rcFreeHeightField()

void rcFreeHeightField ( rcHeightfield * heightfield )

Frees the specified heightfield object using the Recast allocator.

Parameters

[in] heightfield A heightfield allocated using rcAllocHeightfield

See also: rcAllocHeightfield

◆ rcFreeHeightfieldLayerSet()

void rcFreeHeightfieldLayerSet ( rcHeightfieldLayerSet * layerSet )

Frees the specified heightfield layer set using the Recast allocator.

Parameters

[in] layerSet A heightfield layer set allocated using rcAllocHeightfieldLayerSet

See also: rcAllocHeightfieldLayerSet

◆ rcFreePolyMesh()

void rcFreePolyMesh ( rcPolyMesh * polyMesh )

Frees the specified polygon mesh using the Recast allocator.

Parameters

[in] polyMesh A polygon mesh allocated using rcAllocPolyMesh

See also: rcAllocPolyMesh

◆ rcFreePolyMeshDetail()

void rcFreePolyMeshDetail ( rcPolyMeshDetail * detailMesh )

Frees the specified detail mesh using the Recast allocator.

Parameters

[in] detailMesh A detail mesh allocated using rcAllocPolyMeshDetail

See also: rcAllocPolyMeshDetail

◆ rcGetCon()

int rcGetCon	(	const rcCompactSpan &	span,
		int	direction
	)

inline

Gets neighbor connection data for the specified direction.

Parameters

[in]	span	The span to check.
[in]	direction	The direction to check. [Limits: 0 <= value < 4]

Returns: The neighbor connection data for the specified direction, or RC_NOT_CONNECTED if there is no connection.

Can be used to locate neighbor spans in a compact heightfield. See the rcCompactHeightfield documentation for details on its use.

See also: rcCompactHeightfield, rcCompactSpan

◆ rcGetDirForOffset()

int rcGetDirForOffset	(	int	offsetX,
		int	offsetZ
	)

inline

Gets the direction for the specified offset.

One of x and y should be 0.

Parameters

[in]	offsetX	The x offset. [Limits: -1 <= value <= 1]
[in]	offsetZ	The z offset. [Limits: -1 <= value <= 1]

Returns: The direction that represents the offset.

◆ rcGetDirOffsetX()

int rcGetDirOffsetX ( int direction )

inline

Gets the standard width (x-axis) offset for the specified direction.

Parameters

[in] direction The direction. [Limits: 0 <= value < 4]

Returns: The width offset to apply to the current cell position to move in the direction.

The value of dir will be automatically wrapped. So a value of 6 will be interpreted as 2.

See the rcCompactHeightfield documentation for usage details.

◆ rcGetDirOffsetY()

int rcGetDirOffsetY ( int direction )

inline

Gets the standard height (z-axis) offset for the specified direction.

Parameters

[in] direction The direction. [Limits: 0 <= value < 4]

Returns: The height offset to apply to the current cell position to move in the direction.

The value of dir will be automatically wrapped. So a value of 6 will be interpreted as 2.

See the rcCompactHeightfield documentation for usage details.

◆ rcGetHeightFieldSpanCount()

int rcGetHeightFieldSpanCount	(	rcContext *	context,
		const rcHeightfield &	heightfield
	)

Returns the number of spans contained in the specified heightfield.

Parameters

[in,out]	context	The build context to use during the operation.
[in]	heightfield	An initialized heightfield.

Returns: The number of spans in the heightfield.

◆ rcMarkBoxArea()

void rcMarkBoxArea	(	rcContext *	context,
		const float *	boxMinBounds,
		const float *	boxMaxBounds,
		unsigned char	areaId,
		rcCompactHeightfield &	compactHeightfield
	)

Applies an area id to all spans within the specified bounding box.

(AABB)

See also: rcCompactHeightfield, rcMedianFilterWalkableArea

Parameters

[in,out]	context	The build context to use during the operation.
[in]	boxMinBounds	The minimum extents of the bounding box. [(x, y, z)] [Units: wu]
[in]	boxMaxBounds	The maximum extents of the bounding box. [(x, y, z)] [Units: wu]
[in]	areaId	The area id to apply. [Limit: <= RC_WALKABLE_AREA]
[in,out]	compactHeightfield	A populated compact heightfield.

◆ rcMarkConvexPolyArea()

void rcMarkConvexPolyArea	(	rcContext *	context,
		const float *	verts,
		int	numVerts,
		float	minY,
		float	maxY,
		unsigned char	areaId,
		rcCompactHeightfield &	compactHeightfield
	)

Applies the area id to the all spans within the specified convex polygon.

The value of spacial parameters are in world units.

The y-values of the polygon vertices are ignored. So the polygon is effectively projected onto the xz-plane, translated to minY, and extruded to maxY.

See also: rcCompactHeightfield, rcMedianFilterWalkableArea

Parameters

[in,out]	context	The build context to use during the operation.
[in]	verts	The vertices of the polygon [For: (x, y, z) * `numVerts`]
[in]	numVerts	The number of vertices in the polygon.
[in]	minY	The height of the base of the polygon. [Units: wu]
[in]	maxY	The height of the top of the polygon. [Units: wu]
[in]	areaId	The area id to apply. [Limit: <= RC_WALKABLE_AREA]
[in,out]	compactHeightfield	A populated compact heightfield.

◆ rcMarkCylinderArea()

void rcMarkCylinderArea	(	rcContext *	context,
		const float *	position,
		float	radius,
		float	height,
		unsigned char	areaId,
		rcCompactHeightfield &	compactHeightfield
	)

Applies the area id to all spans within the specified y-axis-aligned cylinder.

See also: rcCompactHeightfield, rcMedianFilterWalkableArea

Parameters

[in,out]	context	The build context to use during the operation.
[in]	position	The center of the base of the cylinder. [Form: (x, y, z)] [Units: wu]
[in]	radius	The radius of the cylinder. [Units: wu] [Limit: > 0]
[in]	height	The height of the cylinder. [Units: wu] [Limit: > 0]
[in]	areaId	The area id to apply. [Limit: <= RC_WALKABLE_AREA]
[in,out]	compactHeightfield	A populated compact heightfield.

◆ rcMarkWalkableTriangles()

void rcMarkWalkableTriangles	(	rcContext *	context,
		float	walkableSlopeAngle,
		const float *	verts,
		int	numVerts,
		const int *	tris,
		int	numTris,
		unsigned char *	triAreaIDs
	)

Sets the area id of all triangles with a slope below the specified value to RC_WALKABLE_AREA.

Only sets the area id's for the walkable triangles. Does not alter the area id's for un-walkable triangles.

See the rcConfig documentation for more information on the configuration parameters.

See also: rcHeightfield, rcClearUnwalkableTriangles, rcRasterizeTriangles

Parameters

[in,out]	context	The build context to use during the operation.
[in]	walkableSlopeAngle	The maximum slope that is considered walkable. [Limits: 0 <= value < 90] [Units: Degrees]
[in]	verts	The vertices. [(x, y, z) * `nv`]
[in]	numVerts	The number of vertices.
[in]	tris	The triangle vertex indices. [(vertA, vertB, vertC) * `nt`]
[in]	numTris	The number of triangles.
[out]	triAreaIDs	The triangle area ids. [Length: >= `nt`]

◆ rcMedianFilterWalkableArea()

bool rcMedianFilterWalkableArea	(	rcContext *	context,
		rcCompactHeightfield &	compactHeightfield
	)

Applies a median filter to walkable area types (based on area id), removing noise.

This filter is usually applied after applying area id's using functions such as rcMarkBoxArea, rcMarkConvexPolyArea, and rcMarkCylinderArea.

See also: rcCompactHeightfield

Parameters

[in,out]	context	The build context to use during the operation.
[in,out]	compactHeightfield	A populated compact heightfield.

Returns: True if the operation completed successfully.

◆ rcMergePolyMeshDetails()

bool rcMergePolyMeshDetails	(	rcContext *	ctx,
		rcPolyMeshDetail **	meshes,
		const int	nmeshes,
		rcPolyMeshDetail &	mesh
	)

Merges multiple detail meshes into a single detail mesh.

Parameters

[in,out]	ctx	The build context to use during the operation.
[in]	meshes	An array of detail meshes to merge. [Size: `nmeshes`]
[in]	nmeshes	The number of detail meshes in the meshes array.
[out]	mesh	The resulting detail mesh. (Must be pre-allocated.)

Returns: True if the operation completed successfully.

See also: rcAllocPolyMeshDetail, rcPolyMeshDetail

◆ rcMergePolyMeshes()

bool rcMergePolyMeshes	(	rcContext *	ctx,
		rcPolyMesh **	meshes,
		const int	nmeshes,
		rcPolyMesh &	mesh
	)

Merges multiple polygon meshes into a single mesh.

Parameters

[in,out]	ctx	The build context to use during the operation.
[in]	meshes	An array of polygon meshes to merge. [Size: `nmeshes`]
[in]	nmeshes	The number of polygon meshes in the meshes array.
[in]	mesh	The resulting polygon mesh. (Must be pre-allocated.)

Returns: True if the operation completed successfully.

See also: rcAllocPolyMesh, rcPolyMesh

◆ rcOffsetPoly()

int rcOffsetPoly	(	const float *	verts,
		int	numVerts,
		float	offset,
		float *	outVerts,
		int	maxOutVerts
	)

Expands a convex polygon along its vertex normals by the given offset amount.

Inserts extra vertices to bevel sharp corners.

Helper function to offset convex polygons for rcMarkConvexPolyArea.

Parameters

[in]	verts	The vertices of the polygon [Form: (x, y, z) * `numVerts`]
[in]	numVerts	The number of vertices in the polygon.
[in]	offset	How much to offset the polygon by. [Units: wu]
[out]	outVerts	The offset vertices (should hold up to 2 * `numVerts`) [Form: (x, y, z) * return value]
[in]	maxOutVerts	The max number of vertices that can be stored to `outVerts`.

Returns: Number of vertices in the offset polygon or 0 if too few vertices in outVerts.

◆ rcRasterizeTriangle()

bool rcRasterizeTriangle	(	rcContext *	context,
		const float *	v0,
		const float *	v1,
		const float *	v2,
		unsigned char	areaID,
		rcHeightfield &	heightfield,
		int	flagMergeThreshold = `1`
	)

Rasterizes a single triangle into the specified heightfield.

Calling this for each triangle in a mesh is less efficient than calling rcRasterizeTriangles

No spans will be added if the triangle does not overlap the heightfield grid.

See also: rcHeightfield

Parameters

[in,out]	context	The build context to use during the operation.
[in]	v0	Triangle vertex 0 [(x, y, z)]
[in]	v1	Triangle vertex 1 [(x, y, z)]
[in]	v2	Triangle vertex 2 [(x, y, z)]
[in]	areaID	The area id of the triangle. [Limit: <= RC_WALKABLE_AREA]
[in,out]	heightfield	An initialized heightfield.
[in]	flagMergeThreshold	The distance where the walkable flag is favored over the non-walkable flag. [Limit: >= 0] [Units: vx]

Returns: True if the operation completed successfully.

◆ rcRasterizeTriangles() [1/3]

bool rcRasterizeTriangles	(	rcContext *	context,
		const float *	verts,
		const unsigned char *	triAreaIDs,
		int	numTris,
		rcHeightfield &	heightfield,
		int	flagMergeThreshold = `1`
	)

Rasterizes a triangle list into the specified heightfield.

Expects each triangle to be specified as three sequential vertices of 3 floats.

Spans will only be added for triangles that overlap the heightfield grid.

See also: rcHeightfield

Parameters

[in,out]	context	The build context to use during the operation.
[in]	verts	The triangle vertices. [(ax, ay, az, bx, by, bz, cx, by, cx) * `nt`]
[in]	triAreaIDs	The area id's of the triangles. [Limit: <= RC_WALKABLE_AREA] [Size: `nt`]
[in]	numTris	The number of triangles.
[in,out]	heightfield	An initialized heightfield.
[in]	flagMergeThreshold	The distance where the walkable flag is favored over the non-walkable flag. [Limit: >= 0] [Units: vx]

Returns: True if the operation completed successfully.

◆ rcRasterizeTriangles() [2/3]

bool rcRasterizeTriangles	(	rcContext *	context,
		const float *	verts,
		int	numVerts,
		const int *	tris,
		const unsigned char *	triAreaIDs,
		int	numTris,
		rcHeightfield &	heightfield,
		int	flagMergeThreshold = `1`
	)

Rasterizes an indexed triangle mesh into the specified heightfield.

Spans will only be added for triangles that overlap the heightfield grid.

See also: rcHeightfield

Parameters

[in,out]	context	The build context to use during the operation.
[in]	verts	The vertices. [(x, y, z) * `nv`]
[in]	numVerts	The number of vertices. (unused) TODO (graham): Remove in next major release
[in]	tris	The triangle indices. [(vertA, vertB, vertC) * `nt`]
[in]	triAreaIDs	The area id's of the triangles. [Limit: <= RC_WALKABLE_AREA] [Size: `nt`]
[in]	numTris	The number of triangles.
[in,out]	heightfield	An initialized heightfield.
[in]	flagMergeThreshold	The distance where the walkable flag is favored over the non-walkable flag. [Limit: >= 0] [Units: vx]

Returns: True if the operation completed successfully.

◆ rcRasterizeTriangles() [3/3]

bool rcRasterizeTriangles	(	rcContext *	context,
		const float *	verts,
		int	numVerts,
		const unsigned short *	tris,
		const unsigned char *	triAreaIDs,
		int	numTris,
		rcHeightfield &	heightfield,
		int	flagMergeThreshold = `1`
	)

Rasterizes an indexed triangle mesh into the specified heightfield.

Spans will only be added for triangles that overlap the heightfield grid.

See also: rcHeightfield

Parameters

[in,out]	context	The build context to use during the operation.
[in]	verts	The vertices. [(x, y, z) * `nv`]
[in]	numVerts	The number of vertices. (unused) TODO (graham): Remove in next major release
[in]	tris	The triangle indices. [(vertA, vertB, vertC) * `nt`]
[in]	triAreaIDs	The area id's of the triangles. [Limit: <= RC_WALKABLE_AREA] [Size: `nt`]
[in]	numTris	The number of triangles.
[in,out]	heightfield	An initialized heightfield.
[in]	flagMergeThreshold	The distance where the walkable flag is favored over the non-walkable flag. [Limit: >= 0] [Units: vx]

Returns: True if the operation completed successfully.

◆ rcSetCon()

void rcSetCon	(	rcCompactSpan &	span,
		int	direction,
		int	neighborIndex
	)

inline

Sets the neighbor connection data for the specified direction.

Parameters

[in]	span	The span to update.
[in]	direction	The direction to set. [Limits: 0 <= value < 4]
[in]	neighborIndex	The index of the neighbor span.

This function is used by the build process. It is rarely of use to end users.

See also: rcCompactHeightfield, rcCompactSpan

Classes

Allocation Functions

Heightfield Functions

Compact Heightfield Functions

Layer, Contour, Polymesh, and Detail Mesh Functions

Description

Function Documentation

◆ rcAddSpan()

◆ rcAllocCompactHeightfield()

◆ rcAllocContourSet()

◆ rcAllocHeightfield()

◆ rcAllocHeightfieldLayerSet()

◆ rcAllocPolyMesh()

◆ rcAllocPolyMeshDetail()

◆ rcBuildCompactHeightfield()

◆ rcBuildContours()

◆ rcBuildDistanceField()

◆ rcBuildHeightfieldLayers()

◆ rcBuildLayerRegions()

◆ rcBuildPolyMesh()

◆ rcBuildPolyMeshDetail()

◆ rcBuildRegions()

◆ rcBuildRegionsMonotone()

◆ rcCalcBounds()

◆ rcCalcGridSize()

◆ rcClearUnwalkableTriangles()

◆ rcCopyPolyMesh()

◆ rcCreateHeightfield()

◆ rcErodeWalkableArea()

◆ rcFilterLedgeSpans()

◆ rcFilterLowHangingWalkableObstacles()

◆ rcFilterWalkableLowHeightSpans()

◆ rcFreeCompactHeightfield()

◆ rcFreeContourSet()

◆ rcFreeHeightField()

◆ rcFreeHeightfieldLayerSet()

◆ rcFreePolyMesh()

◆ rcFreePolyMeshDetail()

◆ rcGetCon()

◆ rcGetDirForOffset()

◆ rcGetDirOffsetX()

◆ rcGetDirOffsetY()

◆ rcGetHeightFieldSpanCount()

◆ rcMarkBoxArea()

◆ rcMarkConvexPolyArea()

◆ rcMarkCylinderArea()

◆ rcMarkWalkableTriangles()

◆ rcMedianFilterWalkableArea()

◆ rcMergePolyMeshDetails()

◆ rcMergePolyMeshes()

◆ rcOffsetPoly()

◆ rcRasterizeTriangle()

◆ rcRasterizeTriangles() [1/3]

◆ rcRasterizeTriangles() [2/3]

◆ rcRasterizeTriangles() [3/3]

◆ rcSetCon()