From bd7ba0b664fa98381db9ef8edb69ba211213d595 Mon Sep 17 00:00:00 2001
From: Ferenc Arn <tagcup@yahoo.com>
Date: Tue, 18 Oct 2016 15:50:21 -0500
Subject: Use right handed coordinate system for rotation matrices and
 quaternions. Also fixes Euler angles (XYZ convention, which is used as
 default by Blender).

Furthermore, functions which expect a rotation matrix will now give an error simply, rather than trying to orthonormalize such matrices. The documentation for such functions has be updated accordingly.

This commit breaks code using 3D rotations, and is a part of the breaking changes in 2.1 -> 3.0 transition. The code affected within Godot code base is fixed in this commit.
---
 doc/base/classes.xml | 21 ++++++++++-----------
 1 file changed, 10 insertions(+), 11 deletions(-)

(limited to 'doc')

diff --git a/doc/base/classes.xml b/doc/base/classes.xml
index b49c23f117..4be1666e59 100644
--- a/doc/base/classes.xml
+++ b/doc/base/classes.xml
@@ -20714,7 +20714,7 @@
 			<argument index="1" name="phi" type="float">
 			</argument>
 			<description>
-				Create a matrix from an axis vector and an angle.
+				Create a matrix which rotates around the given axis by the specified angle.
 			</description>
 		</method>
 		<method name="Matrix3">
@@ -20741,7 +20741,7 @@
 			<return type="Vector3">
 			</return>
 			<description>
-				Return euler angles from the matrix.
+				Return euler angles (in the XYZ convention: first Z, then Y, and X last) from the matrix. Returned vector contains the rotation angles in the format (third,second,first).
 			</description>
 		</method>
 		<method name="get_orthogonal_index">
@@ -20767,7 +20767,7 @@
 			<return type="Matrix3">
 			</return>
 			<description>
-				Return the orthonormalized version of the matrix (useful to call from time to time to avoid rounding error).
+				Return the orthonormalized version of the matrix (useful to call from time to time to avoid rounding error for orthogonal matrices). This performs a Gram-Schmidt orthonormalization on the basis of the matrix.
 			</description>
 		</method>
 		<method name="rotated">
@@ -20777,10 +20777,7 @@
 			</argument>
 			<argument index="1" name="phi" type="float">
 			</argument>
-			<description>
-				Return the rotated version of the matrix, by a given axis and angle.
-			</description>
-		</method>
+                </method>
 		<method name="scaled">
 			<return type="Matrix3">
 			</return>
@@ -31485,7 +31482,7 @@
 		Quaternion.
 	</brief_description>
 	<description>
-		Quaternion is a 4 dimensional vector that is used to represent a rotation. It mainly exists to perform SLERP (spherical-linear interpolation) between to rotations obtained by a Matrix3 cheaply. Adding quaternions also cheaply adds the rotations, however quaternions need to be often normalized, or else they suffer from precision issues.
+		Quaternion is a 4 dimensional vector that is used to represent a rotation. It mainly exists to perform SLERP (spherical-linear interpolation) between to rotations obtained by a Matrix3 cheaply. Multiplying quaternions also cheaply reproduces rotation sequences, however quaternions need to be often normalized, or else they suffer from precision issues.
 	</description>
 	<methods>
 		<method name="Quat">
@@ -31510,6 +31507,7 @@
 			<argument index="1" name="angle" type="float">
 			</argument>
 			<description>
+                Returns a quaternion that will rotate around the given axis by the specified angle.
 			</description>
 		</method>
 		<method name="Quat">
@@ -31518,6 +31516,7 @@
 			<argument index="0" name="from" type="Matrix3">
 			</argument>
 			<description>
+				Returns the rotation matrix corresponding to the given quaternion.
 			</description>
 		</method>
 		<method name="cubic_slerp">
@@ -31540,14 +31539,14 @@
 			<argument index="0" name="b" type="Quat">
 			</argument>
 			<description>
-				Returns the dot product between two quaternions.
+				Returns the dot product of two quaternions.
 			</description>
 		</method>
 		<method name="inverse">
 			<return type="Quat">
 			</return>
 			<description>
-				Returns the inverse of the quaternion (applies to the inverse rotation too).
+				Returns the inverse of the quaternion.
 			</description>
 		</method>
 		<method name="length">
@@ -43135,7 +43134,7 @@
 			<argument index="1" name="phi" type="float">
 			</argument>
 			<description>
-				Rotate the transform locally.
+				Rotate the transform locally. This introduces an additional pre-rotation to the transform, changing the basis to basis * Matrix3(axis, phi).
 			</description>
 		</method>
 		<method name="scaled">
-- 
cgit v1.2.3