Recast Navigation  (2016-05-09)
Classes
Recast

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
rcHeightfieldrcAllocHeightfield ()
 Allocates a heightfield object using the Recast allocator. More...
 
void rcFreeHeightField (rcHeightfield *hf)
 Frees the specified heightfield object using the Recast allocator. More...
 
rcCompactHeightfieldrcAllocCompactHeightfield ()
 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...
 
rcHeightfieldLayerSetrcAllocHeightfieldLayerSet ()
 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...
 
rcContourSetrcAllocContourSet ()
 Allocates a contour set object using the Recast allocator. More...
 
void rcFreeContourSet (rcContourSet *cset)
 Frees the specified contour set using the Recast allocator. More...
 
rcPolyMeshrcAllocPolyMesh ()
 Allocates a polygon mesh object using the Recast allocator. More...
 
void rcFreePolyMesh (rcPolyMesh *pmesh)
 Frees the specified polygon mesh using the Recast allocator. More...
 
rcPolyMeshDetailrcAllocPolyMeshDetail ()
 Allocates a detail mesh object using the Recast allocator. More...
 
void rcFreePolyMeshDetail (rcPolyMeshDetail *dmesh)
 Frees the specified detail mesh using the Recast allocator. 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, unsigned char *areas)
 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, unsigned char *areas)
 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 *ctx, rcHeightfield &hf, const int x, const int y, const unsigned short smin, const unsigned short smax, const unsigned char area, const int flagMergeThr)
 Adds a span to the specified heightfield. More...
 
bool rcRasterizeTriangle (rcContext *ctx, const float *v0, const float *v1, const float *v2, const unsigned char area, rcHeightfield &solid, const int flagMergeThr=1)
 Rasterizes a triangle into the specified heightfield. More...
 
bool rcRasterizeTriangles (rcContext *ctx, const float *verts, const int nv, const int *tris, const unsigned char *areas, const int nt, rcHeightfield &solid, const int flagMergeThr=1)
 Rasterizes an indexed triangle mesh into the specified heightfield. More...
 
bool rcRasterizeTriangles (rcContext *ctx, const float *verts, const int nv, const unsigned short *tris, const unsigned char *areas, const int nt, rcHeightfield &solid, const int flagMergeThr=1)
 Rasterizes an indexed triangle mesh into the specified heightfield. More...
 
bool rcRasterizeTriangles (rcContext *ctx, const float *verts, const unsigned char *areas, 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 neighbor. 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...
 

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 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, unsigned char 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, unsigned char 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 convex polygons for rcMarkConvexPolyArea. More...
 
void rcMarkCylinderArea (rcContext *ctx, const float *pos, const float r, const float h, unsigned char areaId, rcCompactHeightfield &chf)
 Applies the area id to all spans within the specified cylinder. 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...
 
int rcGetDirForOffset (int x, int y)
 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, 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...
 

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:

  1. Prepare the input triangle mesh.
  2. Build a rcHeightfield.
  3. Build a rcCompactHeightfield.
  4. Build a rcContourSet.
  5. Build a rcPolyMesh.
  6. Build a rcPolyMeshDetail.
  7. Use the rcPolyMesh and rcPolyMeshDetail to build a Detour navigation mesh tile.

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

  1. Allocate the object using the Recast allocator. (E.g. rcAllocHeightfield)
  2. Initialize or build the object. (E.g. rcCreateHeightfield)
  3. Update the object as needed. (E.g. rcRasterizeTriangles)
  4. Use the object as part of the pipeline.
  5. 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

bool rcAddSpan ( rcContext ctx,
rcHeightfield hf,
const int  x,
const int  y,
const unsigned short  smin,
const unsigned short  smax,
const unsigned char  area,
const int  flagMergeThr 
)

Adds a span to the specified heightfield.

Parameters
[in,out]ctxThe build context to use during the operation.
[in,out]hfAn initialized heightfield.
[in]xThe width index where the span is to be added. [Limits: 0 <= value < rcHeightfield::width]
[in]yThe height index where the span is to be added. [Limits: 0 <= value < rcHeightfield::height]
[in]sminThe minimum height of the span. [Limit: < smax] [Units: vx]
[in]smaxThe maximum height of the span. [Limit: <= RC_SPAN_MAX_HEIGHT] [Units: vx]
[in]areaThe area id of the span. [Limit: <= RC_WALKABLE_AREA)
[in]flagMergeThrThe merge theshold. [Limit: >= 0] [Units: vx]
Returns
True if the operation completed successfully.

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]ctxThe build context to use during the operation.
[in]walkableHeightMinimum floor to 'ceiling' height that will still allow the floor area to be considered walkable. [Limit: >= 3] [Units: vx]
[in]walkableClimbMaximum ledge height that is considered to still be traversable. [Limit: >=0] [Units: vx]
[in]hfThe heightfield to be compacted.
[out]chfThe 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]ctxThe build context to use during the operation.
[in]chfA fully built compact heightfield.
[in]maxErrorThe maximum distance a simplfied contour's border edges should deviate the original raw contour. [Limit: >=0] [Units: wu]
[in]maxEdgeLenThe maximum allowed length for contour edges along the border of the mesh. [Limit: >=0] [Units: vx]
[out]csetThe resulting contour set. (Must be pre-allocated.)
[in]buildFlagsThe 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]ctxThe build context to use during the operation.
[in,out]chfA 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]ctxThe build context to use during the operation.
[in]chfA fully built compact heightfield.
[in]borderSizeThe size of the non-navigable border around the heightfield. [Limit: >=0] [Units: vx]
[in]walkableHeightMinimum floor to 'ceiling' height that will still allow the floor area to be considered walkable. [Limit: >= 3] [Units: vx]
[out]lsetThe 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]ctxThe build context to use during the operation.
[in,out]chfA populated compact heightfield.
[in]borderSizeThe size of the non-navigable border around the heightfield. [Limit: >=0] [Units: vx]
[in]minRegionAreaThe 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]ctxThe build context to use during the operation.
[in]csetA fully built contour set.
[in]nvpThe maximum number of vertices allowed for polygons generated during the contour to polygon conversion process. [Limit: >= 3]
[out]meshThe 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]ctxThe build context to use during the operation.
[in]meshA fully built polygon mesh.
[in]chfThe compact heightfield used to build the polygon mesh.
[in]sampleDistSets the distance to use when samping the heightfield. [Limit: >=0] [Units: wu]
[in]sampleMaxErrorThe maximum distance the detail mesh surface should deviate from heightfield data. [Limit: >=0] [Units: wu]
[out]dmeshThe 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]ctxThe build context to use during the operation.
[in,out]chfA populated compact heightfield.
[in]borderSizeThe size of the non-navigable border around the heightfield. [Limit: >=0] [Units: vx]
[in]minRegionAreaThe minimum number of cells allowed to form isolated island areas. [Limit: >=0] [Units: vx].
[in]mergeRegionAreaAny 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]ctxThe build context to use during the operation.
[in,out]chfA populated compact heightfield.
[in]borderSizeThe size of the non-navigable border around the heightfield. [Limit: >=0] [Units: vx]
[in]minRegionAreaThe minimum number of cells allowed to form isolated island areas. [Limit: >=0] [Units: vx].
[in]mergeRegionAreaAny 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]vertsAn array of vertices. [(x, y, z) * nv]
[in]nvThe number of vertices in the verts array.
[out]bminThe minimum bounds of the AABB. [(x, y, z)] [Units: wu]
[out]bmaxThe 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]bminThe minimum bounds of the AABB. [(x, y, z)] [Units: wu]
[in]bmaxThe maximum bounds of the AABB. [(x, y, z)] [Units: wu]
[in]csThe xz-plane cell size. [Limit: > 0] [Units: wu]
[out]wThe width along the x-axis. [Limit: >= 0] [Units: vx]
[out]hThe height along the z-axis. [Limit: >= 0] [Units: vx]
void rcClearUnwalkableTriangles ( rcContext ctx,
const float  walkableSlopeAngle,
const float *  verts,
int  ,
const int *  tris,
int  nt,
unsigned char *  areas 
)

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]ctxThe build context to use during the operation.
[in]walkableSlopeAngleThe maximum slope that is considered walkable. [Limits: 0 <= value < 90] [Units: Degrees]
[in]vertsThe vertices. [(x, y, z) * nv]
[in]nvThe number of vertices.
[in]trisThe triangle vertex indices. [(vertA, vertB, vertC) * nt]
[in]ntThe number of triangles.
[out]areasThe triangle area ids. [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]ctxThe build context to use during the operation.
[in]srcThe source mesh to copy from.
[out]dstThe 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]ctxThe build context to use during the operation.
[in,out]hfThe allocated heightfield to initialize.
[in]widthThe width of the field along the x-axis. [Limit: >= 0] [Units: vx]
[in]heightThe height of the field along the z-axis. [Limit: >= 0] [Units: vx]
[in]bminThe minimum bounds of the field's AABB. [(x, y, z)] [Units: wu]
[in]bmaxThe maximum bounds of the field's AABB. [(x, y, z)] [Units: wu]
[in]csThe xz-plane cell size to use for the field. [Limit: > 0] [Units: wu]
[in]chThe y-axis cell size to use for field. [Limit: > 0] [Units: wu]
Returns
True if the operation completed successfully.

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]ctxThe build context to use during the operation.
[in]radiusThe radius of erosion. [Limits: 0 < value < 255] [Units: vx]
[in,out]chfThe 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]ctxThe build context to use during the operation.
[in]walkableHeightMinimum floor to 'ceiling' height that will still allow the floor area to be considered walkable. [Limit: >= 3] [Units: vx]
[in]walkableClimbMaximum ledge height that is considered to still be traversable. [Limit: >=0] [Units: vx]
[in,out]solidA 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 neighbor.

Parameters
[in,out]ctxThe build context to use during the operation.
[in]walkableClimbMaximum ledge height that is considered to still be traversable. [Limit: >=0] [Units: vx]
[in,out]solidA 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]ctxThe build context to use during the operation.
[in]walkableHeightMinimum floor to 'ceiling' height that will still allow the floor area to be considered walkable. [Limit: >= 3] [Units: vx]
[in,out]solidA 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]chfA compact heightfield allocated using rcAllocCompactHeightfield
See also
rcAllocCompactHeightfield
void rcFreeContourSet ( rcContourSet cset)

Frees the specified contour set using the Recast allocator.

Parameters
[in]csetA contour set allocated using rcAllocContourSet
See also
rcAllocContourSet
void rcFreeHeightField ( rcHeightfield hf)

Frees the specified heightfield object using the Recast allocator.

Parameters
[in]hfA heightfield allocated using rcAllocHeightfield
See also
rcAllocHeightfield
void rcFreeHeightfieldLayerSet ( rcHeightfieldLayerSet lset)

Frees the specified heightfield layer set using the Recast allocator.

Parameters
[in]lsetA heightfield layer set allocated using rcAllocHeightfieldLayerSet
See also
rcAllocHeightfieldLayerSet
void rcFreePolyMesh ( rcPolyMesh pmesh)

Frees the specified polygon mesh using the Recast allocator.

Parameters
[in]pmeshA polygon mesh allocated using rcAllocPolyMesh
See also
rcAllocPolyMesh
void rcFreePolyMeshDetail ( rcPolyMeshDetail dmesh)

Frees the specified detail mesh using the Recast allocator.

Parameters
[in]dmeshA 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]sThe span to check.
[in]dirThe 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 rcGetDirForOffset ( int  x,
int  y 
)
inline

Gets the direction for the specified offset.

One of x and y should be 0.

Parameters
[in]xThe x offset. [Limits: -1 <= value <= 1]
[in]yThe y offset. [Limits: -1 <= value <= 1]
Returns
The direction that represents the offset.
int rcGetDirOffsetX ( int  dir)
inline

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

Parameters
[in]dirThe 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]dirThe 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]ctxThe build context to use during the operation.
[in]hfAn initialized heightfield.
Returns
The number of spans in the heightfield.
void rcMarkBoxArea ( rcContext ctx,
const float *  bmin,
const float *  bmax,
unsigned char  areaId,
rcCompactHeightfield chf 
)

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

(AABB)

Parameters
[in,out]ctxThe build context to use during the operation.
[in]bminThe minimum of the bounding box. [(x, y, z)]
[in]bmaxThe maximum of the bounding box. [(x, y, z)]
[in]areaIdThe area id to apply. [Limit: <= RC_WALKABLE_AREA]
[in,out]chfA 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,
unsigned char  areaId,
rcCompactHeightfield chf 
)

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

Parameters
[in,out]ctxThe build context to use during the operation.
[in]vertsThe vertices of the polygon [Fomr: (x, y, z) * nverts]
[in]nvertsThe number of vertices in the polygon.
[in]hminThe height of the base of the polygon.
[in]hmaxThe height of the top of the polygon.
[in]areaIdThe area id to apply. [Limit: <= RC_WALKABLE_AREA]
[in,out]chfA 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,
unsigned char  areaId,
rcCompactHeightfield chf 
)

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

Parameters
[in,out]ctxThe build context to use during the operation.
[in]posThe center of the base of the cylinder. [Form: (x, y, z)]
[in]rThe radius of the cylinder.
[in]hThe height of the cylinder.
[in]areaIdThe area id to apply. [Limit: <= RC_WALKABLE_AREA]
[in,out]chfA 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,
unsigned char *  areas 
)

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

Parameters
[in,out]ctxThe build context to use during the operation.
[in]walkableSlopeAngleThe maximum slope that is considered walkable. [Limits: 0 <= value < 90] [Units: Degrees]
[in]vertsThe vertices. [(x, y, z) * nv]
[in]nvThe number of vertices.
[in]trisThe triangle vertex indices. [(vertA, vertB, vertC) * nt]
[in]ntThe number of triangles.
[out]areasThe 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]ctxThe build context to use during the operation.
[in,out]chfA 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]ctxThe build context to use during the operation.
[in]meshesAn array of detail meshes to merge. [Size: nmeshes]
[in]nmeshesThe number of detail meshes in the meshes array.
[out]meshThe 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]ctxThe build context to use during the operation.
[in]meshesAn array of polygon meshes to merge. [Size: nmeshes]
[in]nmeshesThe number of polygon meshes in the meshes array.
[in]meshThe 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 convex polygons for rcMarkConvexPolyArea.

Parameters
[in]vertsThe vertices of the polygon [Form: (x, y, z) * nverts]
[in]nvertsThe number of vertices in the polygon.
[out]outVertsThe offset vertices (should hold up to 2 * nverts) [Form: (x, y, z) * return value]
[in]maxOutVertsThe 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.
bool rcRasterizeTriangle ( rcContext ctx,
const float *  v0,
const float *  v1,
const float *  v2,
const unsigned char  area,
rcHeightfield solid,
const int  flagMergeThr 
)

Rasterizes a triangle into the specified heightfield.

Parameters
[in,out]ctxThe build context to use during the operation.
[in]v0Triangle vertex 0 [(x, y, z)]
[in]v1Triangle vertex 1 [(x, y, z)]
[in]v2Triangle vertex 2 [(x, y, z)]
[in]areaThe area id of the triangle. [Limit: <= RC_WALKABLE_AREA]
[in,out]solidAn initialized heightfield.
[in]flagMergeThrThe distance where the walkable flag is favored over the non-walkable flag. [Limit: >= 0] [Units: vx]
Returns
True if the operation completed successfully.

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

See also
rcHeightfield
bool rcRasterizeTriangles ( rcContext ctx,
const float *  verts,
const int  ,
const int *  tris,
const unsigned char *  areas,
const int  nt,
rcHeightfield solid,
const int  flagMergeThr 
)

Rasterizes an indexed triangle mesh into the specified heightfield.

Parameters
[in,out]ctxThe build context to use during the operation.
[in]vertsThe vertices. [(x, y, z) * nv]
[in]nvThe number of vertices.
[in]trisThe triangle indices. [(vertA, vertB, vertC) * nt]
[in]areasThe area id's of the triangles. [Limit: <= RC_WALKABLE_AREA] [Size: nt]
[in]ntThe number of triangles.
[in,out]solidAn initialized heightfield.
[in]flagMergeThrThe distance where the walkable flag is favored over the non-walkable flag. [Limit: >= 0] [Units: vx]
Returns
True if the operation completed successfully.

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

See also
rcHeightfield
bool rcRasterizeTriangles ( rcContext ctx,
const float *  verts,
const int  ,
const unsigned short *  tris,
const unsigned char *  areas,
const int  nt,
rcHeightfield solid,
const int  flagMergeThr 
)

Rasterizes an indexed triangle mesh into the specified heightfield.

Parameters
[in,out]ctxThe build context to use during the operation.
[in]vertsThe vertices. [(x, y, z) * nv]
[in]nvThe number of vertices.
[in]trisThe triangle indices. [(vertA, vertB, vertC) * nt]
[in]areasThe area id's of the triangles. [Limit: <= RC_WALKABLE_AREA] [Size: nt]
[in]ntThe number of triangles.
[in,out]solidAn initialized heightfield.
[in]flagMergeThrThe distance where the walkable flag is favored over the non-walkable flag. [Limit: >= 0] [Units: vx]
Returns
True if the operation completed successfully.

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

See also
rcHeightfield
bool rcRasterizeTriangles ( rcContext ctx,
const float *  verts,
const unsigned char *  areas,
const int  nt,
rcHeightfield solid,
const int  flagMergeThr 
)

Rasterizes triangles into the specified heightfield.

Parameters
[in,out]ctxThe build context to use during the operation.
[in]vertsThe triangle vertices. [(ax, ay, az, bx, by, bz, cx, by, cx) * nt]
[in]areasThe area id's of the triangles. [Limit: <= RC_WALKABLE_AREA] [Size: nt]
[in]ntThe number of triangles.
[in,out]solidAn initialized heightfield.
[in]flagMergeThrThe distance where the walkable flag is favored over the non-walkable flag. [Limit: >= 0] [Units: vx]
Returns
True if the operation completed successfully.

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]sThe span to update.
[in]dirThe direction to set. [Limits: 0 <= value < 4]
[in]iThe 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