Merge pull request #45624 from aaronfranke/clamp

Allow clamping vectors and colors in addition to floats and ints

core/math/color.cpp

@@ -211,6 +211,14 @@ bool Color::is_equal_approx(const Color &p_color) const {
 	return Math::is_equal_approx(r, p_color.r) && Math::is_equal_approx(g, p_color.g) && Math::is_equal_approx(b, p_color.b) && Math::is_equal_approx(a, p_color.a);
 }
 
+Color Color::clamp(const Color &p_min, const Color &p_max) const {
+	return Color(
+			CLAMP(r, p_min.r, p_max.r),
+			CLAMP(g, p_min.g, p_max.g),
+			CLAMP(b, p_min.b, p_max.b),
+			CLAMP(a, p_min.a, p_max.a));
+}
+
 void Color::invert() {
 	r = 1.0 - r;
 	g = 1.0 - g;

core/math/color.h

@@ -89,6 +89,7 @@ struct Color {
 
 	bool is_equal_approx(const Color &p_color) const;
 
+	Color clamp(const Color &p_min = Color(0, 0, 0, 0), const Color &p_max = Color(1, 1, 1, 1)) const;
 	void invert();
 	Color inverted() const;
 

core/math/vector2.cpp

@@ -122,14 +122,20 @@ Vector2 Vector2::project(const Vector2 &p_to) const {
 	return p_to * (dot(p_to) / p_to.length_squared());
 }
 
+Vector2 Vector2::clamp(const Vector2 &p_min, const Vector2 &p_max) const {
+	return Vector2(
+			CLAMP(x, p_min.x, p_max.x),
+			CLAMP(y, p_min.y, p_max.y));
+}
+
 Vector2 Vector2::snapped(const Vector2 &p_step) const {
 	return Vector2(
 			Math::snapped(x, p_step.x),
 			Math::snapped(y, p_step.y));
 }
 
-Vector2 Vector2::clamped(real_t p_len) const {
-	real_t l = length();
+Vector2 Vector2::limit_length(const real_t p_len) const {
+	const real_t l = length();
 	Vector2 v = *this;
 	if (l > 0 && p_len < l) {
 		v /= l;
@@ -189,6 +195,12 @@ bool Vector2::is_equal_approx(const Vector2 &p_v) const {
 
 /* Vector2i */
 
+Vector2i Vector2i::clamp(const Vector2i &p_min, const Vector2i &p_max) const {
+	return Vector2i(
+			CLAMP(x, p_min.x, p_max.x),
+			CLAMP(y, p_min.y, p_max.y));
+}
+
 Vector2i Vector2i::operator+(const Vector2i &p_v) const {
 	return Vector2i(x + p_v.x, y + p_v.y);
 }

core/math/vector2.h

@@ -84,6 +84,7 @@ struct Vector2 {
 
 	real_t length() const;
 	real_t length_squared() const;
+	Vector2 limit_length(const real_t p_len = 1.0) const;
 
 	Vector2 min(const Vector2 &p_vector2) const {
 		return Vector2(MIN(x, p_vector2.x), MIN(y, p_vector2.y));
@@ -107,8 +108,6 @@ struct Vector2 {
 
 	Vector2 plane_project(real_t p_d, const Vector2 &p_vec) const;
 
-	Vector2 clamped(real_t p_len) const;
-
 	_FORCE_INLINE_ Vector2 lerp(const Vector2 &p_to, real_t p_weight) const;
 	_FORCE_INLINE_ Vector2 slerp(const Vector2 &p_to, real_t p_weight) const;
 	Vector2 cubic_interpolate(const Vector2 &p_b, const Vector2 &p_pre_a, const Vector2 &p_post_b, real_t p_weight) const;
@@ -163,6 +162,7 @@ struct Vector2 {
 	Vector2 ceil() const;
 	Vector2 round() const;
 	Vector2 snapped(const Vector2 &p_by) const;
+	Vector2 clamp(const Vector2 &p_min, const Vector2 &p_max) const;
 	real_t aspect() const { return width / height; }
 
 	operator String() const { return String::num(x) + ", " + String::num(y); }
@@ -338,6 +338,7 @@ struct Vector2i {
 	real_t aspect() const { return width / (real_t)height; }
 	Vector2i sign() const { return Vector2i(SGN(x), SGN(y)); }
 	Vector2i abs() const { return Vector2i(ABS(x), ABS(y)); }
+	Vector2i clamp(const Vector2i &p_min, const Vector2i &p_max) const;
 
 	operator String() const { return String::num(x) + ", " + String::num(y); }
 

core/math/vector3.cpp

@@ -52,6 +52,13 @@ real_t Vector3::get_axis(int p_axis) const {
 	return operator[](p_axis);
 }
 
+Vector3 Vector3::clamp(const Vector3 &p_min, const Vector3 &p_max) const {
+	return Vector3(
+			CLAMP(x, p_min.x, p_max.x),
+			CLAMP(y, p_min.y, p_max.y),
+			CLAMP(z, p_min.z, p_max.z));
+}
+
 void Vector3::snap(Vector3 p_step) {
 	x = Math::snapped(x, p_step.x);
 	y = Math::snapped(y, p_step.y);
@@ -64,6 +71,17 @@ Vector3 Vector3::snapped(Vector3 p_step) const {
 	return v;
 }
 
+Vector3 Vector3::limit_length(const real_t p_len) const {
+	const real_t l = length();
+	Vector3 v = *this;
+	if (l > 0 && p_len < l) {
+		v /= l;
+		v *= p_len;
+	}
+
+	return v;
+}
+
 Vector3 Vector3::cubic_interpolate(const Vector3 &p_b, const Vector3 &p_pre_a, const Vector3 &p_post_b, real_t p_weight) const {
 	Vector3 p0 = p_pre_a;
 	Vector3 p1 = *this;

core/math/vector3.h

@@ -86,6 +86,7 @@ struct Vector3 {
 	_FORCE_INLINE_ Vector3 normalized() const;
 	_FORCE_INLINE_ bool is_normalized() const;
 	_FORCE_INLINE_ Vector3 inverse() const;
+	Vector3 limit_length(const real_t p_len = 1.0) const;
 
 	_FORCE_INLINE_ void zero();
 
@@ -112,6 +113,7 @@ struct Vector3 {
 	_FORCE_INLINE_ Vector3 sign() const;
 	_FORCE_INLINE_ Vector3 ceil() const;
 	_FORCE_INLINE_ Vector3 round() const;
+	Vector3 clamp(const Vector3 &p_min, const Vector3 &p_max) const;
 
 	_FORCE_INLINE_ real_t distance_to(const Vector3 &p_to) const;
 	_FORCE_INLINE_ real_t distance_squared_to(const Vector3 &p_to) const;

core/math/vector3i.cpp

@@ -48,6 +48,13 @@ int Vector3i::max_axis() const {
 	return x < y ? (y < z ? 2 : 1) : (x < z ? 2 : 0);
 }
 
+Vector3i Vector3i::clamp(const Vector3i &p_min, const Vector3i &p_max) const {
+	return Vector3i(
+			CLAMP(x, p_min.x, p_max.x),
+			CLAMP(y, p_min.y, p_max.y),
+			CLAMP(z, p_min.z, p_max.z));
+}
+
 Vector3i::operator String() const {
 	return (itos(x) + ", " + itos(y) + ", " + itos(z));
 }

core/math/vector3i.h

@@ -69,6 +69,7 @@ struct Vector3i {
 
 	_FORCE_INLINE_ Vector3i abs() const;
 	_FORCE_INLINE_ Vector3i sign() const;
+	Vector3i clamp(const Vector3i &p_min, const Vector3i &p_max) const;
 
 	/* Operators */
 

core/variant/variant_call.cpp

@@ -1419,6 +1419,7 @@ static void _register_variant_builtin_methods() {
 	bind_method(Vector2, distance_squared_to, sarray("to"), varray());
 	bind_method(Vector2, length, sarray(), varray());
 	bind_method(Vector2, length_squared, sarray(), varray());
+	bind_method(Vector2, limit_length, sarray("length"), varray(1.0));
 	bind_method(Vector2, normalized, sarray(), varray());
 	bind_method(Vector2, is_normalized, sarray(), varray());
 	bind_method(Vector2, is_equal_approx, sarray("to"), varray());
@@ -1442,14 +1443,15 @@ static void _register_variant_builtin_methods() {
 	bind_method(Vector2, cross, sarray("with"), varray());
 	bind_method(Vector2, abs, sarray(), varray());
 	bind_method(Vector2, sign, sarray(), varray());
+	bind_method(Vector2, clamp, sarray("min", "max"), varray());
 	bind_method(Vector2, snapped, sarray("step"), varray());
-	bind_method(Vector2, clamped, sarray("length"), varray());
 
 	/* Vector2i */
 
 	bind_method(Vector2i, aspect, sarray(), varray());
 	bind_method(Vector2i, sign, sarray(), varray());
 	bind_method(Vector2i, abs, sarray(), varray());
+	bind_method(Vector2i, clamp, sarray("min", "max"), varray());
 
 	/* Rect2 */
 
@@ -1493,10 +1495,12 @@ static void _register_variant_builtin_methods() {
 	bind_method(Vector3, distance_squared_to, sarray("b"), varray());
 	bind_method(Vector3, length, sarray(), varray());
 	bind_method(Vector3, length_squared, sarray(), varray());
+	bind_method(Vector3, limit_length, sarray("length"), varray(1.0));
 	bind_method(Vector3, normalized, sarray(), varray());
 	bind_method(Vector3, is_normalized, sarray(), varray());
 	bind_method(Vector3, is_equal_approx, sarray("to"), varray());
 	bind_method(Vector3, inverse, sarray(), varray());
+	bind_method(Vector3, clamp, sarray("min", "max"), varray());
 	bind_method(Vector3, snapped, sarray("step"), varray());
 	bind_method(Vector3, rotated, sarray("by_axis", "phi"), varray());
 	bind_method(Vector3, lerp, sarray("to", "weight"), varray());
@@ -1525,6 +1529,7 @@ static void _register_variant_builtin_methods() {
 	bind_method(Vector3i, max_axis, sarray(), varray());
 	bind_method(Vector3i, sign, sarray(), varray());
 	bind_method(Vector3i, abs, sarray(), varray());
+	bind_method(Vector3i, clamp, sarray("min", "max"), varray());
 
 	/* Plane */
 
@@ -1562,6 +1567,7 @@ static void _register_variant_builtin_methods() {
 	bind_method(Color, to_abgr64, sarray(), varray());
 	bind_method(Color, to_rgba64, sarray(), varray());
 
+	bind_method(Color, clamp, sarray("min", "max"), varray(Color(0, 0, 0, 0), Color(1, 1, 1, 1)));
 	bind_method(Color, inverted, sarray(), varray());
 	bind_method(Color, lerp, sarray("to", "weight"), varray());
 	bind_method(Color, lightened, sarray("amount"), varray());

doc/classes/Color.xml

@@ -136,6 +136,17 @@
 				[/codeblocks]
 			</description>
 		</method>
+		<method name="clamp" qualifiers="const">
+			<return type="Color">
+			</return>
+			<argument index="0" name="min" type="Color" default="Color( 0, 0, 0, 0 )">
+			</argument>
+			<argument index="1" name="max" type="Color" default="Color( 1, 1, 1, 1 )">
+			</argument>
+			<description>
+				Returns a new color with all components clamped between the components of [code]min[/code] and [code]max[/code], by running [method @GlobalScope.clamp] on each component.
+			</description>
+		</method>
 		<method name="darkened" qualifiers="const">
 			<return type="Color">
 			</return>

doc/classes/Vector2.xml

@@ -110,13 +110,15 @@
 				Returns the vector with all components rounded up (towards positive infinity).
 			</description>
 		</method>
-		<method name="clamped" qualifiers="const">
+		<method name="clamp" qualifiers="const">
 			<return type="Vector2">
 			</return>
-			<argument index="0" name="length" type="float">
+			<argument index="0" name="min" type="Vector2">
+			</argument>
+			<argument index="1" name="max" type="Vector2">
 			</argument>
 			<description>
-				Returns the vector with a maximum length by limiting its length to [code]length[/code].
+				Returns a new vector with all components clamped between the components of [code]min[/code] and [code]max[/code], by running [method @GlobalScope.clamp] on each component.
 			</description>
 		</method>
 		<method name="cross" qualifiers="const">
@@ -232,6 +234,15 @@
 				Returns the result of the linear interpolation between this vector and [code]to[/code] by amount [code]weight[/code]. [code]weight[/code] is on the range of 0.0 to 1.0, representing the amount of interpolation.
 			</description>
 		</method>
+		<method name="limit_length" qualifiers="const">
+			<return type="Vector2">
+			</return>
+			<argument index="0" name="length" type="float" default="1.0">
+			</argument>
+			<description>
+				Returns the vector with a maximum length by limiting its length to [code]length[/code].
+			</description>
+		</method>
 		<method name="move_toward" qualifiers="const">
 			<return type="Vector2">
 			</return>

doc/classes/Vector2i.xml

@@ -64,6 +64,17 @@
 				Returns the ratio of [member x] to [member y].
 			</description>
 		</method>
+		<method name="clamp" qualifiers="const">
+			<return type="Vector2i">
+			</return>
+			<argument index="0" name="min" type="Vector2i">
+			</argument>
+			<argument index="1" name="max" type="Vector2i">
+			</argument>
+			<description>
+				Returns a new vector with all components clamped between the components of [code]min[/code] and [code]max[/code], by running [method @GlobalScope.clamp] on each component.
+			</description>
+		</method>
 		<method name="operator !=" qualifiers="operator">
 			<return type="bool">
 			</return>

doc/classes/Vector3.xml

@@ -87,6 +87,17 @@
 				Returns a new vector with all components rounded up (towards positive infinity).
 			</description>
 		</method>
+		<method name="clamp" qualifiers="const">
+			<return type="Vector3">
+			</return>
+			<argument index="0" name="min" type="Vector3">
+			</argument>
+			<argument index="1" name="max" type="Vector3">
+			</argument>
+			<description>
+				Returns a new vector with all components clamped between the components of [code]min[/code] and [code]max[/code], by running [method @GlobalScope.clamp] on each component.
+			</description>
+		</method>
 		<method name="cross" qualifiers="const">
 			<return type="Vector3">
 			</return>
@@ -207,6 +218,15 @@
 				Returns the result of the linear interpolation between this vector and [code]to[/code] by amount [code]weight[/code]. [code]weight[/code] is on the range of 0.0 to 1.0, representing the amount of interpolation.
 			</description>
 		</method>
+		<method name="limit_length" qualifiers="const">
+			<return type="Vector3">
+			</return>
+			<argument index="0" name="length" type="float" default="1.0">
+			</argument>
+			<description>
+				Returns the vector with a maximum length by limiting its length to [code]length[/code].
+			</description>
+		</method>
 		<method name="max_axis" qualifiers="const">
 			<return type="int">
 			</return>

doc/classes/Vector3i.xml

@@ -58,6 +58,17 @@
 			<description>
 			</description>
 		</method>
+		<method name="clamp" qualifiers="const">
+			<return type="Vector3i">
+			</return>
+			<argument index="0" name="min" type="Vector3i">
+			</argument>
+			<argument index="1" name="max" type="Vector3i">
+			</argument>
+			<description>
+				Returns a new vector with all components clamped between the components of [code]min[/code] and [code]max[/code], by running [method @GlobalScope.clamp] on each component.
+			</description>
+		</method>
 		<method name="max_axis" qualifiers="const">
 			<return type="int">
 			</return>

modules/mono/glue/GodotSharp/GodotSharp/Core/Color.cs

@@ -256,6 +256,27 @@ public Color Blend(Color over)
             return res;
         }
 
+        /// <summary>
+        /// Returns a new color with all components clamped between the
+        /// components of `min` and `max` using
+        /// <see cref="Mathf.Clamp(float, float, float)"/>.
+        /// </summary>
+        /// <param name="min">The color with minimum allowed values.</param>
+        /// <param name="max">The color with maximum allowed values.</param>
+        /// <returns>The color with all components clamped.</returns>
+        public Color Clamp(Color? min = null, Color? max = null)
+        {
+            Color minimum = min ?? new Color(0, 0, 0, 0);
+            Color maximum = max ?? new Color(1, 1, 1, 1);
+            return new Color
+            (
+                (float)Mathf.Clamp(r, minimum.r, maximum.r),
+                (float)Mathf.Clamp(g, minimum.g, maximum.g),
+                (float)Mathf.Clamp(b, minimum.b, maximum.b),
+                (float)Mathf.Clamp(a, minimum.a, maximum.a)
+            );
+        }
+
         /// <summary>
         /// Returns a new color resulting from making this color darker
         /// by the specified ratio (on the range of 0 to 1).