Merge pull request #18804 from tagcup/vec_slerp

Add SLERP to Vector{2,3}, optimize Quat's Vector3 rotation.

4 files changed, 76 insertions, 7 deletions

diff --git a/doc/classes/Basis.xml b/doc/classes/Basis.xml
index 554ed99964..b9dc763820 100644
--- a/doc/classes/Basis.xml
+++ b/doc/classes/Basis.xml
@@ -4,11 +4,12 @@
 		3x3 matrix datatype.
 	</brief_description>
 	<description>
-		3x3 matrix used for 3D rotation and scale. Contains 3 vector fields x,y and z as its columns, which can be interpreted as the local basis vectors of a transformation. Can also be accessed as array of 3D vectors. These vectors are orthogonal to each other, but are not necessarily normalized. Almost always used as orthogonal basis for a [Transform].
+		3x3 matrix used for 3D rotation and scale. Contains 3 vector fields x,y and z as its columns, which can be interpreted as the local basis vectors of a transformation. Can also be accessed as array of 3D vectors. These vectors are orthogonal to each other, but are not necessarily normalized (due to scaling). Almost always used as orthogonal basis for a [Transform].
 		For such use, it is composed of a scaling and a rotation matrix, in that order (M = R.S).
 	</description>
 	<tutorials>
 		http://docs.godotengine.org/en/latest/tutorials/3d/using_transforms.html
+		http://docs.godotengine.org/en/latest/tutorials/math/rotations.html
 	</tutorials>
 	<demos>
 	</demos>
@@ -105,7 +106,7 @@
 			<argument index="1" name="phi" type="float">
 			</argument>
 			<description>
-				Introduce an additional rotation around the given axis by phi (radians). Only relevant when the matrix is being used as a part of [Transform]. The axis must be a normalized vector.
+				Introduce an additional rotation around the given axis by phi (radians). The axis must be a normalized vector.
 			</description>
 		</method>
 		<method name="scaled">
@@ -114,7 +115,18 @@
 			<argument index="0" name="scale" type="Vector3">
 			</argument>
 			<description>
-				Introduce an additional scaling specified by the given 3D scaling factor. Only relevant when the matrix is being used as a part of [Transform].
+				Introduce an additional scaling specified by the given 3D scaling factor.
+			</description>
+		</method>
+		<method name="slerp">
+			<return type="Basis">
+			</return>
+			<argument index="0" name="b" type="Basis">
+			</argument>
+			<argument index="1" name="t" type="float">
+			</argument>
+			<description>
+				Assuming that the matrix is a proper rotation matrix, slerp performs a spherical-linear interpolation with another rotation matrix.
 			</description>
 		</method>
 		<method name="tdotx">
diff --git a/doc/classes/Quat.xml b/doc/classes/Quat.xml
index 33f2b9758b..4121790881 100644
--- a/doc/classes/Quat.xml
+++ b/doc/classes/Quat.xml
@@ -4,13 +4,14 @@
 		Quaternion.
 	</brief_description>
 	<description>
-		A 4-dimensional vector representing a rotation.
-		The vector represents a 4 dimensional complex number where multiplication of the basis elements is not commutative (multiplying i with j gives a different result than multiplying j with i).
-		Multiplying quaternions reproduces rotation sequences. However quaternions need to be often renormalized, or else they suffer from precision issues.
-		It can be used to perform SLERP (spherical-linear interpolation) between two rotations.
+		A unit quaternion used for representing 3D rotations.
+		It is similar to [Basis], which implements matrix representation of rotations, and can be parametrized using both an axis-angle pair or Euler angles. But due to its compactness and the way it is stored in memory, certain operations (obtaining axis-angle and performing SLERP, in particular) are more efficient and robust against floating point errors.
+
+		Quaternions need to be (re)normalized.
 	</description>
 	<tutorials>
 		http://docs.godotengine.org/en/latest/tutorials/3d/using_transforms.html#interpolating-with-quaternions
+		http://docs.godotengine.org/en/latest/tutorials/math/rotations.html
 	</tutorials>
 	<demos>
 	</demos>
@@ -44,6 +45,15 @@
 		<method name="Quat">
 			<return type="Quat">
 			</return>
+			<argument index="0" name="euler" type="Vector3">
+			</argument>
+			<description>
+				Returns a quaternion that will perform a rotation specified by Euler angles (in the YXZ convention: first Z, then X, and Y last), given in the vector format as (X-angle, Y-angle, Z-angle).
+			</description>
+		</method>
+		<method name="Quat">
+			<return type="Quat">
+			</return>
 			<argument index="0" name="from" type="Basis">
 			</argument>
 			<description>
@@ -74,6 +84,13 @@
 				Returns the dot product of two quaternions.
 			</description>
 		</method>
+		<method name="get_euler">
+			<return type="Vector3">
+			</return>
+			<description>
+				Return Euler angles (in the YXZ convention: first Z, then X, and Y last) corresponding to the rotation represented by the unit quaternion. Returned vector contains the rotation angles in the format (X-angle, Y-angle, Z-angle).
+			</description>
+		</method>
 		<method name="inverse">
 			<return type="Quat">
 			</return>
@@ -109,6 +126,22 @@
 				Returns a copy of the quaternion, normalized to unit length.
 			</description>
 		</method>
+		<method name="set_axis_angle">
+			<argument index="0" name="axis" type="Vector3">
+			</argument>
+			<argument index="1" name="phi" type="float">
+			</argument>
+			<description>
+				Set the quaternion to a rotation which rotates around axis by the specified angle, in radians. The axis must be a normalized vector.
+			</description>
+		</method>
+		<method name="set_euler">
+			<argument index="0" name="euler" type="Vector3">
+			</argument>
+			<description>
+				Set the quaternion to a rotation specified by Euler angles (in the YXZ convention: first Z, then X, and Y last), given in the vector format as (X-angle, Y-angle, Z-angle).
+			</description>
+		</method>
 		<method name="slerp">
 			<return type="Quat">
 			</return>
diff --git a/doc/classes/Vector2.xml b/doc/classes/Vector2.xml
index ec92dcf900..e3fbaff62d 100644
--- a/doc/classes/Vector2.xml
+++ b/doc/classes/Vector2.xml
@@ -208,6 +208,18 @@
 			<description>
 			</description>
 		</method>
+		<method name="slerp">
+			<return type="Vector2">
+			</return>
+			<argument index="0" name="b" type="Vector2">
+			</argument>
+			<argument index="1" name="t" type="float">
+			</argument>
+			<description>
+				Returns the result of SLERP between this vector and "b", by amount "t". "t" should be a float of 0.0-1.0, a percentage of how far along the interpolation is.
+				Both vectors need to be normalized.
+			</description>
+		</method>
 		<method name="slide">
 			<return type="Vector2">
 			</return>
diff --git a/doc/classes/Vector3.xml b/doc/classes/Vector3.xml
index a5fc62b6f0..84c16c9fc5 100644
--- a/doc/classes/Vector3.xml
+++ b/doc/classes/Vector3.xml
@@ -210,6 +210,18 @@
 			<description>
 			</description>
 		</method>
+		<method name="slerp">
+			<return type="Vector3">
+			</return>
+			<argument index="0" name="b" type="Vector3">
+			</argument>
+			<argument index="1" name="t" type="float">
+			</argument>
+			<description>
+				Returns the result of SLERP between this vector and "b", by amount "t". "t" should be a float of 0.0-1.0, a percentage of how far along the interpolation is.
+				Both vectors need to be normalized.
+			</description>
+		</method>
 		<method name="slide">
 			<return type="Vector3">
 			</return>