PathEngine home previous: 3D Content Processing Parametersnext: Choosing Voxel Processing Parameters
Contents, Programmers Guide, World Representation, 3D Content Processing, 3D Content Processing Options

3D Content Processing Options

The following options may be specified (as attribute/value pairs) to control the exact behaviour of the 3D content processing functionality:

Common options

'stripTerrainHeightDetail'

Defaults to false, if no attribute is supplied.
When set to true, any internal height detail in terrain parts of the resulting ground mesh will be stripped out.
PathEngine's terrain callback can then be applied, to supply the relevent height information more efficiently, and without repeated representation of heavy terrain data.
See Working with Terrain for more details about the terrain callback mechanism.

With voxel based processing this option effectively suppresses any subdivision in terrain sections of the ground result.

'numberOfTerrainLayers'

Controls the number of sectionID values that should be treated as terrain.

Affects the way the 'stripTerrainHeightDetail' and 'maxSlopeOnTerrain' options are applied.
This value defaults to 1, if no attribute is not supplied, and in most cases should be left at this default value.

'removeObstructedFragmentsWithShape'

When set, the value string for this attribute will be parsed to obtain an agent shape, and any disconnected ground fragments that are completely obstructed for this agent shape discarded.

The vertex coordinate string should be supplied in the format x1,y1,x2,y2,x3,y3.. i.e. as a set of comma separated alternating x and y coordinate values of length depending on the number of vertices in the shape.
Exactly the same constraints apply to these vertex coordinates as to the coordinate array passed in to iPathEngine::newShape(), i.e. the shape must be convex, contain the origin, and so forth.
An example valid vertex coordinate string is "-20,-20,-20,20,20,20,20,-20" for a 40 unit by 40 unit axis aligned square.

'clipToTile'

This option is designed to support tiled 3D content processing.
Refer to this page for details.

'maxSlopeOnTerrain'

This option enables a different maximum slope to be applied for terrain parts of the ground result.
When set, the value string for this option must be a valid 32 bit signed value >= -1, and this is then used instead of the maxSlope parameter value passed into the content processing, for terrain faces.
(See iContentProcessing3D::buildGround() for an explanation of the maxSlope parameter.)

'excludeDownwardFacingFromGroundResult'

Defaults to 'false', if no attribute is supplied.

When set to 'true', all tris (in face/vertex source geometry) with anticlockwise vertex winding order, as seen from above, will be excluded from the ground result.
(So this avoids ground being generated for the 'back faces' of mesh geometry, in situations where geometry is designed to only be rendered for one facing direction.)

This option should probably be turned on in most cases where mesh source geometry is being supplied, with the vertex winding order of that geometry then set appropriately.

'method'

Can be set to either 'voxels' or 'bsp' to control the 3D processing method applied.
Defaults to 'bsp'.

'optimiseWithThreshold'

Setting this attribute to the desired maximum error value turns on mesh external edge optimisation.
This works in essentially the same way as the equivalent 2D content processing option.
(Refer to Mesh Optimisation for details.)

This option should always be set with voxel 3D processing in order to remove the jagged edges resulting from aliasing to the voxel grid.
Setting maximum error to a value at least equal to the voxel size chosen is generally a good idea, for this reason.

(But note that this option can now also be applied with BSP 3D processing.)

'optimiseThreshold_Vertical'

Can be used to specify a separate threshold for vertical error, in the mesh optimisation controlled by 'optimiseWithThreshold'.
(Refer to Mesh Optimisation for more details.)

'optimiseBoundariesWithThreshold'

Setting this attribute to the desired maximum error value turns on mesh internal boundary optimisation.
This works in essentially the same way as the equivalent 2D content processing option.
(Refer to Mesh Optimisation for details.)

This option should always be set with voxel 3D processing, when ground attributes are being passed through to the ground mesh result, in order to remove the jagged edges resulting from aliasing to the voxel grid.
Setting maximum error to a value at least equal to the voxel size chosen is generally a good idea, for this reason.

This option also be applied with BSP 3D processing.

'optimiseBoundariesThreshold_Vertical'

Can be used to specify a separate threshold for vertical error, in the mesh optimisation controlled by 'optimiseBoundariesWithThreshold'.
(Refer to Mesh Optimisation for more details.)

Options specific to BSP based 3D processing

'doOverlapAnalysis'

Defaults to true, if no attribute is supplied.

When turned on, the 3D processing performs an initial 2D analysis of the scene and bypasses BSP generation for any source geometry element which are not overlapped vertically by other elements.

This can significantly reduce processing times and memory load, in particular, for scenes with any significant level of terrain detail.

Most real world scenes are likely to benefit from this optimisation, but, in situations where there is absolutely no terrain-like or non-overlapping source geometry elements, turning off this option will speed up processing times slightly.

'groundGoesBelowTerrain'

Defaults to 'false', if no attribute is supplied.

When set to false, face vertex source geometry that is marked as terrain (i.e. with sectionID greater than or equal to zero and less than numberOfTerrainLayers) is considered to obstruct any other geometry below.
In this case, the terrain geometry is effectively extruded to negative infinity, instead of by the extrude height value supplied.
Note that this can then significantly speed up processing, in some circumstances, by avoiding the need to representation the underside of the terrain, and by enabling below terrain geometry components to be discarded as obstructed.

When set to true, terrain geometry is extruded in the same way as other source geometry components.

Options specific to voxel based 3D processing

'voxelSize'

The horizontal size of each voxel. Must be a positive integer less than or equal to 4000. Defaults to 10.

'minimumFragmentSize'

Specified in voxels, defaults to 5.
Ground regions with horizontal range less than this value (in either X or Y) will be discarded before any further processing.

'subdivisionSize'

Specified in voxels, must be set to either -1 or a non-zero positive value, defaults to -1.
When set to a non-zero positive value, the mesh result will be subdivided at this interval to approximate actual ground height.
When subdivision is being used in scenes with large ground areas it is important to mark terrain areas appropriately, and to set the 'stripTerrainHeightDetail', to avoid very large ground meshes being generated.

'subdivisionRegions'

Can be used to restrict ground subdivision to a supplied set of axis aligned regions.
Coordinate data for the axis aligned regions are supplied in the value string for this attribute, formatted like "250,350,150,300,450,170;100,350,150,120,450,170", where:

Candidate subdivision vertices are then filtered by these ranges, and only inserted where the vertex is inside (or exactly on the boundary of) at least one of the ranges.

'markClearanceRegionsWithHeights'

Can be used to paint surfaceType ground attribute values into the result based on the amount of height clearance at different points on the ground mesh.

The value of this option should be a set of (comma separated) heights for which clearance regions should be generated, in increasing height order, and with the minimum height specified being greater than the voxel processing extrude height paramter.

Currently a maximum of seven clearance regions are supported.

(Has no effect if supplied with BSP processing.)


Documentation for PathEngine release 6.04 - Copyright © 2002-2024 PathEnginenext: Choosing Voxel Processing Parameters