5241464a46
This commit makes the following major changes 1. Add "sample_baked_with_rotation()" to Curve3D, making it usable independently. A similar change was made to Curve2D previously. 2. Refactor the _bake() method on Curve3D, using Parallel Transport Frame instead of Frenet Frame. 3. Refactor the sample_* methods, including: i. Factor out common binary search code, following the DRY principe ii. sample_up_vector() interpolated up vector as part of rotation frame(posture) for consistancy and accuracy.
208 lines
12 KiB
XML
208 lines
12 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<class name="Curve3D" inherits="Resource" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
|
|
<brief_description>
|
|
Describes a Bézier curve in 3D space.
|
|
</brief_description>
|
|
<description>
|
|
This class describes a Bézier curve in 3D space. It is mainly used to give a shape to a [Path3D], but can be manually sampled for other purposes.
|
|
It keeps a cache of precalculated points along the curve, to speed up further calculations.
|
|
</description>
|
|
<tutorials>
|
|
</tutorials>
|
|
<methods>
|
|
<method name="add_point">
|
|
<return type="void" />
|
|
<param index="0" name="position" type="Vector3" />
|
|
<param index="1" name="in" type="Vector3" default="Vector3(0, 0, 0)" />
|
|
<param index="2" name="out" type="Vector3" default="Vector3(0, 0, 0)" />
|
|
<param index="3" name="index" type="int" default="-1" />
|
|
<description>
|
|
Adds a point with the specified [param position] relative to the curve's own position, with control points [param in] and [param out]. Appends the new point at the end of the point list.
|
|
If [param index] is given, the new point is inserted before the existing point identified by index [param index]. Every existing point starting from [param index] is shifted further down the list of points. The index must be greater than or equal to [code]0[/code] and must not exceed the number of existing points in the line. See [member point_count].
|
|
</description>
|
|
</method>
|
|
<method name="clear_points">
|
|
<return type="void" />
|
|
<description>
|
|
Removes all points from the curve.
|
|
</description>
|
|
</method>
|
|
<method name="get_baked_length" qualifiers="const">
|
|
<return type="float" />
|
|
<description>
|
|
Returns the total length of the curve, based on the cached points. Given enough density (see [member bake_interval]), it should be approximate enough.
|
|
</description>
|
|
</method>
|
|
<method name="get_baked_points" qualifiers="const">
|
|
<return type="PackedVector3Array" />
|
|
<description>
|
|
Returns the cache of points as a [PackedVector3Array].
|
|
</description>
|
|
</method>
|
|
<method name="get_baked_tilts" qualifiers="const">
|
|
<return type="PackedFloat32Array" />
|
|
<description>
|
|
Returns the cache of tilts as a [PackedFloat32Array].
|
|
</description>
|
|
</method>
|
|
<method name="get_baked_up_vectors" qualifiers="const">
|
|
<return type="PackedVector3Array" />
|
|
<description>
|
|
Returns the cache of up vectors as a [PackedVector3Array].
|
|
If [member up_vector_enabled] is [code]false[/code], the cache will be empty.
|
|
</description>
|
|
</method>
|
|
<method name="get_closest_offset" qualifiers="const">
|
|
<return type="float" />
|
|
<param index="0" name="to_point" type="Vector3" />
|
|
<description>
|
|
Returns the closest offset to [param to_point]. This offset is meant to be used in [method sample_baked] or [method sample_baked_up_vector].
|
|
[param to_point] must be in this curve's local space.
|
|
</description>
|
|
</method>
|
|
<method name="get_closest_point" qualifiers="const">
|
|
<return type="Vector3" />
|
|
<param index="0" name="to_point" type="Vector3" />
|
|
<description>
|
|
Returns the closest baked point (in curve's local space) to [param to_point].
|
|
[param to_point] must be in this curve's local space.
|
|
</description>
|
|
</method>
|
|
<method name="get_point_in" qualifiers="const">
|
|
<return type="Vector3" />
|
|
<param index="0" name="idx" type="int" />
|
|
<description>
|
|
Returns the position of the control point leading to the vertex [param idx]. The returned position is relative to the vertex [param idx]. If the index is out of bounds, the function sends an error to the console, and returns [code](0, 0, 0)[/code].
|
|
</description>
|
|
</method>
|
|
<method name="get_point_out" qualifiers="const">
|
|
<return type="Vector3" />
|
|
<param index="0" name="idx" type="int" />
|
|
<description>
|
|
Returns the position of the control point leading out of the vertex [param idx]. The returned position is relative to the vertex [param idx]. If the index is out of bounds, the function sends an error to the console, and returns [code](0, 0, 0)[/code].
|
|
</description>
|
|
</method>
|
|
<method name="get_point_position" qualifiers="const">
|
|
<return type="Vector3" />
|
|
<param index="0" name="idx" type="int" />
|
|
<description>
|
|
Returns the position of the vertex [param idx]. If the index is out of bounds, the function sends an error to the console, and returns [code](0, 0, 0)[/code].
|
|
</description>
|
|
</method>
|
|
<method name="get_point_tilt" qualifiers="const">
|
|
<return type="float" />
|
|
<param index="0" name="idx" type="int" />
|
|
<description>
|
|
Returns the tilt angle in radians for the point [param idx]. If the index is out of bounds, the function sends an error to the console, and returns [code]0[/code].
|
|
</description>
|
|
</method>
|
|
<method name="remove_point">
|
|
<return type="void" />
|
|
<param index="0" name="idx" type="int" />
|
|
<description>
|
|
Deletes the point [code]idx[/code] from the curve. Sends an error to the console if [code]idx[/code] is out of bounds.
|
|
</description>
|
|
</method>
|
|
<method name="sample" qualifiers="const">
|
|
<return type="Vector3" />
|
|
<param index="0" name="idx" type="int" />
|
|
<param index="1" name="t" type="float" />
|
|
<description>
|
|
Returns the position between the vertex [param idx] and the vertex [code]idx + 1[/code], where [param t] controls if the point is the first vertex ([code]t = 0.0[/code]), the last vertex ([code]t = 1.0[/code]), or in between. Values of [param t] outside the range ([code]0.0 >= t <=1[/code]) give strange, but predictable results.
|
|
If [param idx] is out of bounds it is truncated to the first or last vertex, and [param t] is ignored. If the curve has no points, the function sends an error to the console, and returns [code](0, 0, 0)[/code].
|
|
</description>
|
|
</method>
|
|
<method name="sample_baked" qualifiers="const">
|
|
<return type="Vector3" />
|
|
<param index="0" name="offset" type="float" />
|
|
<param index="1" name="cubic" type="bool" default="false" />
|
|
<description>
|
|
Returns a point within the curve at position [param offset], where [param offset] is measured as a distance in 3D units along the curve.
|
|
To do that, it finds the two cached points where the [param offset] lies between, then interpolates the values. This interpolation is cubic if [param cubic] is set to [code]true[/code], or linear if set to [code]false[/code].
|
|
Cubic interpolation tends to follow the curves better, but linear is faster (and often, precise enough).
|
|
</description>
|
|
</method>
|
|
<method name="sample_baked_up_vector" qualifiers="const">
|
|
<return type="Vector3" />
|
|
<param index="0" name="offset" type="float" />
|
|
<param index="1" name="apply_tilt" type="bool" default="false" />
|
|
<description>
|
|
Returns an up vector within the curve at position [param offset], where [param offset] is measured as a distance in 3D units along the curve.
|
|
To do that, it finds the two cached up vectors where the [param offset] lies between, then interpolates the values. If [param apply_tilt] is [code]true[/code], an interpolated tilt is applied to the interpolated up vector.
|
|
If the curve has no up vectors, the function sends an error to the console, and returns [code](0, 1, 0)[/code].
|
|
</description>
|
|
</method>
|
|
<method name="sample_baked_with_rotation" qualifiers="const">
|
|
<return type="Transform3D" />
|
|
<param index="0" name="offset" type="float" />
|
|
<param index="1" name="cubic" type="bool" default="false" />
|
|
<param index="2" name="apply_tilt" type="bool" default="false" />
|
|
<description>
|
|
Similar with [code]interpolate_baked()[/code]. The the return value is [code]Transform3D[/code], with [code]origin[/code] as point position, [code]basis.x[/code] as sideway vector, [code]basis.y[/code] as up vector, [code]basis.z[/code] as forward vector. When the curve length is 0, there is no reasonable way to caculate the rotation, all vectors aligned with global space axes.
|
|
</description>
|
|
</method>
|
|
<method name="samplef" qualifiers="const">
|
|
<return type="Vector3" />
|
|
<param index="0" name="fofs" type="float" />
|
|
<description>
|
|
Returns the position at the vertex [param fofs]. It calls [method sample] using the integer part of [param fofs] as [code]idx[/code], and its fractional part as [code]t[/code].
|
|
</description>
|
|
</method>
|
|
<method name="set_point_in">
|
|
<return type="void" />
|
|
<param index="0" name="idx" type="int" />
|
|
<param index="1" name="position" type="Vector3" />
|
|
<description>
|
|
Sets the position of the control point leading to the vertex [param idx]. If the index is out of bounds, the function sends an error to the console. The position is relative to the vertex.
|
|
</description>
|
|
</method>
|
|
<method name="set_point_out">
|
|
<return type="void" />
|
|
<param index="0" name="idx" type="int" />
|
|
<param index="1" name="position" type="Vector3" />
|
|
<description>
|
|
Sets the position of the control point leading out of the vertex [param idx]. If the index is out of bounds, the function sends an error to the console. The position is relative to the vertex.
|
|
</description>
|
|
</method>
|
|
<method name="set_point_position">
|
|
<return type="void" />
|
|
<param index="0" name="idx" type="int" />
|
|
<param index="1" name="position" type="Vector3" />
|
|
<description>
|
|
Sets the position for the vertex [param idx]. If the index is out of bounds, the function sends an error to the console.
|
|
</description>
|
|
</method>
|
|
<method name="set_point_tilt">
|
|
<return type="void" />
|
|
<param index="0" name="idx" type="int" />
|
|
<param index="1" name="tilt" type="float" />
|
|
<description>
|
|
Sets the tilt angle in radians for the point [param idx]. If the index is out of bounds, the function sends an error to the console.
|
|
The tilt controls the rotation along the look-at axis an object traveling the path would have. In the case of a curve controlling a [PathFollow3D], this tilt is an offset over the natural tilt the [PathFollow3D] calculates.
|
|
</description>
|
|
</method>
|
|
<method name="tessellate" qualifiers="const">
|
|
<return type="PackedVector3Array" />
|
|
<param index="0" name="max_stages" type="int" default="5" />
|
|
<param index="1" name="tolerance_degrees" type="float" default="4" />
|
|
<description>
|
|
Returns a list of points along the curve, with a curvature controlled point density. That is, the curvier parts will have more points than the straighter parts.
|
|
This approximation makes straight segments between each point, then subdivides those segments until the resulting shape is similar enough.
|
|
[param max_stages] controls how many subdivisions a curve segment may face before it is considered approximate enough. Each subdivision splits the segment in half, so the default 5 stages may mean up to 32 subdivisions per curve segment. Increase with care!
|
|
[param tolerance_degrees] controls how many degrees the midpoint of a segment may deviate from the real curve, before the segment has to be subdivided.
|
|
</description>
|
|
</method>
|
|
</methods>
|
|
<members>
|
|
<member name="bake_interval" type="float" setter="set_bake_interval" getter="get_bake_interval" default="0.2">
|
|
The distance in meters between two adjacent cached points. Changing it forces the cache to be recomputed the next time the [method get_baked_points] or [method get_baked_length] function is called. The smaller the distance, the more points in the cache and the more memory it will consume, so use with care.
|
|
</member>
|
|
<member name="point_count" type="int" setter="set_point_count" getter="get_point_count" default="0">
|
|
The number of points describing the curve.
|
|
</member>
|
|
<member name="up_vector_enabled" type="bool" setter="set_up_vector_enabled" getter="is_up_vector_enabled" default="true">
|
|
If [code]true[/code], the curve will bake up vectors used for orientation. This is used when [member PathFollow3D.rotation_mode] is set to [constant PathFollow3D.ROTATION_ORIENTED]. Changing it forces the cache to be recomputed.
|
|
</member>
|
|
</members>
|
|
</class>
|