From 408de3b091f49b9be70a4402a41233f478d32327 Mon Sep 17 00:00:00 2001 From: kleonc <9283098+kleonc@users.noreply.github.com> Date: Tue, 17 Oct 2023 19:40:54 +0200 Subject: [PATCH] Clarify C# docs for operators performing xform_inv --- doc/classes/Transform2D.xml | 10 +++--- doc/classes/Transform3D.xml | 4 +-- doc/classes/Vector3.xml | 2 +- .../glue/GodotSharp/GodotSharp/Core/Basis.cs | 9 ++--- .../GodotSharp/GodotSharp/Core/Projection.cs | 3 +- .../GodotSharp/GodotSharp/Core/Quaternion.cs | 1 + .../GodotSharp/GodotSharp/Core/Transform2D.cs | 34 +++++++++++++------ .../GodotSharp/GodotSharp/Core/Transform3D.cs | 29 +++++++++++----- 8 files changed, 60 insertions(+), 32 deletions(-) diff --git a/doc/classes/Transform2D.xml b/doc/classes/Transform2D.xml index 1611af4226f3..aee70f6b5986 100644 --- a/doc/classes/Transform2D.xml +++ b/doc/classes/Transform2D.xml @@ -67,7 +67,7 @@ Returns a vector transformed (multiplied) by the basis matrix. - This method does not account for translation (the origin vector). + This method does not account for translation (the [member origin] vector). @@ -75,9 +75,9 @@ Returns a vector transformed (multiplied) by the inverse basis matrix, under the assumption that the basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). - This method does not account for translation (the origin vector). + This method does not account for translation (the [member origin] vector). [code]transform.basis_xform_inv(vector)[/code] is equivalent to [code]transform.inverse().basis_xform(vector)[/code]. See [method inverse]. - For non-orthonormal transforms (e.g. with scaling) use [code]transform.affine_inverse().basis_xform(vector)[/code] instead. See [method affine_inverse]. + For non-orthonormal transforms (e.g. with scaling) [code]transform.affine_inverse().basis_xform(vector)[/code] can be used instead. See [method affine_inverse]. @@ -276,14 +276,14 @@ - This operator multiplies all components of the [Transform2D], including the origin vector, which scales it uniformly. + This operator multiplies all components of the [Transform2D], including the [member origin] vector, which scales it uniformly. - This operator multiplies all components of the [Transform2D], including the origin vector, which scales it uniformly. + This operator multiplies all components of the [Transform2D], including the [member origin] vector, which scales it uniformly. diff --git a/doc/classes/Transform3D.xml b/doc/classes/Transform3D.xml index c0331855598e..85da629d7051 100644 --- a/doc/classes/Transform3D.xml +++ b/doc/classes/Transform3D.xml @@ -235,14 +235,14 @@ - This operator multiplies all components of the [Transform3D], including the origin vector, which scales it uniformly. + This operator multiplies all components of the [Transform3D], including the [member origin] vector, which scales it uniformly. - This operator multiplies all components of the [Transform3D], including the origin vector, which scales it uniformly. + This operator multiplies all components of the [Transform3D], including the [member origin] vector, which scales it uniformly. diff --git a/doc/classes/Vector3.xml b/doc/classes/Vector3.xml index 77c73914106a..83a8c6af7399 100644 --- a/doc/classes/Vector3.xml +++ b/doc/classes/Vector3.xml @@ -444,7 +444,7 @@ Inversely transforms (multiplies) the [Vector3] by the given [Basis] matrix, under the assumption that the basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). [code]vector * basis[/code] is equivalent to [code]basis.transposed() * vector[/code]. See [method Basis.transposed]. - For transforming by inverse of a non-orthonormal basis [code]basis.inverse() * vector[/code] can be used instead. See [method Basis.inverse]. + For transforming by inverse of a non-orthonormal basis (e.g. with scaling) [code]basis.inverse() * vector[/code] can be used instead. See [method Basis.inverse]. diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Basis.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Basis.cs index a7712db73795..3c1027c954cc 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Basis.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Basis.cs @@ -1037,10 +1037,11 @@ namespace Godot } /// - /// Returns a Vector3 transformed (multiplied) by the transposed basis matrix. - /// - /// Note: This results in a multiplication by the inverse of the - /// basis matrix only if it represents a rotation-reflection. + /// Returns a Vector3 transformed (multiplied) by the inverse basis matrix, + /// under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection + /// is fine, scaling/skew is not). + /// vector * basis is equivalent to basis.Transposed() * vector. See . + /// For transforming by inverse of a non-orthonormal basis (e.g. with scaling) basis.Inverse() * vector can be used instead. See . /// /// A Vector3 to inversely transform. /// The basis matrix transformation to apply. diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Projection.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Projection.cs index a80d202ef27d..627e7c2e6423 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Projection.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Projection.cs @@ -905,7 +905,8 @@ namespace Godot } /// - /// Returns a Vector4 transformed (multiplied) by the inverse projection. + /// Returns a Vector4 transformed (multiplied) by the transpose of the projection. + /// For transforming by inverse of a projection [code]projection.Inverse() * vector[/code] can be used instead. See . /// /// The projection to apply. /// A Vector4 to transform. diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Quaternion.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Quaternion.cs index 39e1b7e4b8f5..3d4591358680 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Quaternion.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Quaternion.cs @@ -644,6 +644,7 @@ namespace Godot /// /// Returns a Vector3 rotated (multiplied) by the inverse quaternion. + /// vector * quaternion is equivalent to quaternion.Inverse() * vector. See . /// /// A Vector3 to inversely rotate. /// The quaternion to rotate by. diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform2D.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform2D.cs index 0e3e54a0c28b..386f5874649a 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform2D.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform2D.cs @@ -126,7 +126,7 @@ namespace Godot /// /// Returns the inverse of the transform, under the assumption that - /// the transformation is composed of rotation, scaling, and translation. + /// the basis is invertible (must have non-zero determinant). /// /// /// The inverse transformation matrix. @@ -180,11 +180,12 @@ namespace Godot } /// - /// Returns a vector transformed (multiplied) by the inverse basis matrix. + /// Returns a vector transformed (multiplied) by the inverse basis matrix, + /// under the assumption that the basis is orthonormal (i.e. rotation/reflection + /// is fine, scaling/skew is not). /// This method does not account for translation (the vector). - /// - /// Note: This results in a multiplication by the inverse of the - /// basis matrix only if it represents a rotation-reflection. + /// transform.BasisXformInv(vector) is equivalent to transform.Inverse().BasisXform(vector). See . + /// For non-orthonormal transforms (e.g. with scaling) transform.AffineInverse().BasisXform(vector) can be used instead. See . /// /// /// A vector to inversely transform. @@ -213,8 +214,9 @@ namespace Godot /// /// Returns the inverse of the transform, under the assumption that - /// the transformation is composed of rotation and translation - /// (no scaling, use for transforms with scaling). + /// the transformation basis is orthonormal (i.e. rotation/reflection + /// is fine, scaling/skew is not). Use for + /// non-orthonormal transforms (e.g. with scaling). /// /// The inverse matrix. public readonly Transform2D Inverse() @@ -480,7 +482,11 @@ namespace Godot } /// - /// Returns a Vector2 transformed (multiplied) by the inverse transformation matrix. + /// Returns a Vector2 transformed (multiplied) by the inverse transformation matrix, + /// under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection + /// is fine, scaling/skew is not). + /// vector * transform is equivalent to transform.Inverse() * vector. See . + /// For transforming by inverse of an affine transformation (e.g. with scaling) transform.AffineInverse() * vector can be used instead. See . /// /// A Vector2 to inversely transform. /// The transformation to apply. @@ -507,7 +513,11 @@ namespace Godot } /// - /// Returns a Rect2 transformed (multiplied) by the inverse transformation matrix. + /// Returns a Rect2 transformed (multiplied) by the inverse transformation matrix, + /// under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection + /// is fine, scaling/skew is not). + /// rect * transform is equivalent to transform.Inverse() * rect. See . + /// For transforming by inverse of an affine transformation (e.g. with scaling) transform.AffineInverse() * rect can be used instead. See . /// /// A Rect2 to inversely transform. /// The transformation to apply. @@ -541,7 +551,11 @@ namespace Godot } /// - /// Returns a copy of the given Vector2[] transformed (multiplied) by the inverse transformation matrix. + /// Returns a copy of the given Vector2[] transformed (multiplied) by the inverse transformation matrix, + /// under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection + /// is fine, scaling/skew is not). + /// array * transform is equivalent to transform.Inverse() * array. See . + /// For transforming by inverse of an affine transformation (e.g. with scaling) transform.AffineInverse() * array can be used instead. See . /// /// A Vector2[] to inversely transform. /// The transformation to apply. diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform3D.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform3D.cs index 7b27071df122..2d09259dcb3a 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform3D.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform3D.cs @@ -105,7 +105,7 @@ namespace Godot /// /// Returns the inverse of the transform, under the assumption that - /// the transformation is composed of rotation, scaling, and translation. + /// the basis is invertible (must have non-zero determinant). /// /// /// The inverse transformation matrix. @@ -144,8 +144,9 @@ namespace Godot /// /// Returns the inverse of the transform, under the assumption that - /// the transformation is composed of rotation and translation - /// (no scaling, use for transforms with scaling). + /// the transformation basis is orthonormal (i.e. rotation/reflection + /// is fine, scaling/skew is not). Use for + /// non-orthonormal transforms (e.g. with scaling). /// /// The inverse matrix. public readonly Transform3D Inverse() @@ -426,10 +427,11 @@ namespace Godot } /// - /// Returns a Vector3 transformed (multiplied) by the transposed transformation matrix. - /// - /// Note: This results in a multiplication by the inverse of the - /// transformation matrix only if it represents a rotation-reflection. + /// Returns a Vector3 transformed (multiplied) by the inverse transformation matrix, + /// under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection + /// is fine, scaling/skew is not). + /// vector * transform is equivalent to transform.Inverse() * vector. See . + /// For transforming by inverse of an affine transformation (e.g. with scaling) transform.AffineInverse() * vector can be used instead. See . /// /// A Vector3 to inversely transform. /// The transformation to apply. @@ -482,7 +484,11 @@ namespace Godot } /// - /// Returns an AABB transformed (multiplied) by the inverse transformation matrix. + /// Returns an AABB transformed (multiplied) by the inverse transformation matrix, + /// under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection + /// is fine, scaling/skew is not). + /// aabb * transform is equivalent to transform.Inverse() * aabb. See . + /// For transforming by inverse of an affine transformation (e.g. with scaling) transform.AffineInverse() * aabb can be used instead. See . /// /// An AABB to inversely transform. /// The transformation to apply. @@ -523,6 +529,7 @@ namespace Godot /// /// Returns a Plane transformed (multiplied) by the inverse transformation matrix. + /// plane * transform is equivalent to transform.AffineInverse() * plane. See . /// /// A Plane to inversely transform. /// The transformation to apply. @@ -568,7 +575,11 @@ namespace Godot } /// - /// Returns a copy of the given Vector3[] transformed (multiplied) by the inverse transformation matrix. + /// Returns a copy of the given Vector3[] transformed (multiplied) by the inverse transformation matrix, + /// under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection + /// is fine, scaling/skew is not). + /// array * transform is equivalent to transform.Inverse() * array. See . + /// For transforming by inverse of an affine transformation (e.g. with scaling) transform.AffineInverse() * array can be used instead. See . /// /// A Vector3[] to inversely transform. /// The transformation to apply.