Unigine::SplineGraph Class

This class is used to manage vertices and segments of spline graphs. UNIGINE's 3D spline system has a wide range of applications, particularly procedural content generation (rivers, roads, pipelines etc.).

A spline graph is determined by a set of points p0, p 1, ... p n and a set of segments (cubic Bezier splines), that connect some or all of these points.

Each segment is determined by the indices of the starting (pSTART ) and ending (pEND ) points and tangent vector coordinates at these points, which determine the form of the segment (tSTART and tEND respectively).

Coordinates of the "up" vector are additionally stored for each point of the segment. You can specify this vector to define orientation of geometry or objects, that can be stretched or tiled along the segments of the spline graph. By default this vector is parallel to the Z axis. The "up" vector does not affect the form of the spline segment.

It is possible to obtain an interpolated value for any point belonging to a segment, this can be used for various purposes (e.g. to change road profile). Interpolated "up" vector can be calculated as follows (pseudocode):

Source code (C++)
``````vec3 lerpUpVector(vec3 start_up, vec3 end_up, float t) const
{
float angle = acos(dot(start_up, end_up)) * RAD2DEG;
vec3 rotation_axis = cross(start_up, end_up);

return rotateAxisAngle(rotation_axis, angle * t) * start_up;
}``````

• The C++ API sample <UnigineSDK>/data/samples/worlds/spline_graph_00. It illustrates:

• Creation of a SplineGraph from scratch.
• Movement of a node along the segments of the SplineGraph.
• The WorldSplineGraph class article to learn how to generate geometry along a spline graph.
• The Spline File Format article to learn how the spline graph data is stored.

static SplineGraphPtr create ( )

Default constructor. Creates an empty spline graph.

static SplineGraphPtr create ( const char * name )

Constructor. Creates an empty spline graph with a given name.

Arguments

• const char * name - Spline graph name.

static SplineGraphPtr create ( const Ptr<SplineGraph> & graph )

Constructor. Creates a spline graph by copying a given source spline graph.

Arguments

• const Ptr<SplineGraph> & graph - Source spline graph.

floatgetLength( int index )

Retuns the length of the segment with a given index.

Arguments

• int index - Segment index.

Segment length.

intgetNumPoints( )

Returns the total number of points in the spline graph.

Return value

Number of points.

intgetNumSegments( )

Returns the total number of segments in the spline graph.

Return value

Number of segments.

intisOwner( )

Returns the owner flag. If the pointer is the owner, on its deletion the spline graph also will be deleted. Use grab() and release() functions to change ownership

Owner flag.

voidsetPoint( int index, const Math::Vec3 & point )

Sets new coordinates for the point with a given index.

Arguments

• int index - Point index.
• const Math::Vec3 & point - New point coordinates.

Math::Vec3getPoint( int index )

Returns the coordinates of the point with a given index.

Arguments

• int index - Point index.

Return value

Point coordinates.

voidsetSegmentEndPoint( int index, const Math::Vec3 & point )

Sets the coordinates of the end point for the segment with a given index.

Arguments

• int index - Segment index.
• const Math::Vec3 & point - Segment end point coordinates to be set.

Math::Vec3getSegmentEndPoint( int index )

Returns the coordinates of the end point for the segment with a given index.

Arguments

• int index - Segment index.

Return value

Segment end point coordinates.

intgetSegmentEndPointIndex( int index )

Returns the index of the end point for the segment with a given index.

Arguments

• int index - Segment index.

Return value

Segment end point index.

voidsetSegmentEndTangent( int index, const Math::vec3 & tangent )

Sets the tangent coordinates for the end point of the segment with a given index.

Arguments

• int index - Segment index.
• const Math::vec3 & tangent - End point tangent coordinates.

Math::vec3getSegmentEndTangent( int index )

Returns the tangent coordinates for the end point of the segment with a given index.

Arguments

• int index - Segment index.

Return value

End point tangent coordinates.

voidsetSegmentEndUpVector( int index, const Math::vec3 & up )

Sets the "up" vector coordinates for the end point of the segment with a given index.

Math::vec3getSegmentEndUpVector( int index )

Returns the "up" vector coordinates for the end point of the segment with a given index.

Arguments

• int index - Segment index.

Return value

End point "up" vector coordinates.

voidsetSegmentStartPoint( int index, const Math::Vec3 & point )

Sets the coordinates of the start point for the segment with a given index.

Arguments

• int index - Segment index.
• const Math::Vec3 & point - Segment start point coordinates to be set.

Math::Vec3getSegmentStartPoint( int index )

Returns the coordinates of the start point for the segment with a given index.

Arguments

• int index - Segment index.

Return value

Segment start point coordinates.

intgetSegmentStartPointIndex( int index )

Returns the index of the end point for the segment with a given index.

Arguments

• int index - Segment index.

Return value

Segment start point index.

voidsetSegmentStartTangent( int index, const Math::vec3 & tangent )

Sets the tangent coordinates for the start point of the segment with a given index.

Arguments

• int index - Segment index.
• const Math::vec3 & tangent - Start point tangent coordinates.

Math::vec3getSegmentStartTangent( int index )

Returns the tangent coordinates for the start point of the segment with a given index.

Arguments

• int index - Segment index.

Return value

Start point tangent coordinates.

voidsetSegmentStartUpVector( int index, const Math::vec3 & up )

Sets the "up" vector coordinates for the start point of the segment with a given index.

Math::vec3getSegmentStartUpVector( int index )

Returns the "up" vector coordinates for the start point of the segment with a given index.

Arguments

• int index - Segment index.

Return value

Start point "up" vector coordinates.

intaddPoint( const Math::Vec3 & point )

Adds a point with specified coordinates to the spline graph.

Arguments

• const Math::Vec3 & point - Point coordinates.

Return value

Current number of points in the spline graph.

intaddSegment( int start_index, const Math::vec3 & start_tangent, const Math::vec3 & start_up, int end_index, const Math::vec3 & end_tangent, const Math::vec3 & end_up )

Adds a segment to the spline graph.

Arguments

• int start_index - Start point index.
• const Math::vec3 & start_tangent - Start point tangent coordinates.
• const Math::vec3 & start_up - Start point "up" vector coordinates.
• int end_index - End point index.
• const Math::vec3 & end_tangent - End point tangent coordinates.
• const Math::vec3 & end_up - End point "up" vector coordinates.

Return value

Number of segments in the spline graph if a segment was addes successfully; otherwise, -1

Math::Vec3calcSegmentPoint( int index, float t )

Returns the coordinates of the point on the given segment.

Arguments

• int index - Segment index.
• float t - Position of the point on the segment, in increments of the segment's length normalized to 1.

Return value

Coordinates of the point on the given segment.

Math::vec3calcSegmentTangent( int index, float t )

Returns the tangent coordinates for the point on the given segment.

Arguments

• int index - Segment index.
• float t - Position of the point on the segment, in increments of the segment's length normalized to 1.

Return value

Tangent coordinates for the point on the given segment.

Math::vec3calcSegmentUpVector( int index, float t )

Returns the "up" vector coordinates for the point on the given segment.

Arguments

• int index - Segment index.
• float t - Position of the point on the segment, in increments of the segment's length normalized to 1.

Return value

"Up" vector coordinates for the point on the given segment.

voidclear( )

Clears the spline graph.

voidgrab( )

Grabs the spline graph (sets the owner flag to 1). The spline graph should not be handled by the engine after this function is called.

intload( const char * name )

Loads the spline graph from the specified XML-file.

Arguments

• const char * name - Name of the XML-file to load the spline graph from.

Return value

1 if the spline graph was successfully loaded; otherwise, 0.

voidrelease( )

Releases the spline graph (sets the owner flag to 0). The spline graph should be handled by the engine after this function is called.

voidremovePoint( int index, int merge = 0 )

Removes a point with a given index from the spline graph.

Arguments

• int index - Point index.
• int merge - Merge flag. When there are two segments attached to the point, use 1 to merge these segments into one; 0 removes all segments attached to the point (by default).

voidsplitPoint( int index )

Splits the point with the specified index into N points, where N is the number of segments attached to the point. The number of points in the graph shall increase by N-1. All new points will be attached to the corresponding segments.

Arguments

• int index - Point index.

voidweldPoints( Vector< int > & indices )

Merges all points with given indices into one.
Notice
All common segments between these points shall be removed. All points with given indices are removed from the graph, except for the one having the minimum index value, all segments shall be attached to this point. Resulting point shall be moved to the position of the first point in the given array.

Arguments

• Vector< int > & indices - Array containing indices of points to be merged into one.

voidremoveSegment( int index, int with_points = 0 )

Removes the segment with a given index.

Arguments

• int index - Segment index.
• int with_points - Use 1 to remove segment with its starting and ending points, or 0 to remove the segment only.
Notice
Points will be removed only in case if they do not belong to other segments. After removal, the last element of the vector of spline graph segments shall be moved to the position of the one removed.

intsave( const char * name )

Saves the spline graph to the specified XML-file.

Arguments

• const char * name - Name of the XML-file to save the spline graph to.

Return value

1 if the spline graph was successfully saved; otherwise, 0.

voidinsertPointToSegment( int segment_index, float new_point_t )

Inserts a new point into the given segment with the specified offset from the starting point.

Arguments

• int segment_index - Segment index.
• float new_point_t - Offset of the new point to be added from the starting point of the segment in the range [0.0f, 1.0f].

voidgetPointSegmentsIndices( int index, Vector< int > & indices )

Retrieves indices of all segments attached to the specified point and puts them to the given index buffer.

Arguments

• int index - Point index.
• Vector< int > & indices - Index buffer to which segment indices will be added.
Last update: 2018-12-27