From 5ec0a8df5e8a0bd31e064165cb87ce68f045f2c2 Mon Sep 17 00:00:00 2001 From: Aaron Franke Date: Wed, 3 Nov 2021 23:18:51 -0500 Subject: [PATCH] [3.x] Add documentation to operators for math types --- .../glue/GodotSharp/GodotSharp/Core/AABB.cs | 33 +++- .../glue/GodotSharp/GodotSharp/Core/Basis.cs | 41 ++++- .../glue/GodotSharp/GodotSharp/Core/Color.cs | 102 ++++++++++- .../glue/GodotSharp/GodotSharp/Core/Colors.cs | 2 + .../glue/GodotSharp/GodotSharp/Core/Plane.cs | 31 +++- .../glue/GodotSharp/GodotSharp/Core/Quat.cs | 88 ++++++++- .../glue/GodotSharp/GodotSharp/Core/Rect2.cs | 22 ++- .../GodotSharp/GodotSharp/Core/Transform.cs | 39 +++- .../GodotSharp/GodotSharp/Core/Transform2D.cs | 39 +++- .../GodotSharp/GodotSharp/Core/Vector2.cs | 171 +++++++++++++++++- .../GodotSharp/GodotSharp/Core/Vector3.cs | 167 ++++++++++++++++- 11 files changed, 689 insertions(+), 46 deletions(-) diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/AABB.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/AABB.cs index 1a286ae1448..ee4dcc09712 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/AABB.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/AABB.cs @@ -654,21 +654,40 @@ namespace Godot _size = new Vector3(width, height, depth); } + /// + /// Returns if the AABBs are exactly equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left AABB. + /// The right AABB. + /// Whether or not the AABBs are exactly equal. public static bool operator ==(AABB left, AABB right) { return left.Equals(right); } + /// + /// Returns if the AABBs are not equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left AABB. + /// The right AABB. + /// Whether or not the AABBs are not equal. public static bool operator !=(AABB left, AABB right) { return !left.Equals(right); } /// - /// Returns if this AABB and are equal. + /// Returns if the AABB is exactly equal + /// to the given object (). + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. /// - /// The other object to compare. - /// Whether or not the AABB structure and the other object are equal. + /// The object to compare with. + /// Whether or not the AABB and the object are equal. public override bool Equals(object obj) { if (obj is AABB) @@ -680,10 +699,12 @@ namespace Godot } /// - /// Returns if this AABB and are equal + /// Returns if the AABBs are exactly equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. /// - /// The other AABB to compare. - /// Whether or not the AABBs are equal. + /// The other AABB. + /// Whether or not the AABBs are exactly equal. public bool Equals(AABB other) { return _position == other._position && _size == other._size; diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Basis.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Basis.cs index c3514844f2e..eaa982df228 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Basis.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Basis.cs @@ -860,6 +860,14 @@ namespace Godot Row2 = new Vector3(xz, yz, zz); } + /// + /// Composes these two basis matrices by multiplying them + /// together. This has the effect of transforming the second basis + /// (the child) by the first basis (the parent). + /// + /// The parent basis. + /// The child basis. + /// The composed basis. public static Basis operator *(Basis left, Basis right) { return new Basis @@ -870,21 +878,40 @@ namespace Godot ); } + /// + /// Returns if the basis matrices are exactly + /// equal. Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left basis. + /// The right basis. + /// Whether or not the basis matrices are exactly equal. public static bool operator ==(Basis left, Basis right) { return left.Equals(right); } + /// + /// Returns if the basis matrices are not equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left basis. + /// The right basis. + /// Whether or not the basis matrices are not equal. public static bool operator !=(Basis left, Basis right) { return !left.Equals(right); } /// - /// Returns if this basis and are equal. + /// Returns if the is + /// exactly equal to the given object (). + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. /// - /// The other object to compare. - /// Whether or not the basis and the other object are equal. + /// The object to compare with. + /// Whether or not the basis matrix and the object are exactly equal. public override bool Equals(object obj) { if (obj is Basis) @@ -896,10 +923,12 @@ namespace Godot } /// - /// Returns if this basis and are equal + /// Returns if the basis matrices are exactly + /// equal. Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. /// - /// The other basis to compare. - /// Whether or not the bases are equal. + /// The other basis. + /// Whether or not the basis matrices are exactly equal. public bool Equals(Basis other) { return Row0.Equals(other.Row0) && Row1.Equals(other.Row1) && Row2.Equals(other.Row2); diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Color.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Color.cs index 684650a815e..41ef452bf7d 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Color.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Color.cs @@ -834,6 +834,13 @@ namespace Godot throw new ArgumentOutOfRangeException("Invalid color code. Blue part is not valid hexadecimal: " + rgba); } + /// + /// Adds each component of the + /// with the components of the given . + /// + /// The left color. + /// The right color. + /// The added color. public static Color operator +(Color left, Color right) { left.r += right.r; @@ -843,6 +850,13 @@ namespace Godot return left; } + /// + /// Subtracts each component of the + /// by the components of the given . + /// + /// The left color. + /// The right color. + /// The subtracted color. public static Color operator -(Color left, Color right) { left.r -= right.r; @@ -852,11 +866,25 @@ namespace Godot return left; } + /// + /// Inverts the given color. This is equivalent to + /// Colors.White - c or + /// new Color(1 - c.r, 1 - c.g, 1 - c.b, 1 - c.a). + /// + /// The color to invert. + /// The inverted color public static Color operator -(Color color) { return Colors.White - color; } + /// + /// Multiplies each component of the + /// by the given . + /// + /// The color to multiply. + /// The value to multiply by. + /// The multiplied color. public static Color operator *(Color color, float scale) { color.r *= scale; @@ -866,6 +894,13 @@ namespace Godot return color; } + /// + /// Multiplies each component of the + /// by the given . + /// + /// The value to multiply by. + /// The color to multiply. + /// The multiplied color. public static Color operator *(float scale, Color color) { color.r *= scale; @@ -875,6 +910,13 @@ namespace Godot return color; } + /// + /// Multiplies each component of the + /// by the components of the given . + /// + /// The left color. + /// The right color. + /// The multiplied color. public static Color operator *(Color left, Color right) { left.r *= right.r; @@ -884,6 +926,13 @@ namespace Godot return left; } + /// + /// Divides each component of the + /// by the given . + /// + /// The dividend vector. + /// The divisor value. + /// The divided color. public static Color operator /(Color color, float scale) { color.r /= scale; @@ -893,6 +942,13 @@ namespace Godot return color; } + /// + /// Divides each component of the + /// by the components of the given . + /// + /// The dividend color. + /// The divisor color. + /// The divided color. public static Color operator /(Color left, Color right) { left.r /= right.r; @@ -902,16 +958,44 @@ namespace Godot return left; } + /// + /// Returns if the colors are exactly equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left color. + /// The right color. + /// Whether or not the colors are equal. public static bool operator ==(Color left, Color right) { return left.Equals(right); } + /// + /// Returns if the colors are not equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left color. + /// The right color. + /// Whether or not the colors are equal. public static bool operator !=(Color left, Color right) { return !left.Equals(right); } + /// + /// Compares two s by first checking if + /// the red value of the color is less than + /// the red value of the color. + /// If the red values are exactly equal, then it repeats this check + /// with the green values of the two colors, then with the blue values, + /// and then with the alpha value. + /// This operator is useful for sorting colors. + /// + /// The left color. + /// The right color. + /// Whether or not the left is less than the right. public static bool operator <(Color left, Color right) { if (Mathf.IsEqualApprox(left.r, right.r)) @@ -929,6 +1013,18 @@ namespace Godot return left.r < right.r; } + /// + /// Compares two s by first checking if + /// the red value of the color is greater than + /// the red value of the color. + /// If the red values are exactly equal, then it repeats this check + /// with the green values of the two colors, then with the blue values, + /// and then with the alpha value. + /// This operator is useful for sorting colors. + /// + /// The left color. + /// The right color. + /// Whether or not the left is greater than the right. public static bool operator >(Color left, Color right) { if (Mathf.IsEqualApprox(left.r, right.r)) @@ -962,9 +1058,11 @@ namespace Godot } /// - /// Returns if this color and are equal + /// Returns if the colors are exactly equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. /// - /// The other color to compare. + /// The other color. /// Whether or not the colors are equal. public bool Equals(Color other) { diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Colors.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Colors.cs index 0ee9fb8659e..0433a5150cf 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Colors.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Colors.cs @@ -158,6 +158,7 @@ namespace Godot {"yellowgreen", new Color(0.60f, 0.80f, 0.20f)}, }; +#pragma warning disable CS1591 // Disable warning: "Missing XML comment for publicly visible type or member" public static Color AliceBlue { get { return namedColors["aliceblue"]; } } public static Color AntiqueWhite { get { return namedColors["antiquewhite"]; } } public static Color Aqua { get { return namedColors["aqua"]; } } @@ -304,5 +305,6 @@ namespace Godot public static Color WhiteSmoke { get { return namedColors["whitesmoke"]; } } public static Color Yellow { get { return namedColors["yellow"]; } } public static Color YellowGreen { get { return namedColors["yellowgreen"]; } } +#pragma warning restore CS1591 } } diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Plane.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Plane.cs index 3c0be46f5cf..12f3a1891ae 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Plane.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Plane.cs @@ -320,16 +320,43 @@ namespace Godot D = _normal.Dot(v1); } + /// + /// Returns the negative value of the . + /// This is the same as writing new Plane(-p.Normal, -p.D). + /// This operation flips the direction of the normal vector and + /// also flips the distance value, resulting in a Plane that is + /// in the same place, but facing the opposite direction. + /// + /// The plane to negate/flip. + /// The negated/flipped plane. public static Plane operator -(Plane plane) { return new Plane(-plane._normal, -plane.D); } + /// + /// Returns if the + /// s are exactly equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left rect. + /// The right rect. + /// Whether or not the planes are exactly equal. public static bool operator ==(Plane left, Plane right) { return left.Equals(right); } + /// + /// Returns if the + /// s are not equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left rect. + /// The right rect. + /// Whether or not the planes are not equal. public static bool operator !=(Plane left, Plane right) { return !left.Equals(right); @@ -339,7 +366,7 @@ namespace Godot /// Returns if this plane and are equal. /// /// The other object to compare. - /// Whether or not the plane and the other object are equal. + /// Whether or not the plane and the other object are exactly equal. public override bool Equals(object obj) { if (obj is Plane) @@ -354,7 +381,7 @@ namespace Godot /// Returns if this plane and are equal. /// /// The other plane to compare. - /// Whether or not the planes are equal. + /// Whether or not the planes are exactly equal. public bool Equals(Plane other) { return _normal == other._normal && D == other.D; diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Quat.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Quat.cs index 8f19fdb3c79..9de41160972 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Quat.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Quat.cs @@ -473,6 +473,14 @@ namespace Godot } } + /// + /// Composes these two quaternions by multiplying them together. + /// This has the effect of rotating the second quaternion + /// (the child) by the first quaternion (the parent). + /// + /// The parent quaternion. + /// The child quaternion. + /// The composed quaternion. public static Quat operator *(Quat left, Quat right) { return new Quat @@ -484,21 +492,49 @@ namespace Godot ); } + /// + /// Adds each component of the left + /// to the right . This operation is not + /// meaningful on its own, but it can be used as a part of a + /// larger expression, such as approximating an intermediate + /// rotation between two nearby rotations. + /// + /// The left quaternion to add. + /// The right quaternion to add. + /// The added quaternion. public static Quat operator +(Quat left, Quat right) { return new Quat(left.x + right.x, left.y + right.y, left.z + right.z, left.w + right.w); } + /// + /// Subtracts each component of the left + /// by the right . This operation is not + /// meaningful on its own, but it can be used as a part of a + /// larger expression. + /// + /// The left quaternion to subtract. + /// The right quaternion to subtract. + /// The subtracted quaternion. public static Quat operator -(Quat left, Quat right) { return new Quat(left.x - right.x, left.y - right.y, left.z - right.z, left.w - right.w); } - public static Quat operator -(Quat left) + /// + /// Returns the negative value of the . + /// This is the same as writing + /// new Quat(-q.x, -q.y, -q.z, -q.w). This operation + /// results in a quaternion that represents the same rotation. + /// + /// The quaternion to negate. + /// The negated quaternion. + public static Quat operator -(Quat quat) { - return new Quat(-left.x, -left.y, -left.z, -left.w); + return new Quat(-quat.x, -quat.y, -quat.z, -quat.w); } + [Obsolete("This operator does not have the correct behavior and will be replaced in the future. Do not use this.")] public static Quat operator *(Quat left, Vector3 right) { return new Quat @@ -510,6 +546,7 @@ namespace Godot ); } + [Obsolete("This operator does not have the correct behavior and will be replaced in the future. Do not use this.")] public static Quat operator *(Vector3 left, Quat right) { return new Quat @@ -521,26 +558,69 @@ namespace Godot ); } + /// + /// Multiplies each component of the + /// by the given . This operation is not + /// meaningful on its own, but it can be used as a part of a + /// larger expression. + /// + /// The quaternion to multiply. + /// The value to multiply by. + /// The multiplied quaternion. public static Quat operator *(Quat left, real_t right) { return new Quat(left.x * right, left.y * right, left.z * right, left.w * right); } + /// + /// Multiplies each component of the + /// by the given . This operation is not + /// meaningful on its own, but it can be used as a part of a + /// larger expression. + /// + /// The value to multiply by. + /// The quaternion to multiply. + /// The multiplied quaternion. public static Quat operator *(real_t left, Quat right) { return new Quat(right.x * left, right.y * left, right.z * left, right.w * left); } + /// + /// Divides each component of the + /// by the given . This operation is not + /// meaningful on its own, but it can be used as a part of a + /// larger expression. + /// + /// The quaternion to divide. + /// The value to divide by. + /// The divided quaternion. public static Quat operator /(Quat left, real_t right) { return left * (1.0f / right); } + /// + /// Returns if the quaternions are exactly equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left quaternion. + /// The right quaternion. + /// Whether or not the quaternions are exactly equal. public static bool operator ==(Quat left, Quat right) { return left.Equals(right); } + /// + /// Returns if the quaternions are not equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left quaternion. + /// The right quaternion. + /// Whether or not the quaternions are not equal. public static bool operator !=(Quat left, Quat right) { return !left.Equals(right); @@ -550,7 +630,7 @@ namespace Godot /// Returns if this quaternion and are equal. /// /// The other object to compare. - /// Whether or not the quaternion and the other object are equal. + /// Whether or not the quaternion and the other object are exactly equal. public override bool Equals(object obj) { if (obj is Quat) @@ -565,7 +645,7 @@ namespace Godot /// Returns if this quaternion and are equal. /// /// The other quaternion to compare. - /// Whether or not the quaternions are equal. + /// Whether or not the quaternions are exactly equal. public bool Equals(Quat other) { return x == other.x && y == other.y && z == other.z && w == other.w; diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Rect2.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Rect2.cs index acfa3107a2e..756d90fa6a6 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Rect2.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Rect2.cs @@ -383,11 +383,29 @@ namespace Godot _size = new Vector2(width, height); } + /// + /// Returns if the + /// s are exactly equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left rect. + /// The right rect. + /// Whether or not the rects are exactly equal. public static bool operator ==(Rect2 left, Rect2 right) { return left.Equals(right); } + /// + /// Returns if the + /// s are not equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left rect. + /// The right rect. + /// Whether or not the rects are not equal. public static bool operator !=(Rect2 left, Rect2 right) { return !left.Equals(right); @@ -397,7 +415,7 @@ namespace Godot /// Returns if this rect and are equal. /// /// The other object to compare. - /// Whether or not the rect and the other object are equal. + /// Whether or not the rect and the other object are exactly equal. public override bool Equals(object obj) { if (obj is Rect2) @@ -412,7 +430,7 @@ namespace Godot /// Returns if this rect and are equal. /// /// The other rect to compare. - /// Whether or not the rects are equal. + /// Whether or not the rects are exactly equal. public bool Equals(Rect2 other) { return _position.Equals(other._position) && _size.Equals(other._size); diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform.cs index 7c8a9a292b3..6c1b987add1 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform.cs @@ -350,6 +350,14 @@ namespace Godot this.origin = origin; } + /// + /// Composes these two transformation matrices by multiplying them + /// together. This has the effect of transforming the second transform + /// (the child) by the first transform (the parent). + /// + /// The parent transform. + /// The child transform. + /// The composed transform. public static Transform operator *(Transform left, Transform right) { left.origin = left.Xform(right.origin); @@ -357,21 +365,40 @@ namespace Godot return left; } + /// + /// Returns if the transforms are exactly equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left transform. + /// The right transform. + /// Whether or not the transforms are exactly equal. public static bool operator ==(Transform left, Transform right) { return left.Equals(right); } + /// + /// Returns if the transforms are not equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left transform. + /// The right transform. + /// Whether or not the transforms are not equal. public static bool operator !=(Transform left, Transform right) { return !left.Equals(right); } /// - /// Returns if this transform and are equal. + /// Returns if the transform is exactly equal + /// to the given object (). + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. /// - /// The other object to compare. - /// Whether or not the transform and the other object are equal. + /// The object to compare with. + /// Whether or not the transform and the object are exactly equal. public override bool Equals(object obj) { if (obj is Transform) @@ -383,10 +410,12 @@ namespace Godot } /// - /// Returns if this transform and are equal. + /// Returns if the transforms are exactly equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. /// /// The other transform to compare. - /// Whether or not the matrices are equal. + /// Whether or not the matrices are exactly equal. public bool Equals(Transform other) { return basis.Equals(other.basis) && origin.Equals(other.origin); diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform2D.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform2D.cs index 58530ab35a0..ce589093b94 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform2D.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform2D.cs @@ -447,6 +447,14 @@ namespace Godot this.origin = origin; } + /// + /// Composes these two transformation matrices by multiplying them + /// together. This has the effect of transforming the second transform + /// (the child) by the first transform (the parent). + /// + /// The parent transform. + /// The child transform. + /// The composed transform. public static Transform2D operator *(Transform2D left, Transform2D right) { left.origin = left * right.origin; @@ -554,31 +562,52 @@ namespace Godot return newArray; } + /// + /// Returns if the transforms are exactly equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left transform. + /// The right transform. + /// Whether or not the transforms are exactly equal. public static bool operator ==(Transform2D left, Transform2D right) { return left.Equals(right); } + /// + /// Returns if the transforms are not equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left transform. + /// The right transform. + /// Whether or not the transforms are not equal. public static bool operator !=(Transform2D left, Transform2D right) { return !left.Equals(right); } /// - /// Returns if this transform and are equal. + /// Returns if the transform is exactly equal + /// to the given object (). + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. /// - /// The other object to compare. - /// Whether or not the transform and the other object are equal. + /// The object to compare with. + /// Whether or not the transform and the object are exactly equal. public override bool Equals(object obj) { return obj is Transform2D transform2D && Equals(transform2D); } /// - /// Returns if this transform and are equal. + /// Returns if the transforms are exactly equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. /// /// The other transform to compare. - /// Whether or not the matrices are equal. + /// Whether or not the matrices are exactly equal. public bool Equals(Transform2D other) { return x.Equals(other.x) && y.Equals(other.y) && origin.Equals(other.origin); diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Vector2.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Vector2.cs index a6ea34a1fe7..a45af4fea3b 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Vector2.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Vector2.cs @@ -645,6 +645,13 @@ namespace Godot y = v.y; } + /// + /// Adds each component of the + /// with the components of the given . + /// + /// The left vector. + /// The right vector. + /// The added vector. public static Vector2 operator +(Vector2 left, Vector2 right) { left.x += right.x; @@ -652,6 +659,13 @@ namespace Godot return left; } + /// + /// Subtracts each component of the + /// by the components of the given . + /// + /// The left vector. + /// The right vector. + /// The subtracted vector. public static Vector2 operator -(Vector2 left, Vector2 right) { left.x -= right.x; @@ -659,6 +673,15 @@ namespace Godot return left; } + /// + /// Returns the negative value of the . + /// This is the same as writing new Vector2(-v.x, -v.y). + /// This operation flips the direction of the vector while + /// keeping the same magnitude. + /// With floats, the number zero can be either positive or negative. + /// + /// The vector to negate/flip. + /// The negated/flipped vector. public static Vector2 operator -(Vector2 vec) { vec.x = -vec.x; @@ -666,6 +689,13 @@ namespace Godot return vec; } + /// + /// Multiplies each component of the + /// by the given . + /// + /// The vector to multiply. + /// The scale to multiply by. + /// The multiplied vector. public static Vector2 operator *(Vector2 vec, real_t scale) { vec.x *= scale; @@ -673,6 +703,13 @@ namespace Godot return vec; } + /// + /// Multiplies each component of the + /// by the given . + /// + /// The scale to multiply by. + /// The vector to multiply. + /// The multiplied vector. public static Vector2 operator *(real_t scale, Vector2 vec) { vec.x *= scale; @@ -680,6 +717,13 @@ namespace Godot return vec; } + /// + /// Multiplies each component of the + /// by the components of the given . + /// + /// The left vector. + /// The right vector. + /// The multiplied vector. public static Vector2 operator *(Vector2 left, Vector2 right) { left.x *= right.x; @@ -687,6 +731,13 @@ namespace Godot return left; } + /// + /// Multiplies each component of the + /// by the given . + /// + /// The dividend vector. + /// The divisor value. + /// The divided vector. public static Vector2 operator /(Vector2 vec, real_t divisor) { vec.x /= divisor; @@ -694,6 +745,13 @@ namespace Godot return vec; } + /// + /// Divides each component of the + /// by the components of the given . + /// + /// The dividend vector. + /// The divisor vector. + /// The divided vector. public static Vector2 operator /(Vector2 vec, Vector2 divisorv) { vec.x /= divisorv.x; @@ -701,6 +759,22 @@ namespace Godot return vec; } + /// + /// Gets the remainder of each component of the + /// with the components of the given . + /// This operation uses truncated division, which is often not desired + /// as it does not work well with negative numbers. + /// Consider using instead + /// if you want to handle negative numbers. + /// + /// + /// + /// GD.Print(new Vector2(10, -20) % 7); // Prints "(3, -6)" + /// + /// + /// The dividend vector. + /// The divisor value. + /// The remainder vector. public static Vector2 operator %(Vector2 vec, real_t divisor) { vec.x %= divisor; @@ -708,6 +782,22 @@ namespace Godot return vec; } + /// + /// Gets the remainder of each component of the + /// with the components of the given . + /// This operation uses truncated division, which is often not desired + /// as it does not work well with negative numbers. + /// Consider using instead + /// if you want to handle negative numbers. + /// + /// + /// + /// GD.Print(new Vector2(10, -20) % new Vector2(7, 8)); // Prints "(3, -4)" + /// + /// + /// The dividend vector. + /// The divisor vector. + /// The remainder vector. public static Vector2 operator %(Vector2 vec, Vector2 divisorv) { vec.x %= divisorv.x; @@ -715,16 +805,43 @@ namespace Godot return vec; } + /// + /// Returns if the vectors are exactly equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left vector. + /// The right vector. + /// Whether or not the vectors are exactly equal. public static bool operator ==(Vector2 left, Vector2 right) { return left.Equals(right); } + /// + /// Returns if the vectors are not equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left vector. + /// The right vector. + /// Whether or not the vectors are not equal. public static bool operator !=(Vector2 left, Vector2 right) { return !left.Equals(right); } + /// + /// Compares two vectors by first checking if + /// the X value of the vector is less than + /// the X value of the vector. + /// If the X values are exactly equal, then it repeats this check + /// with the Y values of the two vectors. + /// This operator is useful for sorting vectors. + /// + /// The left vector. + /// The right vector. + /// Whether or not the left is less than the right. public static bool operator <(Vector2 left, Vector2 right) { if (left.x == right.x) @@ -734,6 +851,17 @@ namespace Godot return left.x < right.x; } + /// + /// Compares two vectors by first checking if + /// the X value of the vector is greater than + /// the X value of the vector. + /// If the X values are exactly equal, then it repeats this check + /// with the Y values of the two vectors. + /// This operator is useful for sorting vectors. + /// + /// The left vector. + /// The right vector. + /// Whether or not the left is greater than the right. public static bool operator >(Vector2 left, Vector2 right) { if (left.x == right.x) @@ -743,29 +871,54 @@ namespace Godot return left.x > right.x; } + /// + /// Compares two vectors by first checking if + /// the X value of the vector is less than + /// or equal to the X value of the vector. + /// If the X values are exactly equal, then it repeats this check + /// with the Y values of the two vectors. + /// This operator is useful for sorting vectors. + /// + /// The left vector. + /// The right vector. + /// Whether or not the left is less than or equal to the right. public static bool operator <=(Vector2 left, Vector2 right) { if (left.x == right.x) { return left.y <= right.y; } - return left.x <= right.x; + return left.x < right.x; } + /// + /// Compares two vectors by first checking if + /// the X value of the vector is greater than + /// or equal to the X value of the vector. + /// If the X values are exactly equal, then it repeats this check + /// with the Y values of the two vectors. + /// This operator is useful for sorting vectors. + /// + /// The left vector. + /// The right vector. + /// Whether or not the left is greater than or equal to the right. public static bool operator >=(Vector2 left, Vector2 right) { if (left.x == right.x) { return left.y >= right.y; } - return left.x >= right.x; + return left.x > right.x; } /// - /// Returns if this vector and are equal. + /// Returns if the vector is exactly equal + /// to the given object (). + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. /// - /// The other object to compare. - /// Whether or not the vector and the other object are equal. + /// The object to compare with. + /// Whether or not the vector and the object are equal. public override bool Equals(object obj) { if (obj is Vector2) @@ -776,10 +929,12 @@ namespace Godot } /// - /// Returns if this vector and are equal. + /// Returns if the vectors are exactly equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. /// - /// The other vector to compare. - /// Whether or not the vectors are equal. + /// The other vector. + /// Whether or not the vectors are exactly equal. public bool Equals(Vector2 other) { return x == other.x && y == other.y; diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Vector3.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Vector3.cs index 1f83dbbf10d..89f07728a16 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Vector3.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Vector3.cs @@ -684,6 +684,13 @@ namespace Godot z = v.z; } + /// + /// Adds each component of the + /// with the components of the given . + /// + /// The left vector. + /// The right vector. + /// The added vector. public static Vector3 operator +(Vector3 left, Vector3 right) { left.x += right.x; @@ -692,6 +699,13 @@ namespace Godot return left; } + /// + /// Subtracts each component of the + /// by the components of the given . + /// + /// The left vector. + /// The right vector. + /// The subtracted vector. public static Vector3 operator -(Vector3 left, Vector3 right) { left.x -= right.x; @@ -700,6 +714,15 @@ namespace Godot return left; } + /// + /// Returns the negative value of the . + /// This is the same as writing new Vector3(-v.x, -v.y, -v.z). + /// This operation flips the direction of the vector while + /// keeping the same magnitude. + /// With floats, the number zero can be either positive or negative. + /// + /// The vector to negate/flip. + /// The negated/flipped vector. public static Vector3 operator -(Vector3 vec) { vec.x = -vec.x; @@ -708,6 +731,13 @@ namespace Godot return vec; } + /// + /// Multiplies each component of the + /// by the given . + /// + /// The vector to multiply. + /// The scale to multiply by. + /// The multiplied vector. public static Vector3 operator *(Vector3 vec, real_t scale) { vec.x *= scale; @@ -716,6 +746,13 @@ namespace Godot return vec; } + /// + /// Multiplies each component of the + /// by the given . + /// + /// The scale to multiply by. + /// The vector to multiply. + /// The multiplied vector. public static Vector3 operator *(real_t scale, Vector3 vec) { vec.x *= scale; @@ -724,6 +761,13 @@ namespace Godot return vec; } + /// + /// Multiplies each component of the + /// by the components of the given . + /// + /// The left vector. + /// The right vector. + /// The multiplied vector. public static Vector3 operator *(Vector3 left, Vector3 right) { left.x *= right.x; @@ -732,6 +776,13 @@ namespace Godot return left; } + /// + /// Divides each component of the + /// by the given . + /// + /// The dividend vector. + /// The divisor value. + /// The divided vector. public static Vector3 operator /(Vector3 vec, real_t divisor) { vec.x /= divisor; @@ -740,6 +791,13 @@ namespace Godot return vec; } + /// + /// Divides each component of the + /// by the components of the given . + /// + /// The dividend vector. + /// The divisor vector. + /// The divided vector. public static Vector3 operator /(Vector3 vec, Vector3 divisorv) { vec.x /= divisorv.x; @@ -748,6 +806,22 @@ namespace Godot return vec; } + /// + /// Gets the remainder of each component of the + /// with the components of the given . + /// This operation uses truncated division, which is often not desired + /// as it does not work well with negative numbers. + /// Consider using instead + /// if you want to handle negative numbers. + /// + /// + /// + /// GD.Print(new Vector3(10, -20, 30) % 7); // Prints "(3, -6, 2)" + /// + /// + /// The dividend vector. + /// The divisor value. + /// The remainder vector. public static Vector3 operator %(Vector3 vec, real_t divisor) { vec.x %= divisor; @@ -756,6 +830,22 @@ namespace Godot return vec; } + /// + /// Gets the remainder of each component of the + /// with the components of the given . + /// This operation uses truncated division, which is often not desired + /// as it does not work well with negative numbers. + /// Consider using instead + /// if you want to handle negative numbers. + /// + /// + /// + /// GD.Print(new Vector3(10, -20, 30) % new Vector3(7, 8, 9)); // Prints "(3, -4, 3)" + /// + /// + /// The dividend vector. + /// The divisor vector. + /// The remainder vector. public static Vector3 operator %(Vector3 vec, Vector3 divisorv) { vec.x %= divisorv.x; @@ -764,16 +854,43 @@ namespace Godot return vec; } + /// + /// Returns if the vectors are exactly equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left vector. + /// The right vector. + /// Whether or not the vectors are exactly equal. public static bool operator ==(Vector3 left, Vector3 right) { return left.Equals(right); } + /// + /// Returns if the vectors are not equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. + /// + /// The left vector. + /// The right vector. + /// Whether or not the vectors are not equal. public static bool operator !=(Vector3 left, Vector3 right) { return !left.Equals(right); } + /// + /// Compares two vectors by first checking if + /// the X value of the vector is less than + /// the X value of the vector. + /// If the X values are exactly equal, then it repeats this check + /// with the Y values of the two vectors, and then with the Z values. + /// This operator is useful for sorting vectors. + /// + /// The left vector. + /// The right vector. + /// Whether or not the left is less than the right. public static bool operator <(Vector3 left, Vector3 right) { if (left.x == right.x) @@ -787,6 +904,17 @@ namespace Godot return left.x < right.x; } + /// + /// Compares two vectors by first checking if + /// the X value of the vector is greater than + /// the X value of the vector. + /// If the X values are exactly equal, then it repeats this check + /// with the Y values of the two vectors, and then with the Z values. + /// This operator is useful for sorting vectors. + /// + /// The left vector. + /// The right vector. + /// Whether or not the left is greater than the right. public static bool operator >(Vector3 left, Vector3 right) { if (left.x == right.x) @@ -800,6 +928,17 @@ namespace Godot return left.x > right.x; } + /// + /// Compares two vectors by first checking if + /// the X value of the vector is less than + /// or equal to the X value of the vector. + /// If the X values are exactly equal, then it repeats this check + /// with the Y values of the two vectors, and then with the Z values. + /// This operator is useful for sorting vectors. + /// + /// The left vector. + /// The right vector. + /// Whether or not the left is less than or equal to the right. public static bool operator <=(Vector3 left, Vector3 right) { if (left.x == right.x) @@ -813,6 +952,17 @@ namespace Godot return left.x < right.x; } + /// + /// Compares two vectors by first checking if + /// the X value of the vector is greater than + /// or equal to the X value of the vector. + /// If the X values are exactly equal, then it repeats this check + /// with the Y values of the two vectors, and then with the Z values. + /// This operator is useful for sorting vectors. + /// + /// The left vector. + /// The right vector. + /// Whether or not the left is greater than or equal to the right. public static bool operator >=(Vector3 left, Vector3 right) { if (left.x == right.x) @@ -827,10 +977,13 @@ namespace Godot } /// - /// Returns if this vector and are equal. + /// Returns if the vector is exactly equal + /// to the given object (). + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. /// - /// The other object to compare. - /// Whether or not the vector and the other object are equal. + /// The object to compare with. + /// Whether or not the vector and the object are equal. public override bool Equals(object obj) { if (obj is Vector3) @@ -842,10 +995,12 @@ namespace Godot } /// - /// Returns if this vector and are equal + /// Returns if the vectors are exactly equal. + /// Note: Due to floating-point precision errors, consider using + /// instead, which is more reliable. /// - /// The other vector to compare. - /// Whether or not the vectors are equal. + /// The other vector. + /// Whether or not the vectors are exactly equal. public bool Equals(Vector3 other) { return x == other.x && y == other.y && z == other.z;