Unigine::WorldSplineGraph Class
| Header: | #include <UnigineWorlds.h> |
| Inherits from: | Node |
Warning
This feature is an experimental one and is not recommended for production use.
This class is used to generate specified nodes (called source nodes) along a spline graph.
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;
}A world spline graph consists of segments and has a list of source nodes (currently ObjectMeshStatic, ObjectMeshSkinned, and DecalProj) that can be placed at points and along the segments of the spline graph. Each point and segment can have a single or a set of source nodes assigned. An arbitrary number of WorldSplineGraph nodes can be added to the scene.
WorldSplineGraph has the following features:
- Points of the spline graph are managed via the SplinePoint class.
- Segments of the spline graph are managed via the SplineSegment class.
- 3 modes are supported:
- stretching: source nodes are stretched along the spline segment.
- tiling: source nodes are duplicated along the spline segment.
- adaptive - represents a combination of the first two: source nodes are duplicated along the spline segment, but the length of each node (stretching) is determined by the curvature of the corresponding part of the segment. Thus, long nodes are placed along the straight parts of segments, while short ones - along the curved parts, providing a reasonable balance between the plausible look and performance.
- Forward axis selection for stretching/tiling source nodes.
See Also#
See the article on the World Spline Graph object.
See the following UnigineScript API samples to learn how to manage the WorldSplineGraph class:
<UnigineSDK>/data/samples/worlds/world_spline_graph_00 featuring:
- Creation of a WorldSplineGraph node from a SplineGraph file
- Generation of geometry along the graph segments in stretching mode
<UnigineSDK>/data/samples/worlds/world_spline_graph_01 featuring:
- Creation of a WorldSplineGraph node from a SplineGraph file
- Generation of geometry along the graph segments in tiling mode
The C++ API sample <UnigineSDK>/source/samples/Api/Nodes/SplineGraph
WorldSplineGraph Class
Members
static WorldSplineGraphPtr create ( ) #
Default constructor. Creates an empty world spline graph.static WorldSplineGraphPtr create ( const char * name ) #
Constructor. Creates an empty world spline graph with a given name.Arguments
- const char * name - World spline graph name.
int getNumSplinePoints ( ) const#
Returns the total number of spline points in the world spline graph.Return value
Number of spline points.int getNumSplineSegments ( ) const#
Returns the total number of spline segments in the world spline graph.Return value
Number of segments.void setSplineGraphName ( const char * name, bool force_load = 0 ) #
Sets the name of the world spline graph.Arguments
- const char * name - World spline graph name.
- bool force_load - Force flag.
- If 1 is specified, the world spline graph will immediately loaded from a file.
- If 0 is specified, only the world spline graph name will be updated.
const char * getSplineGraphName ( ) const#
Returns the name of the world spline graph.Return value
World spline graph name.void loadSegmentNodes ( int segment_index = -1 ) #
Loads source nodes assigned to the specified spline segment immediately.Arguments
- int segment_index - Segment index. If no segment index is specified, the method loads source nodes assigned to all segments.
void clear ( ) #
Clears the world spline graph.bool isCurved ( ) const#
Returns a value indicating if the world spline graph is curved.Return value
true if the world spline graph is curved; otherwise, false.void makeCurved ( ) #
Curves the world spline graph using its geodetic pivot. The spline file is saved upon completion of the curving operation.Notice
The world spline graph must be a child of a Geodetic Pivot node.
void makeFlat ( ) #
Flattens the world spline graph using its geodetic pivot. The spline file is saved upon completion of the flattening operation.Notice
The world spline graph must be a child of a Geodetic Pivot node.
bool load ( const char * name ) #
Loads a spline graph from the specified XML-file.Arguments
- const char * name - Name of the XML-file to load the spline graph from.
Return value
true if the spline graph was successfully loaded; otherwise, false.bool save ( const char * name ) #
Saves a spline graph to the specified XML-file.Arguments
- const char * name - Name of the XML-file to save the spline graph to.
Return value
true if the spline graph was successfully saved; otherwise, false.static int type ( ) #
Returns the type of the node.Return value
WorldSplineGraph type identifier.void getSegmentNodeMesh ( const Ptr<Mesh> & mesh, const Ptr<SplineSegment> & segment, int node_index, bool bake_transform = 0 ) #
Gets a mesh used by a node with the specified index, placed along the specified spline segment, and puts it to the specified target Mesh instance.Arguments
- const Ptr<Mesh> & mesh - Target mesh instance to which the obtained mesh is to be put.
- const Ptr<SplineSegment> & segment - Spline segment for which the mesh is to be returned.
- int node_index - Number of the node instance placed along the spline segment.
- bool bake_transform - true to use baked mesh transformation, false - to use default (the mesh will be placed at the origin). The default value is false.
void getPointNodeMesh ( Ptr<Mesh> & mesh, const Ptr<SplinePoint> & point, int node_index, bool bake_transform = false ) #
Exports a mesh with the specified index placed as the specified spline point to the specified target mesh.Notice
Due to the nature of the mesh, there will be visual artifacts connected with the float precision, in case an exported node is located very far from the origin (around 10,000 m and further). In this case we advise exporting it without baking transformation.
Arguments
- Ptr<Mesh> & mesh - Target mesh to store the desired mesh placed at the specified spline point.
- const Ptr<SplinePoint> & point - Spline point for which a mesh is to be retrieved.
- int node_index - Number of the desired node in a row of nodes placed at the specified point, in the range from 0 to the total number of nodes placed at the point.NoticeThe node must be an ObjectMeshStatic or an ObjectMeshSkinned, otherwise an error occurs.
- bool bake_transform - Bake Transform flag: true - to export the mesh preserving the current coordinates (can be useful when splitting large WorldSplineGraph objects to keep relative positions of meshes); or false - to reset the position of the exported mesh to origin (0,0,0) with zero-rotation.
Ptr<SplinePoint> createSplinePoint ( const Math::Vec3& position ) #
Creates a new spline point with the specified parameters and attaches it to the world spline graph.Arguments
- const Math::Vec3& position - Position coordinates for the new splint point.
Return value
New spline point.void removeSplinePoint ( const Ptr<SplinePoint> & point, bool merge = 0 ) #
Removes the specified spline point from the world spline graph. You can set the merge flag to merge spline segments sharing this point as their start and end points.Notice
Segment merging is available only when the point to be removed is shared by two segments, otherwise the merge flag is ignored and all segments sharing this point are also removed.
Arguments
- const Ptr<SplinePoint> & point - Spline point to be removed.
- bool merge - true to merge spline segments sharing this point as their start and end points, false to remove all segments sharing this point. The default value is false.
void getSplinePoints ( Vector< Ptr<SplinePoint> > & points ) const#
Returns the list of all points of the world spline graph and puts them to the specified vector of SplinePoint elements.Arguments
- Vector< Ptr<SplinePoint> > & points - Vector to store the list of all points of the world spline graph.
Ptr<SplineSegment> createSplineSegment ( const Ptr<SplinePoint> & start_point, const Math::vec3& start_tangent, const Math::vec3& start_up, const Ptr<SplinePoint> & end_point, const Math::vec3& end_tangent, const Math::vec3& end_up ) #
Creates a new spline segment with the specified parameters and attaches it to the world spline graph.Arguments
- const Ptr<SplinePoint> & start_point - Start point of the spline segment.
- const Math::vec3& start_tangent - Tangent coordinates for the start point of the spline segment.
- const Math::vec3& start_up - Coordinates of the "up" vector for the start point of the spline segment.
- const Ptr<SplinePoint> & end_point - End point of the segment.
- const Math::vec3& end_tangent - Tangent coordinates for the end point of the spline segment.
- const Math::vec3& end_up - Coordinates of the "up" vector for the end point of the spline segment.
Return value
New spline segment connecting two specified points.void removeSplineSegment ( const Ptr<SplineSegment> & segment, bool with_points = 0 ) #
Removes the specified spline segment from the world spline graph. You can set the with_points flag to remove the segment together with its start and end points.Arguments
- const Ptr<SplineSegment> & segment - Spline segment to be removed.
- bool with_points - true to remove the segment with its start and end points, false to keep points. The default value is false.
void getSplineSegments ( Vector< Ptr<SplineSegment> > & segments ) const#
Returns the list of all segments of the world spline graph and puts them to the specified vector of SplineSegment elements.Arguments
- Vector< Ptr<SplineSegment> > & segments - Vector to store the list of all segments of the world spline graph.
void rebuild ( int try_force = 0 ) #
Rebuilds the world spline graph. This method is to be called after making any changes to spline segments (mode, etc.), point positions, tangents, or "up" vectors, as well as after changing source node assignments and/or other parameters (UV tiling, gap, etc.)Arguments
- int try_force - Forced rebuild flag: set 1 to try and force rebuild the world spline graph.
int isRebuilding ( ) const#
Returns a value indicating if the world spline graph is currently being rebuilt. The world spline graph uses a deferred rebuild.Return value
1 if the world spline graph is currently being rebuilt; otherwise 0.void * addPointAddedCallback ( Unigine::CallbackBase2< Ptr<Body>, int > * func ) #
Adds a callback function to be called when a point is added to the world spline graph. The signature of the Point Added callback function must be as follows:Source code (C++)
void point_added_callback_function_name(WorldSplineGraphPtr graph, SplinePointPtr point);You can set a callback function as follows:
Source code (C++)
addPointAddedCallback(MakeCallback(point_added_callback_function_name));Arguments
- Unigine::CallbackBase2< Ptr<Body>, int > * func - Callback pointer.
Return value
ID of the last added Point Added callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.bool removePointAddedCallback ( void * id ) #
Removes the specified callback from the list of Point Added callbacks.Arguments
- void * id - Point Added callback ID obtained when adding it.
Return value
True if the Point Added callback with the given ID was removed successfully; otherwise false.void clearPointAddedCallbacks ( ) #
Clears all added Point Added callbacks.void * addPointChangedCallback ( Unigine::CallbackBase2< Ptr<Body>, int > * func ) #
Adds a callback function to be called when a point of the world spline graph is modified. The signature of the Point Changed callback function must be as follows:Source code (C++)
void point_changed_callback_function_name(WorldSplineGraphPtr graph, SplinePointPtr point);You can set a callback function as follows:
Source code (C++)
addPointChangedCallback(MakeCallback(point_changed_callback_function_name));Arguments
- Unigine::CallbackBase2< Ptr<Body>, int > * func - Callback pointer.
Return value
ID of the last added Point Changed callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.bool removePointChangedCallback ( void * id ) #
Removes the specified callback from the list of Point Changed callbacks.Arguments
- void * id - Point Changed callback ID obtained when adding it.
Return value
True if the Point Changed callback with the given ID was removed successfully; otherwise false.void clearPointChangedCallbacks ( ) #
Clears all added Point Changed callbacks.void * addPointRemovedCallback ( Unigine::CallbackBase2< Ptr<Body>, int > * func ) #
Adds a callback function to be called when a point of the world spline graph is removed. The signature of the Point Removed callback function must be as follows:Source code (C++)
void point_removed_callback_function_name(WorldSplineGraphPtr graph, SplinePointPtr point);You can set a callback function as follows:
Source code (C++)
addPointRemovedCallback(MakeCallback(point_removed_callback_function_name));Arguments
- Unigine::CallbackBase2< Ptr<Body>, int > * func - Callback pointer.
Return value
ID of the last added Point Removed callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.bool removePointRemovedCallback ( void * id ) #
Removes the specified callback from the list of Point Removed callbacks.Arguments
- void * id - Point Removed callback ID obtained when adding it.
Return value
True if the Point Removed callback with the given ID was removed successfully; otherwise false.void clearPointRemovedCallbacks ( ) #
Clears all added Point Removed callbacks.void * addSegmentAddedCallback ( Unigine::CallbackBase2< Ptr<Body>, int > * func ) #
Adds a callback function to be called when a segment is added to the world spline graph. The signature of the Segment Added callback function must be as follows:Source code (C++)
void segment_added_callback_function_name(WorldSplineGraphPtr graph, SplineSegmentPtr segment);You can set a callback function as follows:
Source code (C++)
addSegmentAddedCallback(MakeCallback(segment_added_callback_function_name));Arguments
- Unigine::CallbackBase2< Ptr<Body>, int > * func - Callback pointer.
Return value
ID of the last added Segment Added callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.bool removeSegmentAddedCallback ( void * id ) #
Removes the specified callback from the list of Segment Added callbacks.Arguments
- void * id - Segment Added callback ID obtained when adding it.
Return value
True if the Segment Added callback with the given ID was removed successfully; otherwise false.void clearSegmentAddedCallbacks ( ) #
Clears all added Segment Added callbacks.void * addSegmentChangedCallback ( Unigine::CallbackBase2< Ptr<Body>, int > * func ) #
Adds a callback function to be called when a segment of the world spline graph is modified. The signature of the Segment Changed callback function must be as follows:Source code (C++)
void segment_changed_callback_function_name(WorldSplineGraphPtr graph, SplineSegmentPtr segment);You can set a callback function as follows:
Source code (C++)
addSegmentChangedCallback(MakeCallback(segment_changed_callback_function_name));Arguments
- Unigine::CallbackBase2< Ptr<Body>, int > * func - Callback pointer.
Return value
ID of the last added Segment Changed callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.bool removeSegmentChangedCallback ( void * id ) #
Removes the specified callback from the list of Segment Changed callbacks.Arguments
- void * id - Segment Changed callback ID obtained when adding it.
Return value
True if the Segment Changed callback with the given ID was removed successfully; otherwise false.void clearSegmentChangedCallbacks ( ) #
Clears all added Segment Changed callbacks.void * addSegmentRemovedCallback ( Unigine::CallbackBase2< Ptr<Body>, int > * func ) #
Adds a callback function to be called when a segment of the world spline graph is removed. The signature of the Segment Removed callback function must be as follows:Source code (C++)
void segment_removed_callback_function_name(WorldSplineGraphPtr graph, SplineSegmentPtr segment);You can set a callback function as follows:
Source code (C++)
addSegmentRemovedCallback(MakeCallback(segment_removed_callback_function_name));Arguments
- Unigine::CallbackBase2< Ptr<Body>, int > * func - Callback pointer.
Return value
ID of the last added Segment Removed callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.bool removeSegmentRemovedCallback ( void * id ) #
Removes the specified callback from the list of Segment Removed callbacks.Arguments
- void * id - Segment Removed callback ID obtained when adding it.
Return value
True if the Segment Removed callback with the given ID was removed successfully; otherwise false.void clearSegmentRemovedCallbacks ( ) #
Clears all added Segment Removed callbacks.void splitSplineSegment ( const Ptr<SplineSegment> & segment, float new_point_t ) #
Splits the specified spline segment into two parts by inserting a new point placed at the parametrically specified point on the T (times axis) in the [0.0f, 1.0f] range from the segment's start point.
Arguments
- const Ptr<SplineSegment> & segment - Spline segment to be split.
- float new_point_t - Coordinate of the splitting point of the segment along the horizontal T (times) axis in the range [0.0f, 1.0f].
void breakSplinePoint ( const Ptr<SplinePoint> & point ) #
Breaks the specified spline point shared by several spline segments into a set of separate ones, so that each of the segments gets its own point.Arguments
- const Ptr<SplinePoint> & point - Spline point to be broken.
NoticeThe point must be shared by a least 2 segments.
void weldSplinePoints ( Vector< Ptr<SplinePoint> > & points ) #
Joins all spline points specified in the list into a single one, so that this point is shared by all spline segments having the specified points as starting or ending ones.Arguments
- Vector< Ptr<SplinePoint> > & points - List of spline points to be joined into a single one.
bool isLinked ( const Ptr<SplinePoint> & point ) const#
Returns a value indicating if the specified spline point is linked to any spline segment.Arguments
- const Ptr<SplinePoint> & point - Spline point to be checked.
Return value
1 if the specified spline point is linked to any spline segment; otherwise, 0.Last update:
2023-06-23
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)