Methods in Gemetry2D don't explain how to use is_polygon_clockwise to tell boundaries from holes

[hatsoptional]

Your Godot version:

4.3

Issue description:

There are some methods in the Geometry2D doc page (see URLs below) that return an Array[PackedVector2Array] with this indication:

The operation may result in an outer polygon (boundary) and inner polygon (hole) produced which could be distinguished by calling is_polygon_clockwise

but without telling how to use the result from is_polygon_clockwise to distinguish boundaries from holes.

It would be less confusing to explicitly state which convention is used by Geometry2D: are clockwise polygons used to represent holes or boundaries?

Looking through the geometry2d.cpp source, it looks like the implementation relies on the Clipper2 Lib that states:

Clipping closed paths:

Clipping operations will always return Positive oriented solutions (unless the Clipper object's ReverseSolution property has been enabled). This means that outer polygon contours will wind anti-clockwise (in Cartesian coordinates), and inner hole contours will wind clockwise.

Hoping I got everything right, the indication of the methods listed below could be changed to this:

The operation may result in an outer polygon (boundary) and inner polygon (hole) produced which could be distinguished by calling is_polygon_clockwise and checking if the result is true (the polygon is a boundary) or false (the polygon is a hole).

The proposed description already flips the results of is_polygon_clockwise to adapt the Clipper2 Cartesian coordinates in the expected "y+ is down" screen coordinates.

URL to the documentation page (if already existing): https://docs.godotengine.org/en/stable/classes/class_geometry2d.html#class-geometry2d-method-clip-polygons https://docs.godotengine.org/en/stable/classes/class_geometry2d.html#class-geometry2d-method-exclude-polygons https://docs.godotengine.org/en/stable/classes/class_geometry2d.html#class-geometry2d-method-intersect-polygons https://docs.godotengine.org/en/stable/classes/class_geometry2d.html#class-geometry2d-method-merge-polygons https://docs.godotengine.org/en/stable/classes/class_geometry2d.html#class-geometry2d-method-offset-polygon https://docs.godotengine.org/en/stable/classes/class_geometry2d.html#class-geometry2d-method-offset-polyline

[hatsoptional]

After a bit of experimentation, it seems that there's no fixed convention, but the results depend on the winding of the input polygon:

• if the input polygon is clockwise, the resulting boundaries are clockwise and holes are counter-clockwise
• if the input polygon is counter-clockwise, the resulting boundaries are counter-clockwise and holes are clockwise

So a new proposal would be:

The operation may result in an outer polygon (boundary) and inner polygon (hole) produced which could be distinguished by calling is_polygon_clockwise. Boudaries will have the same winding direction of the input polygon and holes will have the opposite direction.

If someone with more experience on the Geometry2D classs can confirm that this is correct, I will open a PR.