Add handedness enum for is_polygon_clockwise

[exodrifter]

When this was originally implemented in 16022da, the implementation treated the vertices as being in a space where the y-axis is positive in the up direction. This causes it to return the incorrect value for 2D games, since Godot treats the y-axis as being positive in the down direction.

This change maintains compatibility with existing uses of is_polygon_clockwise by adding an optional parameter which allows the user to select which handedness their coordinate system uses. The documentation for is_polygon_clockwise has also been updated to describe the difference.

This PR replaces #80035, from which it differs in the following ways:

• Compatibility with existing calls is preserved.
• Instead of always flipping the return result, the return result is only flipped when the left-handed version is asked for.

Fixes #49716.

[AThousandShips]

For compatibility you need to add compatibility bindings, will explain how to add those, when I'm back at my computer

[AThousandShips]

This needs to be added:

diff --git a/core/core_bind.compat.inc b/core/core_bind.compat.inc
new file mode 100644
index 0000000000..aa4399bb76
--- /dev/null
+++ b/core/core_bind.compat.inc
@@ -0,0 +1,47 @@
+/**************************************************************************/
+/*  core_bind.compat.inc                                                  */
+/**************************************************************************/
+/*                         This file is part of:                          */
+/*                             GODOT ENGINE                               */
+/*                        https://godotengine.org                         */
+/**************************************************************************/
+/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
+/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur.                  */
+/*                                                                        */
+/* Permission is hereby granted, free of charge, to any person obtaining  */
+/* a copy of this software and associated documentation files (the        */
+/* "Software"), to deal in the Software without restriction, including    */
+/* without limitation the rights to use, copy, modify, merge, publish,    */
+/* distribute, sublicense, and/or sell copies of the Software, and to     */
+/* permit persons to whom the Software is furnished to do so, subject to  */
+/* the following conditions:                                              */
+/*                                                                        */
+/* The above copyright notice and this permission notice shall be         */
+/* included in all copies or substantial portions of the Software.        */
+/*                                                                        */
+/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,        */
+/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF     */
+/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
+/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY   */
+/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,   */
+/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE      */
+/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                 */
+/**************************************************************************/
+
+#ifndef DISABLE_DEPRECATED
+
+namespace core_bind {
+
+////// Geometry2D //////
+
+bool Geometry2D::_is_polygon_clockwise_bind_compat_89635(const Vector<Vector2> &p_polygon) {
+       return is_polygon_clockwise(p_polygon, RIGHT_HAND);
+}
+
+void Geometry2D::_bind_compatibility_methods() {
+       ClassDB::bind_compatibility_method(D_METHOD("is_polygon_clockwise", "polygon"), &Geometry2D::_is_polygon_clockwise_bind_compat_89635);
+}
+
+} // namespace core_bind
+
+#endif // DISABLE_DEPRECATED
diff --git a/core/core_bind.cpp b/core/core_bind.cpp
index 6927db002b..2185775dc0 100644
--- a/core/core_bind.cpp
+++ b/core/core_bind.cpp
@@ -29,6 +29,7 @@
 /**************************************************************************/
 
 #include "core_bind.h"
+#include "core_bind.compat.inc"
 
 #include "core/config/project_settings.h"
 #include "core/crypto/crypto_core.h"
diff --git a/core/core_bind.h b/core/core_bind.h
index 305f616cef..e27bfa26ef 100644
--- a/core/core_bind.h
+++ b/core/core_bind.h
@@ -257,6 +257,11 @@ class Geometry2D : public Object {
 protected:
 	static void _bind_methods();
 
+#ifndef DISABLE_DEPRECATED
+	bool _is_polygon_clockwise_bind_compat_89635(const Vector<Vector2> &p_polygon);
+	static void _bind_compatibility_methods();
+#endif // DISABLE_DEPRECATED
+
 public:
 	static Geometry2D *get_singleton();
 	Variant segment_intersects_segment(const Vector2 &p_from_a, const Vector2 &p_to_a, const Vector2 &p_from_b, const Vector2 &p_to_b);
diff --git a/misc/extension_api_validation/4.2-stable.expected b/misc/extension_api_validation/4.2-stable.expected
index 8623e8eb25..cf4cb1590f 100644
--- a/misc/extension_api_validation/4.2-stable.expected
+++ b/misc/extension_api_validation/4.2-stable.expected
@@ -248,3 +248,10 @@ Validate extension JSON: Error: Field 'classes/AcceptDialog/methods/register_tex
 Validate extension JSON: Error: Field 'classes/AcceptDialog/methods/remove_button/arguments/0': type changed value in new API, from "Control" to "Button".
 
 Changed argument type to the more specific one actually expected by the method. Compatibility method registered.
+
+
+GH-89635
+--------
+Validate extension JSON: Error: Field 'classes/Geometry2D/methods/is_polygon_clockwise/arguments': size changed value in new API, from 1 to 2.
+
+Added handedness argument. Compatibility method registered.

[exodrifter]

@AThousandShips Added in 5d606feff84f4c129ead0ae73600172af0f690b4. I'm not terribly familiar with how this works but I'll try to keep it in mind for future PRs.

[AThousandShips]

When I have the energy and time I'm going to write a doc page on this, but it's a bit of a large task so haven't been able to focus on it

[AThousandShips]

This looks good to me but the need and approach would need a look by the core team :)

[lawnjelly]

Agree that more eyes on this would be good. Imo it would benefit from some more "user friendliness" opinions:

• First, just to re-iterate, I'm not absolutely sure whether right handed and left handed coordinate system is the correct term for this in 2D, we need a mathematician to confirm / or change to the correct term. I used this because it seemed "similar" to the cases in 3D.
• I suspect the documentation needs to make more clear when and why this flip might be needed, and why. At the moment it seems very unclear to users (it's not a simple concept, evidently).

Also, we should always consider the alternative - to keep the function the same, and simply mention this problem in the classref and documentation, and leave it to the user to flip where necessary (after all it's just a single operator). I would slightly lean towards making it explicit as in this PR, but opinions may differ on this.

This probably needs some more bikeshedding on how to best handle before proceeding, as it isn't clear cut.

[kinami-imai]

Handedness seems to be the correct term of art for 2D Cartesian coordinates: https://en.wikipedia.org/wiki/Cartesian_coordinate_system#Orientation_and_handedness