Unigine.WorldSplineGraph Class
| 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
Properties
int NumSplineSegments#
The total number of spline segments in the world spline graph.
int NumSplinePoints#
The total number of spline points in the world spline graph.
bool IsCurved#
The A value indicating if the world spline graph is curved.
Members
WorldSplineGraph ( ) #
Default constructor. Creates an empty world spline graph.WorldSplineGraph ( string name ) #
Constructor. Creates an empty world spline graph with a given name.Arguments
- string name - World spline graph name.
void SetSplineGraphName ( string name, bool force_load = 0 ) #
Sets the name of the world spline graph.Arguments
- string 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.
string GetSplineGraphName ( ) #
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.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 ( string name ) #
Loads a spline graph from the specified XML-file.Arguments
- string 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 ( string name ) #
Saves a spline graph to the specified XML-file.Arguments
- string 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 ( Mesh mesh, 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
- Mesh mesh - Target mesh instance to which the obtained mesh is to be put.
- 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 ( Mesh mesh, 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
- Mesh mesh - Target mesh to store the desired mesh placed at the specified spline point.
- 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.
SplinePoint CreateSplinePoint ( vec3 position ) #
Creates a new spline point with the specified parameters and attaches it to the world spline graph.Arguments
- vec3 position - Position coordinates for the new splint point.
Return value
New spline point.void RemoveSplinePoint ( 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
- 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 ( SplinePoint[] points ) #
Returns the list of all points of the world spline graph and puts them to the specified array of SplinePoint elements.Arguments
- SplinePoint[] points - Array to store the list of all points of the world spline graph.
SplineSegment CreateSplineSegment ( SplinePoint start_point, vec3 start_tangent, vec3 start_up, SplinePoint end_point, vec3 end_tangent, vec3 end_up ) #
Creates a new spline segment with the specified parameters and attaches it to the world spline graph.Arguments
- SplinePoint start_point - Start point of the spline segment.
- vec3 start_tangent - Tangent coordinates for the start point of the spline segment.
- vec3 start_up - Coordinates of the "up" vector for the start point of the spline segment.
- SplinePoint end_point - End point of the segment.
- vec3 end_tangent - Tangent coordinates for the end point of the spline segment.
- 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 ( 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
- 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 ( SplineSegment[] segments ) #
Returns the list of all segments of the world spline graph and puts them to the specified array of SplineSegment elements.Arguments
- SplineSegment[] segments - Array 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 ( ) #
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.IntPtr addPointAddedCallback ( PointAddedDelegate 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(WorldSplineGraph graph, SplinePoint point);You can set a callback function as follows:
Source code (C#)
addPointAddedCallback((g, point) => point_added_callback_function_name(g, point));Arguments
- PointAddedDelegate func - Callback function with the following signature: void PointAddedDelegate(WorldSplineGraph graph, SplinePoint point)
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 ( IntPtr id ) #
Removes the specified callback from the list of Point Added callbacks.Arguments
- IntPtr 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.IntPtr addPointChangedCallback ( PointChangedDelegate 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(WorldSplineGraph graph, SplinePoint point);You can set a callback function as follows:
Source code (C#)
addPointChangedCallback((g, point) => point_changed_callback_function_name(g, point));Arguments
- PointChangedDelegate func - Callback function with the following signature: void PointChangedDelegate(WorldSplineGraph graph, SplinePoint point)
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 ( IntPtr id ) #
Removes the specified callback from the list of Point Changed callbacks.Arguments
- IntPtr 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.IntPtr addPointRemovedCallback ( PointRemovedDelegate 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(WorldSplineGraph graph, SplinePoint point);You can set a callback function as follows:
Source code (C#)
addPointRemovedCallback((g, point) => point_removed_callback_function_name(g, point));Arguments
- PointRemovedDelegate func - Callback function with the following signature: void PointRemovedDelegate(WorldSplineGraph graph, SplinePoint point)
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 ( IntPtr id ) #
Removes the specified callback from the list of Point Removed callbacks.Arguments
- IntPtr 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.IntPtr addSegmentAddedCallback ( SegmentAddedDelegate 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(WorldSplineGraph graph, SplineSegment segment);You can set a callback function as follows:
Source code (C#)
addSegmentAddedCallback((g, segment) => segment_added_callback_function_name(g, segment));Arguments
- SegmentAddedDelegate func - Callback function with the following signature: void SegmentAddedDelegate(WorldSplineGraph graph, SplineSegment segment)
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 ( IntPtr id ) #
Removes the specified callback from the list of Segment Added callbacks.Arguments
- IntPtr 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.IntPtr addSegmentChangedCallback ( SegmentChangedDelegate 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(WorldSplineGraph graph, SplineSegment segment);You can set a callback function as follows:
Source code (C#)
addSegmentChangedCallback((g, segment) => segment_changed_callback_function_name(g, segment));Arguments
- SegmentChangedDelegate func - Callback function with the following signature: void SegmentChangedDelegate(WorldSplineGraph graph, SplineSegment segment)
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 ( IntPtr id ) #
Removes the specified callback from the list of Segment Changed callbacks.Arguments
- IntPtr 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.IntPtr addSegmentRemovedCallback ( SegmentRemovedDelegate 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(WorldSplineGraph graph, SplineSegment segment);You can set a callback function as follows:
Source code (C#)
addSegmentRemovedCallback((g, segment) => segment_removed_callback_function_name(g, segment));Arguments
- SegmentRemovedDelegate func - Callback function with the following signature: void SegmentRemovedDelegate(WorldSplineGraph graph, SplineSegment segment)
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 ( IntPtr id ) #
Removes the specified callback from the list of Segment Removed callbacks.Arguments
- IntPtr 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 ( 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
- 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 ( 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
- SplinePoint point - Spline point to be broken.
NoticeThe point must be shared by a least 2 segments.
void WeldSplinePoints ( 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
- SplinePoint[] points - List of spline points to be joined into a single one.
bool IsLinked ( SplinePoint point ) #
Returns a value indicating if the specified spline point is linked to any spline segment.Arguments
- 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:
2022-12-14
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)