183 lines
10 KiB
XML
183 lines
10 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<class name="Curve2D" inherits="Resource" version="4.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
|
|
<brief_description>
|
|
Describes a Bézier curve in 2D space.
|
|
</brief_description>
|
|
<description>
|
|
This class describes a Bézier curve in 2D space. It is mainly used to give a shape to a [Path2D], 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="Vector2" />
|
|
<param index="1" name="in" type="Vector2" default="Vector2(0, 0)" />
|
|
<param index="2" name="out" type="Vector2" default="Vector2(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="PackedVector2Array" />
|
|
<description>
|
|
Returns the cache of points as a [PackedVector2Array].
|
|
</description>
|
|
</method>
|
|
<method name="get_closest_offset" qualifiers="const">
|
|
<return type="float" />
|
|
<param index="0" name="to_point" type="Vector2" />
|
|
<description>
|
|
Returns the closest offset to [param to_point]. This offset is meant to be used in [method sample_baked].
|
|
[param to_point] must be in this curve's local space.
|
|
</description>
|
|
</method>
|
|
<method name="get_closest_point" qualifiers="const">
|
|
<return type="Vector2" />
|
|
<param index="0" name="to_point" type="Vector2" />
|
|
<description>
|
|
Returns the closest point on baked segments (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="Vector2" />
|
|
<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)[/code].
|
|
</description>
|
|
</method>
|
|
<method name="get_point_out" qualifiers="const">
|
|
<return type="Vector2" />
|
|
<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)[/code].
|
|
</description>
|
|
</method>
|
|
<method name="get_point_position" qualifiers="const">
|
|
<return type="Vector2" />
|
|
<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)[/code].
|
|
</description>
|
|
</method>
|
|
<method name="remove_point">
|
|
<return type="void" />
|
|
<param index="0" name="idx" type="int" />
|
|
<description>
|
|
Deletes the point [param idx] from the curve. Sends an error to the console if [param idx] is out of bounds.
|
|
</description>
|
|
</method>
|
|
<method name="sample" qualifiers="const">
|
|
<return type="Vector2" />
|
|
<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)[/code].
|
|
</description>
|
|
</method>
|
|
<method name="sample_baked" qualifiers="const">
|
|
<return type="Vector2" />
|
|
<param index="0" name="offset" type="float" default="0.0" />
|
|
<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 pixel distance 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_with_rotation" qualifiers="const">
|
|
<return type="Transform2D" />
|
|
<param index="0" name="offset" type="float" default="0.0" />
|
|
<param index="1" name="cubic" type="bool" default="false" />
|
|
<description>
|
|
Similar to [method sample_baked], but returns [Transform2D] that includes a rotation along the curve, with [member Transform2D.origin] as the point position, [member Transform2D.x] as the sideways vector, and [member Transform2D.y] as the forward vector. Returns an empty transform if the length of the curve is [code]0[/code].
|
|
[codeblock]
|
|
var baked = curve.sample_baked_with_rotation(offset)
|
|
# This will rotate and position the node with the up direction pointing along the curve.
|
|
position = baked.get_origin()
|
|
rotation = baked.get_rotation()
|
|
# Alternatively, not preserving scale.
|
|
transform = baked * Transform2D.FLIP_Y
|
|
# To match the rotation of PathFollow2D, not preserving scale.
|
|
transform = Transform2D(baked.y, baked.x, baked.origin)
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="samplef" qualifiers="const">
|
|
<return type="Vector2" />
|
|
<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="Vector2" />
|
|
<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="Vector2" />
|
|
<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="Vector2" />
|
|
<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="tessellate" qualifiers="const">
|
|
<return type="PackedVector2Array" />
|
|
<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>
|
|
<method name="tessellate_even_length" qualifiers="const">
|
|
<return type="PackedVector2Array" />
|
|
<param index="0" name="max_stages" type="int" default="5" />
|
|
<param index="1" name="tolerance_length" type="float" default="20.0" />
|
|
<description>
|
|
Returns a list of points along the curve, with almost uniform density. [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_length] controls the maximal distance between two neighboring points, 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="5.0">
|
|
The distance in pixels 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>
|
|
</members>
|
|
</class>
|