Graph GLRegion/TextRegionUtil: Enhance pre-determination of buffer-size, increase default initial 16->64 (unsued)

- Region.countOutlineShape(..) now returns unpatched 3*triangle value for indices, avoiding grow
- TextRegionUtil.addStringToRegion() uses countStringRegion(..) per default
- Added GLRegion.create(.., OutlineShape) for convenience, using Region.countOutlineShape(..)
- Refined API doc
-

3 files changed, 93 insertions, 33 deletions

diff --git a/src/jogl/classes/com/jogamp/graph/curve/Region.java b/src/jogl/classes/com/jogamp/graph/curve/Region.java
index 820911bbf..28ac1a134 100644
--- a/src/jogl/classes/com/jogamp/graph/curve/Region.java
+++ b/src/jogl/classes/com/jogamp/graph/curve/Region.java
@@ -236,27 +236,32 @@ public abstract class Region {
     public final boolean usesI32Idx() { return this.use_int32_idx; }
 
     /**
-     * Allow the renderer buffers to pre-emptively grow for given vertices- and index counts.
-     * @param verticesCount number of vertices to hold
-     * @param indicesCount number of indices to hold
+     * Increase the renderer buffers if necessary to add given counts of vertices- and index elements.
+     * <p>
+     * Buffers will not change if remaining free slots, capacity less position, satisfy count elements.
+     * </p>
+     * @param verticesCount number of vertex elements to add if necessary
+     * @param indicesCount number of index elements to add if necessary
+     * @return true if buffer size has changed, i.e. grown. Otherwise false.
      * @see #setBufferCapacity(int, int)
      * @see #countOutlineShape(OutlineShape, int[])
      * @see #countOutlineShapes(List, int[])
      */
-    public abstract void growBuffer(int verticesCount, int indicesCount);
+    public abstract boolean growBuffer(int verticesCount, int indicesCount);
 
     /**
      * Set the renderer buffers pre-emptively for given vertices- and index counts.
      * <p>
-     * If the buffers already exceeds given numbers, the buffers are unchanged.
+     * Buffers will not change if given count elements is lower or equal current capacity.
      * </p>
      * @param verticesCount number of vertices to hold
      * @param indicesCount number of indices to hold
+     * @return true if buffer size has changed, i.e. grown. Otherwise false.
      * @see #growBuffer(int, int)
      * @see #countOutlineShape(OutlineShape, int[])
      * @see #countOutlineShapes(List, int[])
      */
-    public abstract void setBufferCapacity(int verticesCount, int indicesCount);
+    public abstract boolean setBufferCapacity(int verticesCount, int indicesCount);
 
     protected abstract void pushVertex(final Vec3f coords, final Vec3f texParams, Vec4f rgba);
     protected abstract void pushVertices(final Vec3f coords1, final Vec3f coords2, final Vec3f coords3,
@@ -487,18 +492,21 @@ public abstract class Region {
      * </p>
      * @param shape the {@link OutlineShape} to count
      * @param vertIndexCount the int[2] storage where the counted vertices and indices are added, vertices at [0] and indices at [1]
+     * @return the given int[2] storage for chaining
      * @see #setBufferCapacity(int, int)
      * @see #growBuffer(int, int)
      */
-    public static final void countOutlineShape(final OutlineShape shape, final int[/*2*/] vertIndexCount) {
+    public static final int[] countOutlineShape(final OutlineShape shape, final int[/*2*/] vertIndexCount) {
+        if( null == shape ) {
+            return vertIndexCount;
+        }
         final List<Triangle> trisIn = shape.getTriangles(OutlineShape.VerticesState.QUADRATIC_NURBS);
         final ArrayList<Vertex> vertsIn = shape.getVertices();
         {
-            final int verticeCount = vertsIn.size() + shape.getAddedVerticeCount();
-            final int indexCount = trisIn.size() * 3;
-            vertIndexCount[0] += verticeCount;
-            vertIndexCount[1] += Math.min( Math.ceil(verticeCount * 0.9), indexCount );
+            vertIndexCount[0] += vertsIn.size() + shape.getAddedVerticeCount(); // verticesCount
+            vertIndexCount[1] += trisIn.size() * 3; // indicesCount
         }
+        return vertIndexCount;
     }
 
     /**
@@ -510,13 +518,15 @@ public abstract class Region {
      * </p>
      * @param shapes list of {@link OutlineShape} to count
      * @param vertIndexCount the int[2] storage where the counted vertices and indices are added, vertices at [0] and indices at [1]
+     * @return the given int[2] storage for chaining
      * @see #setBufferCapacity(int, int)
      * @see #growBuffer(int, int)
      */
-    public static final void countOutlineShapes(final List<OutlineShape> shapes, final int[/*2*/] vertIndexCount) {
+    public static final int[] countOutlineShapes(final List<OutlineShape> shapes, final int[/*2*/] vertIndexCount) {
         for (int i = 0; i < shapes.size(); i++) {
             countOutlineShape(shapes.get(i), vertIndexCount);
         }
+        return vertIndexCount;
     }
 
     /**
diff --git a/src/jogl/classes/com/jogamp/graph/curve/opengl/GLRegion.java b/src/jogl/classes/com/jogamp/graph/curve/opengl/GLRegion.java
index db3a935cf..9117d1aee 100644
--- a/src/jogl/classes/com/jogamp/graph/curve/opengl/GLRegion.java
+++ b/src/jogl/classes/com/jogamp/graph/curve/opengl/GLRegion.java
@@ -84,12 +84,12 @@ public abstract class GLRegion extends Region {
     /**

      * Default initial vertices count {@value}, assuming small sized shapes.

      */

-    public static final int defaultVerticesCount = 16;

+    public static final int defaultVerticesCount = 64;

 

     /**

      * Default initial indices count {@value}, assuming small sized shapes.

      */

-    public static final int defaultIndicesCount = 16;

+    public static final int defaultIndicesCount = 64;

 

     // private static final float growthFactor = 1.2f; // avg +5% size but 15% more overhead (34% total)

     protected static final float growthFactor = GLArrayDataClient.DEFAULT_GROWTH_FACTOR; // avg +20% size, but 15% less CPU overhead compared to 1.2 (19% total)

@@ -121,7 +121,7 @@ public abstract class GLRegion extends Region {
     }

 

     /**

-     * Create a GLRegion using the passed render mode

+     * Create a GLRegion using the passed render mode and default initial buffer sizes {@link #defaultVerticesCount} and {@link #defaultIndicesCount}.

      *

      * <p> In case {@link Region#VBAA_RENDERING_BIT} is being requested the default texture unit

      * {@link Region#DEFAULT_TWO_PASS_TEXTURE_UNIT} is being used.</p>

@@ -135,6 +135,22 @@ public abstract class GLRegion extends Region {
 

     /**

      * Create a GLRegion using the passed render mode and pre-calculating its buffer sizes

+     * using {@link Region#countOutlineShape(OutlineShape, int[])}.

+     *

+     * <p> In case {@link Region#VBAA_RENDERING_BIT} is being requested the default texture unit

+     * {@link Region#DEFAULT_TWO_PASS_TEXTURE_UNIT} is being used.</p>

+     * @param glp intended GLProfile to use. Instance may use higher OpenGL features if indicated by GLProfile.

+     * @param renderModes bit-field of modes, e.g. {@link Region#VARWEIGHT_RENDERING_BIT}, {@link Region#VBAA_RENDERING_BIT}

+     * @param colorTexSeq optional {@link TextureSequence} for {@link Region#COLORTEXTURE_RENDERING_BIT} rendering mode.

+     * @param shape the {@link OutlineShape} used to determine {@link GLRegion}'s buffer sizes via {@link Region#countOutlineShape(OutlineShape, int[])}

+     */

+    public static GLRegion create(final GLProfile glp, final int renderModes, final TextureSequence colorTexSeq, final OutlineShape shape) {

+        final int[/*2*/] vertIndexCount = Region.countOutlineShape(shape, new int[2]);

+        return GLRegion.create(glp, renderModes, colorTexSeq, vertIndexCount[0], vertIndexCount[1]);

+    }

+

+    /**

+     * Create a GLRegion using the passed render mode and pre-calculating its buffer sizes

      * using given font's {@link Font#processString(com.jogamp.graph.font.Font.GlyphVisitor2, CharSequence)}

      * to {@link #countOutlineShape(OutlineShape, int[])}.

      *

@@ -213,39 +229,47 @@ public abstract class GLRegion extends Region {
     }

 

     @Override

-    public final void growBuffer(final int verticesCount, final int indicesCount) {

+    public final boolean growBuffer(final int verticesCount, final int indicesCount) {

         boolean grown = false;

         if( curIndicesCap < indicesBuffer.elemPosition() + indicesCount ) {

-            // System.err.printf("XXX Buffer grow - Indices: %d < ( %d = %d + %d ); Status: %s%n",

-            //       curIndicesCap, indicesBuffer.elemPosition() + indicesCount, indicesBuffer.elemPosition(), indicesCount, indicesBuffer.elemStatsToString());

+            System.err.printf("XXX Buffer grow - Indices: %d < ( %d = %d + %d ); Status: %s%n",

+                   curIndicesCap, indicesBuffer.elemPosition() + indicesCount, indicesBuffer.elemPosition(), indicesCount, indicesBuffer.elemStatsToString());

             indicesBuffer.growIfNeeded(indicesCount * indicesBuffer.getCompsPerElem());

-            // System.err.println("grew.indices 0x"+Integer.toHexString(hashCode())+": "+curIndicesCap+" -> "+indicesBuffer.getElemCapacity()+", "+indicesBuffer.elemStatsToString());

+            System.err.println("grew.indices 0x"+Integer.toHexString(hashCode())+": "+curIndicesCap+" -> "+indicesBuffer.getElemCapacity()+", "+indicesBuffer.elemStatsToString());

+            Thread.dumpStack();

             curIndicesCap = indicesBuffer.getElemCapacity();

             grown = true;

         }

         if( curVerticesCap < vpc_ileave.elemPosition() + verticesCount ) {

-            // System.err.printf("XXX Buffer grow - Verices: %d < ( %d = %d + %d ); Status: %s%n",

-            //        curVerticesCap, gca_VerticesAttr.elemPosition() + verticesCount, gca_VerticesAttr.elemPosition(), verticesCount, gca_VerticesAttr.elemStatsToString());

+            System.err.printf("XXX Buffer grow - Verices: %d < ( %d = %d + %d ); Status: %s%n",

+                    curVerticesCap, gca_VerticesAttr.elemPosition() + verticesCount, gca_VerticesAttr.elemPosition(), verticesCount, gca_VerticesAttr.elemStatsToString());

             vpc_ileave.growIfNeeded(verticesCount * vpc_ileave.getCompsPerElem());

-            // System.err.println("grew.vertices 0x"+Integer.toHexString(hashCode())+": "+curVerticesCap+" -> "+gca_VerticesAttr.getElemCapacity()+", "+gca_VerticesAttr.elemStatsToString());

+            System.err.println("grew.vertices 0x"+Integer.toHexString(hashCode())+": "+curVerticesCap+" -> "+gca_VerticesAttr.getElemCapacity()+", "+gca_VerticesAttr.elemStatsToString());

             curVerticesCap = vpc_ileave.getElemCapacity();

             grown = true;

         }

         if( grown ) {

             ++growCount;

+            return true;

+        } else {

+            return false;

         }

     }

 

     @Override

-    public final void setBufferCapacity(final int verticesCount, final int indicesCount) {

+    public final boolean setBufferCapacity(final int verticesCount, final int indicesCount) {

+        boolean grown = false;

         if( curIndicesCap < indicesCount ) {

             indicesBuffer.reserve(indicesCount);

             curIndicesCap = indicesBuffer.getElemCapacity();

+            grown = true;

         }

         if( curVerticesCap < verticesCount ) {

             vpc_ileave.reserve(verticesCount);

             curVerticesCap = vpc_ileave.getElemCapacity();

+            grown = true;

         }

+        return grown;

     }

 

     @Override

@@ -409,6 +433,9 @@ public abstract class GLRegion extends Region {
             indicesBuffer.destroy(gl);

             indicesBuffer = null;

         }

+        curVerticesCap = 0;

+        curIndicesCap = 0;

+        growCount = 0;

         destroyImpl(gl);

     }

     protected abstract void destroyImpl(final GL2ES2 gl);

diff --git a/src/jogl/classes/com/jogamp/graph/curve/opengl/TextRegionUtil.java b/src/jogl/classes/com/jogamp/graph/curve/opengl/TextRegionUtil.java
index 8e41ddaa4..428bb350d 100644
--- a/src/jogl/classes/com/jogamp/graph/curve/opengl/TextRegionUtil.java
+++ b/src/jogl/classes/com/jogamp/graph/curve/opengl/TextRegionUtil.java
@@ -76,7 +76,7 @@ public class TextRegionUtil {
      * Origin of rendered text is 0/0 at bottom left.
      * </p>
      * <p>
-     * The region buffer's size is grown by pre-calculating required string size via {@link #countStringRegion(Font, CharSequence, int[])}.
+     * The region buffer's size is grown by pre-calculating required size via {@link #countStringRegion(Font, CharSequence, int[])}.
      * </p>
      * @param region the {@link GLRegion} sink
      * @param font the target {@link Font}
@@ -100,7 +100,7 @@ public class TextRegionUtil {
      * Origin of rendered text is 0/0 at bottom left.
      * </p>
      * <p>
-     * The region buffer's size is grown by pre-calculating required string size via {@link #countStringRegion(Font, CharSequence, int[])}.
+     * The region buffer's size is grown by pre-calculating required size via {@link #countStringRegion(Font, CharSequence, int[])}.
      * </p>
      * @param region the {@link GLRegion} sink
      * @param font the target {@link Font}
@@ -117,9 +117,31 @@ public class TextRegionUtil {
         return addStringToRegion(true /* preGrowRegion */, region, font, transform, str, rgbaColor, temp1, temp2);
     }
 
-    private static AABBox addStringToRegion(final boolean preGrowRegion, final Region region, final Font font, final AffineTransform transform,
-                                            final CharSequence str, final Vec4f rgbaColor,
-                                            final AffineTransform temp1, final AffineTransform temp2) {
+    /**
+     * Add the string in 3D space w.r.t. the font in font em-size [0..1] at the end of the {@link GLRegion}
+     * while passing the progressed {@link AffineTransform}.
+     * <p>
+     * The shapes added to the GLRegion are in font em-size [0..1], but can be adjusted with the given transform, progressed and passed to the visitor.
+     * </p>
+     * <p>
+     * Origin of rendered text is 0/0 at bottom left.
+     * </p>
+     * <p>
+     * Depending on `preGrowRegion`, the region buffer's size is grown by pre-calculating required size via {@link #countStringRegion(Font, CharSequence, int[])}.
+     * </p>
+     * @param preGrowRegion if true, utilizes {@link #countStringRegion(Font, CharSequence, int[])} to pre-calc required buffer size, otherwise not.
+     * @param region the {@link GLRegion} sink
+     * @param font the target {@link Font}
+     * @param transform optional given transform
+     * @param str string text
+     * @param rgbaColor if {@link Region#hasColorChannel()} RGBA color must be passed, otherwise value is ignored.
+     * @param temp1 temporary AffineTransform storage, mandatory
+     * @param temp2 temporary AffineTransform storage, mandatory
+     * @return the bounding box of the given string by taking each glyph's font em-sized [0..1] OutlineShape into account.
+     */
+    public static AABBox addStringToRegion(final boolean preGrowRegion, final Region region, final Font font, final AffineTransform transform,
+                                           final CharSequence str, final Vec4f rgbaColor,
+                                           final AffineTransform temp1, final AffineTransform temp2) {
         final Font.GlyphVisitor visitor = new Font.GlyphVisitor() {
             @Override
             public void visit(final char symbol, final Glyph glyph, final AffineTransform t) {
@@ -130,8 +152,7 @@ public class TextRegionUtil {
             }
         };
         if( preGrowRegion ) {
-            final int[] vertIndCount = { 0, 0 };
-            countStringRegion(font, str, vertIndCount);
+            final int[] vertIndCount = countStringRegion(font, str, new int[2]);
             region.growBuffer(vertIndCount[0], vertIndCount[1]);
         }
         return font.processString(visitor, transform, str, temp1, temp2);
@@ -145,17 +166,19 @@ public class TextRegionUtil {
      * @param font the target {@link Font}
      * @param str string text
      * @param vertIndexCount the int[2] storage where the counted vertices and indices are added, vertices at [0] and indices at [1]
+     * @return the given int[2] storage for chaining
      * @see Region#setBufferCapacity(int, int)
      * @see Region#growBuffer(int, int)
      * @see #drawString3D(GL2ES2, GLRegion, RegionRenderer, Font, CharSequence, float[], int[], AffineTransform, AffineTransform)
      */
-    public static void countStringRegion(final Font font, final CharSequence str, final int[/*2*/] vertIndexCount) {
+    public static int[] countStringRegion(final Font font, final CharSequence str, final int[/*2*/] vertIndexCount) {
         final Font.GlyphVisitor2 visitor = new Font.GlyphVisitor2() {
             @Override
             public final void visit(final char symbol, final Font.Glyph glyph) {
                 Region.countOutlineShape(glyph.getShape(), vertIndexCount);
             } };
         font.processString(visitor, str);
+        return vertIndexCount;
     }
 
     /**
@@ -259,7 +282,7 @@ public class TextRegionUtil {
     /**
      * Try using {@link #drawString3D(GL2ES2, GLRegion, RegionRenderer, Font, CharSequence, float[], int[], AffineTransform, AffineTransform)} to reuse {@link AffineTransform} instances.
      * <p>
-     * The region buffer's size is grown by pre-calculating required string size via {@link #countStringRegion(Font, CharSequence, int[])}.
+     * The region buffer's size is grown by pre-calculating required size via {@link #countStringRegion(Font, CharSequence, int[])}.
      * </p>
      */
     public static AABBox drawString3D(final GL2ES2 gl, final GLRegion region, final RegionRenderer renderer,
@@ -279,7 +302,7 @@ public class TextRegionUtil {
      * Origin of rendered text is 0/0 at bottom left.
      * </p>
      * <p>
-     * The region buffer's size is grown by pre-calculating required string size via {@link #countStringRegion(Font, CharSequence, int[])}.
+     * The region buffer's size is grown by pre-calculating required size via {@link #countStringRegion(Font, CharSequence, int[])}.
      * </p>
      * @param gl the current GL state
      * @param region