classref: Sync with current master branch (893bbdf)

classes/class_transform3d.rst

@@ -161,9 +161,31 @@ Constants
 
 **IDENTITY** = ``Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)`` :ref:`🔗<class_Transform3D_constant_IDENTITY>`
 
-A transform with no translation, no rotation, and its scale being ``1``. Its :ref:`basis<class_Transform3D_property_basis>` is equal to :ref:`Basis.IDENTITY<class_Basis_constant_IDENTITY>`.
+The identity **Transform3D**. This is a transform with no translation, no rotation, and a scale of :ref:`Vector3.ONE<class_Vector3_constant_ONE>`. Its :ref:`basis<class_Transform3D_property_basis>` is equal to :ref:`Basis.IDENTITY<class_Basis_constant_IDENTITY>`. This also means that:
 
-When multiplied by another :ref:`Variant<class_Variant>` such as :ref:`AABB<class_AABB>` or another **Transform3D**, no transformation occurs.
+- Its :ref:`Basis.x<class_Basis_property_x>` points right (:ref:`Vector3.RIGHT<class_Vector3_constant_RIGHT>`);
+
+- Its :ref:`Basis.y<class_Basis_property_y>` points up (:ref:`Vector3.UP<class_Vector3_constant_UP>`);
+
+- Its :ref:`Basis.z<class_Basis_property_z>` points back (:ref:`Vector3.BACK<class_Vector3_constant_BACK>`).
+
+::
+
+    var transform = Transform3D.IDENTITY
+    var basis = transform.basis
+    print("| X | Y | Z | Origin")
+    print("| %.f | %.f | %.f | %.f" % [basis.x.x, basis.y.x, basis.z.x, transform.origin.x])
+    print("| %.f | %.f | %.f | %.f" % [basis.x.y, basis.y.y, basis.z.y, transform.origin.y])
+    print("| %.f | %.f | %.f | %.f" % [basis.x.z, basis.y.z, basis.z.z, transform.origin.z])
+    # Prints:
+    # | X | Y | Z | Origin
+    # | 1 | 0 | 0 | 0
+    # | 0 | 1 | 0 | 0
+    # | 0 | 0 | 1 | 0
+
+If a :ref:`Vector3<class_Vector3>`, an :ref:`AABB<class_AABB>`, a :ref:`Plane<class_Plane>`, a :ref:`PackedVector3Array<class_PackedVector3Array>`, or another **Transform3D** is transformed (multiplied) by this constant, no transformation occurs.
+
+\ **Note:** In GDScript, this constant is equivalent to creating a :ref:`Transform3D<class_Transform3D_constructor_Transform3D>` without any arguments. It can be used to make your code clearer, and for consistency with C#.
 
 .. _class_Transform3D_constant_FLIP_X:
 
@@ -233,7 +255,7 @@ Constructor Descriptions
 
 :ref:`Transform3D<class_Transform3D>` **Transform3D**\ (\ ) :ref:`🔗<class_Transform3D_constructor_Transform3D>`
 
-Constructs a **Transform3D** identical to the :ref:`IDENTITY<class_Transform3D_constant_IDENTITY>`.
+Constructs a **Transform3D** identical to :ref:`IDENTITY<class_Transform3D_constant_IDENTITY>`.
 
 \ **Note:** In C#, this constructs a **Transform3D** with its :ref:`origin<class_Transform3D_property_origin>` and the components of its :ref:`basis<class_Transform3D_property_basis>` set to :ref:`Vector3.ZERO<class_Vector3_constant_ZERO>`.
 
@@ -296,7 +318,7 @@ Method Descriptions
 
 Returns the inverted version of this transform. Unlike :ref:`inverse<class_Transform3D_method_inverse>`, this method works with almost any :ref:`basis<class_Transform3D_property_basis>`, including non-uniform ones, but is slower. See also :ref:`Basis.inverse<class_Basis_method_inverse>`.
 
-\ **Note:** For this method to return correctly, the transform's :ref:`basis<class_Transform3D_property_basis>` needs to have a determinant that is not exactly ``0`` (see :ref:`Basis.determinant<class_Basis_method_determinant>`).
+\ **Note:** For this method to return correctly, the transform's :ref:`basis<class_Transform3D_property_basis>` needs to have a determinant that is not exactly ``0.0`` (see :ref:`Basis.determinant<class_Basis_method_determinant>`).
 
 .. rst-class:: classref-item-separator
 
@@ -322,9 +344,9 @@ The ``weight`` should be between ``0.0`` and ``1.0`` (inclusive). Values outside
 
 :ref:`Transform3D<class_Transform3D>` **inverse**\ (\ ) |const| :ref:`🔗<class_Transform3D_method_inverse>`
 
-Returns the inverted version of this transform. See also :ref:`Basis.inverse<class_Basis_method_inverse>`.
+Returns the `inverted version of this transform <https://en.wikipedia.org/wiki/Invertible_matrix>`__. See also :ref:`Basis.inverse<class_Basis_method_inverse>`.
 
-\ **Note:** For this method to return correctly, the transform's :ref:`basis<class_Transform3D_property_basis>` needs to be *orthonormal* (see :ref:`Basis.orthonormalized<class_Basis_method_orthonormalized>`). That means, the basis should only represent a rotation. If it does not, use :ref:`affine_inverse<class_Transform3D_method_affine_inverse>` instead.
+\ **Note:** For this method to return correctly, the transform's :ref:`basis<class_Transform3D_property_basis>` needs to be *orthonormal* (see :ref:`orthonormalized<class_Transform3D_method_orthonormalized>`). That means the basis should only represent a rotation. If it does not, use :ref:`affine_inverse<class_Transform3D_method_affine_inverse>` instead.
 
 .. rst-class:: classref-item-separator
 
@@ -376,7 +398,7 @@ If ``use_model_front`` is ``true``, the +Z axis (asset front) is treated as forw
 
 :ref:`Transform3D<class_Transform3D>` **orthonormalized**\ (\ ) |const| :ref:`🔗<class_Transform3D_method_orthonormalized>`
 
-Returns a copy of this transform with its :ref:`basis<class_Transform3D_property_basis>` orthonormalized. An orthonormal basis is both *orthogonal* (the axes are perpendicular to each other) and *normalized* (the axes have a length of ``1``), which also means it can only represent rotation. See also :ref:`Basis.orthonormalized<class_Basis_method_orthonormalized>`.
+Returns a copy of this transform with its :ref:`basis<class_Transform3D_property_basis>` orthonormalized. An orthonormal basis is both *orthogonal* (the axes are perpendicular to each other) and *normalized* (the axes have a length of ``1.0``), which also means it can only represent a rotation. See also :ref:`Basis.orthonormalized<class_Basis_method_orthonormalized>`.
 
 .. rst-class:: classref-item-separator
 
@@ -390,7 +412,7 @@ Returns a copy of this transform with its :ref:`basis<class_Transform3D_property
 
 Returns a copy of this transform rotated around the given ``axis`` by the given ``angle`` (in radians).
 
-The ``axis`` must be a normalized vector.
+The ``axis`` must be a normalized vector (see :ref:`Vector3.normalized<class_Vector3_method_normalized>`). If ``angle`` is positive, the basis is rotated counter-clockwise around the axis.
 
 This method is an optimized version of multiplying the given transform ``X`` with a corresponding rotation transform ``R`` from the left, i.e., ``R * X``.