Graph: Fix Loop.initFromPolyline()'s Winding determination, document Winding rules for OutlineShape and add get/setWinding in Outline

Loop.initFromPolyline()'s Winding determination used a 3-point triangle-area method,
which is insufficent for complex shapes like serif 'g' or 'æ'.
Solved by using the whole area over the Outline shape.

Note: Loop.initFromPolyline()'s Winding determination is used to convert
the inner shape or holes to CW only.
Therefor the outter bondary shapes must be CCW.

This details has been documented within OutlineShape, anchor 'windingrules'.
Since the conversion of 'CCW -> CW' for inner shapes or holes is covered,
a safe user path would be to completely create CCW shapes.
However, this has not been hardcoded and is left to the user.

Impact: Fixes rendering serif 'g' or 'æ'.

The enhanced unit test TestTextRendererNEWT01 produces snapshots for all fonts within FontSet01.
While it shows proper rendering of the single Glyphs it exposes another Region/Curve Renderer bug,
i.e. sort-of a Region overflow crossing over from the box-end to the start.

1 files changed, 23 insertions, 7 deletions

diff --git a/src/jogl/classes/com/jogamp/opengl/math/VectorUtil.java b/src/jogl/classes/com/jogamp/opengl/math/VectorUtil.java
index 3ee504a29..d7e72e245 100644
--- a/src/jogl/classes/com/jogamp/opengl/math/VectorUtil.java
+++ b/src/jogl/classes/com/jogamp/opengl/math/VectorUtil.java
@@ -888,25 +888,35 @@ public final class VectorUtil {
         return triAreaVec2(a,b,c) > 0;
     }
 
-    /** Compute the winding of given points
+    /**
+     * Compute the winding of the 3 given points
+     * <p>
+     * Consider using {@link #getWinding(ArrayList)} using the {@link #area(ArrayList)} function over all points
+     * on complex shapes for a reliable result!
+     * </p>
      * @param a first vertex
      * @param b second vertex
      * @param c third vertex
-     * @return Winding
+     * @return {@link Winding#CCW} or {@link Winding#CW}
+     * @see #getWinding(ArrayList)
      */
     public static Winding getWinding(final Vert2fImmutable a, final Vert2fImmutable b, final Vert2fImmutable c) {
         return triAreaVec2(a,b,c) > 0 ? Winding.CCW : Winding.CW ;
     }
 
-    /** Computes the area of a list of vertices to check if ccw
+    /**
+     * Computes the area of a list of vertices.
+     * <p>
+     * This method is utilized e.g. to reliably compute the {@link Winding} of complex shapes.
+     * </p>
      * @param vertices
      * @return positive area if ccw else negative area value
+     * @see #getWinding(ArrayList)
      */
     public static float area(final ArrayList<? extends Vert2fImmutable> vertices) {
         final int n = vertices.size();
         float area = 0.0f;
-        for (int p = n - 1, q = 0; q < n; p = q++)
-        {
+        for (int p = n - 1, q = 0; q < n; p = q++) {
             final float[] pCoord = vertices.get(p).getCoord();
             final float[] qCoord = vertices.get(q).getCoord();
             area += pCoord[0] * qCoord[1] - qCoord[0] * pCoord[1];
@@ -914,9 +924,15 @@ public final class VectorUtil {
         return area;
     }
 
-    /** Compute the  general winding of the vertices
+    /**
+     * Compute the winding using the {@link #area(ArrayList)} function over all vertices for complex shapes.
+     * <p>
+     * Uses the {@link #area(ArrayList)} function over all points
+     * on complex shapes for a reliable result!
+     * </p>
      * @param vertices array of Vertices
-     * @return CCW or CW {@link Winding}
+     * @return {@link Winding#CCW} or {@link Winding#CW}
+     * @see #area(ArrayList)
      */
     public static Winding getWinding(final ArrayList<? extends Vert2fImmutable> vertices) {
         return area(vertices) >= 0 ? Winding.CCW : Winding.CW ;