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

Functions
bool	rcErodeWalkableArea (rcContext *ctx, int radius, rcCompactHeightfield &chf)
	Erodes the walkable area within the heightfield by the specified radius. More...

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

void	rcMarkBoxArea (rcContext ctx, const float bmin, const float *bmax, navAreaMask areaId, rcCompactHeightfield &chf)
	Applies an area id to all spans within the specified bounding box. More...

void	rcMarkConvexPolyArea (rcContext ctx, const float verts, const int nverts, const float hmin, const float hmax, navAreaMask areaId, rcCompactHeightfield &chf)
	Applies the area id to the all spans within the specified convex polygon. More...

int	rcOffsetPoly (const float verts, const int nverts, const float offset, float outVerts, const int maxOutVerts)
	Helper function to offset voncex polygons for rcMarkConvexPolyArea. More...

void	rcMarkCylinderArea (rcContext ctx, const float pos, const float r, const float h, navAreaMask areaMask, rcCompactHeightfield &chf)
	Applies the area id to all spans within the specified cylinder. More...

bool	rcBuildHeightfieldLayers (rcContext *ctx, rcCompactHeightfield &chf, const int borderSize, const int walkableHeight, rcHeightfieldLayerSet &lset)
	Builds a layer set from the specified compact heightfield. More...

bool	rcBuildContours (rcContext *ctx, rcCompactHeightfield &chf, const float maxError, const int maxEdgeLen, rcContourSet &cset, const 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, 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, const float sampleDist, const 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...

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

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

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

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

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

void	rcSetCon (rcCompactSpan &s, int dir, int i)
	Sets the neighbor connection data for the specified direction. More...

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

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

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

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

void	rcCalcGridSize (const float bmin, const float bmax, float cs, int w, int h)
	Calculates the grid size based on the bounding box and grid cell size. More...

bool	rcCreateHeightfield (rcContext ctx, rcHeightfield &hf, int width, int height, const float bmin, const float *bmax, float cs, float ch)
	Initializes a new heightfield. More...

void	rcMarkWalkableTriangles (rcContext ctx, const float walkableSlopeAngle, const float verts, int nv, const int tris, int nt, navAreaMask areaMasks)
	Sets the area id of all triangles with a slope below the specified value to RC_WALKABLE_AREA. More...

void	rcClearUnwalkableTriangles (rcContext ctx, const float walkableSlopeAngle, const float verts, int nv, const int tris, int nt, navAreaMask areaMasks)
	Sets the area id of all triangles with a slope greater than or equal to the specified value to RC_NULL_AREA. More...

void	rcAddSpan (rcContext *ctx, rcHeightfield &hf, const int x, const int y, const unsigned short smin, const unsigned short smax, const navAreaMask areaMask, const int flagMergeThr)
	Adds a span to the specified heightfield. More...

void	rcRasterizeTriangle (rcContext ctx, const float v0, const float v1, const float v2, const navAreaMask areaMask, rcHeightfield &solid, const int flagMergeThr=1)
	Rasterizes a triangle into the specified heightfield. More...

void	rcRasterizeTriangles (rcContext ctx, const float verts, const int nv, const int tris, const navAreaMask areaMasks, const int nt, rcHeightfield &solid, const int flagMergeThr=1)
	Rasterizes an indexed triangle mesh into the specified heightfield. More...

void	rcRasterizeTriangles (rcContext ctx, const float verts, const int nv, const unsigned short tris, const navAreaMask areaMasks, const int nt, rcHeightfield &solid, const int flagMergeThr=1)
	Rasterizes an indexed triangle mesh into the specified heightfield. More...

void	rcRasterizeTriangles (rcContext ctx, const float verts, const navAreaMask *areaMasks, const int nt, rcHeightfield &solid, const int flagMergeThr=1)
	Rasterizes triangles into the specified heightfield. More...

void	rcFilterLowHangingWalkableObstacles (rcContext *ctx, const int walkableClimb, rcHeightfield &solid)
	Marks non-walkable spans as walkable if their maximum is within `walkableClimp` of a walkable neihbor. More...

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

void	rcFilterWalkableLowHeightSpans (rcContext *ctx, int walkableHeight, rcHeightfield &solid)
	Marks walkable spans as not walkable if the clearence above the span is less than the specified height. More...

int	rcGetHeightFieldSpanCount (rcContext *ctx, rcHeightfield &hf)
	Returns the number of spans contained in the specified heightfield. 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 *hf)
	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 *chf)
	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 *lset)
	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 *cset)
	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 *pmesh)
	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 *dmesh)
	Frees the specified detail mesh using the Recast allocator. 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)

Note: This is a summary list of members. Use the index or search feature to find minor members.

Function Documentation

void rcAddSpan	(	rcContext *	ctx,
		rcHeightfield &	hf,
		const int	x,
		const int	y,
		const unsigned short	smin,
		const unsigned short	smax,
		const navAreaMask	areaMask,
		const int	flagMergeThr
	)

Adds a span to the specified heightfield.

Parameters

[in,out]	ctx	The build context to use during the operation.
[in,out]	hf	An initialized heightfield.
[in]	x	The width index where the span is to be added. [Limits: 0 <= value < rcHeightfield::width]
[in]	y	The height index where the span is to be added. [Limits: 0 <= value < rcHeightfield::height]
[in]	smin	The minimum height of the span. [Limit: < `smax`] [Units: vx]
[in]	smax	The maximum height of the span. [Limit: <= rcSpan::RC_SPAN_MAX_HEIGHT] [Units: vx]
[in]	areaMask	The area of the span. [Limit: <= RC_WALKABLE_AREA)
[in]	flagMergeThr	The merge theshold. [Limit: >= 0] [Units: vx]

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

See also: rcHeightfield, rcSpan.

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

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

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

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

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

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

bool rcBuildCompactHeightfield	(	rcContext *	ctx,
		const int	walkableHeight,
		const int	walkableClimb,
		rcHeightfield &	hf,
		rcCompactHeightfield &	chf
	)

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

Parameters

[in,out]	ctx	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]	hf	The heightfield to be compacted.
[out]	chf	The resulting compact heightfield. (Must be pre-allocated.)

Returns: True if the operation completed successfully.

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

bool rcBuildContours	(	rcContext *	ctx,
		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 simplfied 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

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

bool rcBuildHeightfieldLayers	(	rcContext *	ctx,
		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

bool rcBuildLayerRegions	(	rcContext *	ctx,
		rcCompactHeightfield &	chf,
		const int	borderSize,
		const 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.

bool rcBuildPolyMesh	(	rcContext *	ctx,
		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 retricted to <= DT_VERTS_PER_POLYGON.

See also: rcAllocPolyMesh, rcContourSet, rcPolyMesh, rcConfig

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

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

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

void rcCalcBounds	(	const float *	verts,
		int	nv,
		float *	bmin,
		float *	bmax
	)

Calculates the bounding box of an array of vertices.

Parameters

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

void rcCalcGridSize	(	const float *	bmin,
		const float *	bmax,
		float	cs,
		int *	w,
		int *	h
	)

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

Parameters

[in]	bmin	The minimum bounds of the AABB. [(x, y, z)] [Units: wu]
[in]	bmax	The maximum bounds of the AABB. [(x, y, z)] [Units: wu]
[in]	cs	The xz-plane cell size. [Limit: > 0] [Units: wu]
[out]	w	The width along the x-axis. [Limit: >= 0] [Units: vx]
[out]	h	The height along the z-axis. [Limit: >= 0] [Units: vx]

void rcClearUnwalkableTriangles	(	rcContext *	ctx,
		const float	walkableSlopeAngle,
		const float *	verts,
		int	nv,
		const int *	tris,
		int	nt,
		navAreaMask *	areaMasks
	)

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

Parameters

[in,out]	ctx	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]	nv	The number of vertices.
[in]	tris	The triangle vertex indices. [(vertA, vertB, vertC) * `nt`]
[in]	nt	The number of triangles.
[out]	areaMasks	The triangle area masks. [Length: >= `nt`]

Only sets the area id's for the unwalkable 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

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.

bool rcCreateHeightfield	(	rcContext *	ctx,
		rcHeightfield &	hf,
		int	width,
		int	height,
		const float *	bmin,
		const float *	bmax,
		float	cs,
		float	ch
	)

Initializes a new heightfield.

Parameters

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

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

See also: rcAllocHeightfield, rcHeightfield

bool rcErodeWalkableArea	(	rcContext *	ctx,
		int	radius,
		rcCompactHeightfield &	chf
	)

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

Parameters

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

Returns: True if the operation completed successfully.

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

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

See also: rcCompactHeightfield, rcBuildCompactHeightfield, rcConfig::walkableRadius

void rcFilterLedgeSpans	(	rcContext *	ctx,
		const int	walkableHeight,
		const int	walkableClimb,
		rcHeightfield &	solid
	)

Marks spans that are ledges as not-walkable.

Parameters

[in,out]	ctx	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]	solid	A fully built heightfield. (All spans have been added.)

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

void rcFilterLowHangingWalkableObstacles	(	rcContext *	ctx,
		const int	walkableClimb,
		rcHeightfield &	solid
	)

Marks non-walkable spans as walkable if their maximum is within walkableClimp of a walkable neihbor.

Parameters

[in,out]	ctx	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]	solid	A fully built heightfield. (All spans have been added.)

Allows the formation of walkable regions that will flow over low lying objects such as curbs, and up structures such as stairways.

Two neighboring spans are walkable if: rcAbs(currentSpan.smax - neighborSpan.smax) < waklableClimb

Warning: Will override the effect of rcFilterLedgeSpans. So if both filters are used, call rcFilterLedgeSpans after calling this filter.

See also: rcHeightfield, rcConfig

void rcFilterWalkableLowHeightSpans	(	rcContext *	ctx,
		int	walkableHeight,
		rcHeightfield &	solid
	)

Marks walkable spans as not walkable if the clearence above the span is less than the specified height.

Parameters

[in,out]	ctx	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]	solid	A fully built heightfield. (All spans have been added.)

For this filter, the clearance above the span is the distance from the span's maximum to the next higher span's minimum. (Same grid column.)

See also: rcHeightfield, rcConfig

void rcFreeCompactHeightfield ( rcCompactHeightfield * chf )

Frees the specified compact heightfield object using the Recast allocator.

Parameters

[in] chf A compact heightfield allocated using rcAllocCompactHeightfield

See also: rcAllocCompactHeightfield

void rcFreeContourSet ( rcContourSet * cset )

Frees the specified contour set using the Recast allocator.

Parameters

[in] cset A contour set allocated using rcAllocContourSet

See also: rcAllocContourSet

void rcFreeHeightField ( rcHeightfield * hf )

Frees the specified heightfield object using the Recast allocator.

Parameters

[in] hf A heightfield allocated using rcAllocHeightfield

See also: rcAllocHeightfield

void rcFreeHeightfieldLayerSet ( rcHeightfieldLayerSet * lset )

Frees the specified heightfield layer set using the Recast allocator.

Parameters

[in] lset A heightfield layer set allocated using rcAllocHeightfieldLayerSet

See also: rcAllocHeightfieldLayerSet

void rcFreePolyMesh ( rcPolyMesh * pmesh )

Frees the specified polygon mesh using the Recast allocator.

Parameters

[in] pmesh A polygon mesh allocated using rcAllocPolyMesh

See also: rcAllocPolyMesh

void rcFreePolyMeshDetail ( rcPolyMeshDetail * dmesh )

Frees the specified detail mesh using the Recast allocator.

Parameters

[in] dmesh A detail mesh allocated using rcAllocPolyMeshDetail

See also: rcAllocPolyMeshDetail

int rcGetCon	(	const rcCompactSpan &	s,
		int	dir
	)

inline

Gets neighbor connection data for the specified direction.

Parameters

[in]	s	The span to check.
[in]	dir	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

int rcGetDirOffsetX ( int dir )

inline

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

Parameters

[in] dir 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.

int rcGetDirOffsetY ( int dir )

inline

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

Parameters

[in] dir 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.

int rcGetHeightFieldSpanCount	(	rcContext *	ctx,
		rcHeightfield &	hf
	)

Returns the number of spans contained in the specified heightfield.

Parameters

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

Returns: The number of spans in the heightfield.

void rcMarkBoxArea	(	rcContext *	ctx,
		const float *	bmin,
		const float *	bmax,
		navAreaMask	areaId,
		rcCompactHeightfield &	chf
	)

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

(AABB)

Parameters

[in,out]	ctx	The build context to use during the operation.
[in]	bmin	The minimum of the bounding box. [(x, y, z)]
[in]	bmax	The maximum of the bounding box. [(x, y, z)]
[in]	areaId	The area id to apply. [Limit: <= RC_WALKABLE_AREA]
[in,out]	chf	A populated compact heightfield.

The value of spacial parameters are in world units.

See also: rcCompactHeightfield, rcMedianFilterWalkableArea

void rcMarkConvexPolyArea	(	rcContext *	ctx,
		const float *	verts,
		const int	nverts,
		const float	hmin,
		const float	hmax,
		navAreaMask	areaId,
		rcCompactHeightfield &	chf
	)

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

Parameters

[in,out]	ctx	The build context to use during the operation.
[in]	verts	The vertices of the polygon [Fomr: (x, y, z) * `nverts`]
[in]	nverts	The number of vertices in the polygon.
[in]	hmin	The height of the base of the polygon.
[in]	hmax	The height of the top of the polygon.
[in]	areaId	The area id to apply. [Limit: <= RC_WALKABLE_AREA]
[in,out]	chf	A populated compact heightfield.

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 at hmin, then extruded to hmax.

See also: rcCompactHeightfield, rcMedianFilterWalkableArea

void rcMarkCylinderArea	(	rcContext *	ctx,
		const float *	pos,
		const float	r,
		const float	h,
		navAreaMask	areaMask,
		rcCompactHeightfield &	chf
	)

Applies the area id to all spans within the specified cylinder.

Parameters

[in,out]	ctx	The build context to use during the operation.
[in]	pos	The center of the base of the cylinder. [Form: (x, y, z)]
[in]	r	The radius of the cylinder.
[in]	h	The height of the cylinder.
[in]	areaMask	The area mask to apply. [Limit: <= RC_WALKABLE_AREA]
[in,out]	chf	A populated compact heightfield.

The value of spacial parameters are in world units.

See also: rcCompactHeightfield, rcMedianFilterWalkableArea

void rcMarkWalkableTriangles	(	rcContext *	ctx,
		const float	walkableSlopeAngle,
		const float *	verts,
		int	nv,
		const int *	tris,
		int	nt,
		navAreaMask *	areaMasks
	)

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

Parameters

[in,out]	ctx	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]	nv	The number of vertices.
[in]	tris	The triangle vertex indices. [(vertA, vertB, vertC) * `nt`]
[in]	nt	The number of triangles.
[out]	areaMasks	The triangle area ids. [Length: >= `nt`]

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

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

See also: rcHeightfield, rcClearUnwalkableTriangles, rcRasterizeTriangles

bool rcMedianFilterWalkableArea	(	rcContext *	ctx,
		rcCompactHeightfield &	chf
	)

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

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 filter is usually applied after applying area id's using functions such as rcMarkBoxArea, rcMarkConvexPolyArea, and rcMarkCylinderArea.

See also: rcCompactHeightfield

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

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

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

Helper function to offset voncex polygons for rcMarkConvexPolyArea.

Parameters

[in]	verts	The vertices of the polygon [Form: (x, y, z) * `nverts`]
[in]	nverts	The number of vertices in the polygon.
[in]	offset	The offset on the XY Plane.
[out]	outVerts	The offset vertices (should hold up to 2 * `nverts`) [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.

void rcRasterizeTriangle	(	rcContext *	ctx,
		const float *	v0,
		const float *	v1,
		const float *	v2,
		const navAreaMask	areaMask,
		rcHeightfield &	solid,
		const int	flagMergeThr
	)

Rasterizes a triangle into the specified heightfield.

Parameters

[in,out]	ctx	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]	areaMask	The area id of the triangle. [Limit: <= RC_WALKABLE_AREA]
[in,out]	solid	An initialized heightfield.
[in]	flagMergeThr	The distance where the walkable flag is favored over the non-walkable flag. [Limit: >= 0] [Units: vx]

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

See also: rcHeightfield

void rcRasterizeTriangles	(	rcContext *	ctx,
		const float *	verts,
		const int	nv,
		const int *	tris,
		const navAreaMask *	areaMasks,
		const int	nt,
		rcHeightfield &	solid,
		const int	flagMergeThr
	)

Rasterizes an indexed triangle mesh into the specified heightfield.

Parameters

[in,out]	ctx	The build context to use during the operation.
[in]	verts	The vertices. [(x, y, z) * `nv`]
[in]	nv	The number of vertices.
[in]	tris	The triangle indices. [(vertA, vertB, vertC) * `nt`]
[in]	areaMasks	The area masks of the triangles. [Limit: <= RC_WALKABLE_AREA] [Size: `nt`]
[in]	nt	The number of triangles.
[in,out]	solid	An initialized heightfield.
[in]	flagMergeThr	The distance where the walkable flag is favored over the non-walkable flag. [Limit: >= 0] [Units: vx]

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

See also: rcHeightfield

void rcRasterizeTriangles	(	rcContext *	ctx,
		const float *	verts,
		const int	nv,
		const unsigned short *	tris,
		const navAreaMask *	areaMasks,
		const int	nt,
		rcHeightfield &	solid,
		const int	flagMergeThr
	)

Rasterizes an indexed triangle mesh into the specified heightfield.

Parameters

[in,out]	ctx	The build context to use during the operation.
[in]	verts	The vertices. [(x, y, z) * `nv`]
[in]	nv	The number of vertices.
[in]	tris	The triangle indices. [(vertA, vertB, vertC) * `nt`]
[in]	areaMasks	The area masks of the triangles. [Limit: <= RC_WALKABLE_AREA] [Size: `nt`]
[in]	nt	The number of triangles.
[in,out]	solid	An initialized heightfield.
[in]	flagMergeThr	The distance where the walkable flag is favored over the non-walkable flag. [Limit: >= 0] [Units: vx]

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

See also: rcHeightfield

void rcRasterizeTriangles	(	rcContext *	ctx,
		const float *	verts,
		const navAreaMask *	areaMasks,
		const int	nt,
		rcHeightfield &	solid,
		const int	flagMergeThr
	)

Rasterizes triangles into the specified heightfield.

Parameters

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

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

See also: rcHeightfield

void rcSetCon	(	rcCompactSpan &	s,
		int	dir,
		int	i
	)

inline

Sets the neighbor connection data for the specified direction.

Parameters

[in]	s	The span to update.
[in]	dir	The direction to set. [Limits: 0 <= value < 4]
[in]	i	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

Functions

Compact Heightfield Functions

Heightfield Functions

Allocation Functions

Description

Function Documentation