From 90a95e6f689b479f3c3ae3caf4e30447030c7682 Mon Sep 17 00:00:00 2001
From: Sven Gothel <sgothel@jausoft.com>
Date: Tue, 7 Mar 2023 17:56:08 +0100
Subject: GLArrayData: Promote sealed() from GLArrayDataEditable, to correctly
 being used for getElemCount() instead of 0==position, ... (API change)

API Change
- sealed() moved up from GLArrayDataEditable -> GLArrayData
- GLArrayDataWrapper is sealed by default
- getSizeInBytes() -> getByteCount()
- Semantics of getElemCount() and getByteCount()
  - Correctly use sealed() to switch from position to limit - instead of 0==position

Aligned method names:
- getElemCount()
- elemPosition()
- remainingElems()
- getElemCapacity()

to corresponding byte counts:
- getByteCount()
- bytePosition()
- remainingBytes()
- getByteCapacity()
---
 .../classes/com/jogamp/opengl/GLArrayData.java     | 100 +++++++++++++++++++--
 1 file changed, 91 insertions(+), 9 deletions(-)

(limited to 'src/jogl/classes/com/jogamp/opengl/GLArrayData.java')

diff --git a/src/jogl/classes/com/jogamp/opengl/GLArrayData.java b/src/jogl/classes/com/jogamp/opengl/GLArrayData.java
index d209addbb..65ef8c41e 100644
--- a/src/jogl/classes/com/jogamp/opengl/GLArrayData.java
+++ b/src/jogl/classes/com/jogamp/opengl/GLArrayData.java
@@ -28,7 +28,6 @@
 
 package com.jogamp.opengl;
 
-import java.io.PrintStream;
 import java.nio.Buffer;
 
 import com.jogamp.opengl.fixedfunc.GLPointerFunc;
@@ -173,26 +172,109 @@ public interface GLArrayData {
     public int getBytesPerComp();
 
     /**
-     * The current number of used elements.
+     * Returns true if data has been {@link {@link com.jogamp.opengl.util.GLArrayDataEditable#seal(boolean) sealed} (flipped to read), otherwise false (writing mode).
+     *
+     * @see com.jogamp.opengl.util.GLArrayDataEditable#seal(boolean)
+     * @see com.jogamp.opengl.util.GLArrayDataEditable#seal(GL, boolean)
+     */
+    public boolean sealed();
+
+    /**
+     * Returns the element position (written elements) if not {@link #sealed()} or
+     * the element limit (available to read) after {@link #sealed()} (flip).
      * <p>
      * On element consist out of {@link #getCompsPerElem()} components.
      * </p>
-     * In case the buffer's position is 0 (sealed, flipped), it's based on it's limit instead of it's position.
+     * @see #sealed()
+     * @see #getByteCount()
+     * @see #elemPosition()
+     * @see #remainingElems()
+     * @see #getElemCapacity()
      */
     public int getElemCount();
 
     /**
-     * The currently used size in bytes.<br>
-     * In case the buffer's position is 0 (sealed, flipped), it's based on it's limit instead of it's position.
+     * Returns the element position.
+     * <p>
+     * On element consist out of {@link #getCompsPerElem()} components.
+     * </p>
+     * @see #bytePosition()
+     * @see #getElemCount()
+     * @see #remainingElems()
+     * @see #getElemCapacity()
+     */
+    public int elemPosition();
+
+    /**
+     * The current number of remaining elements.
+     * <p>
+     * On element consist out of {@link #getCompsPerElem()} components.
+     * </p>
+     * Returns the number of elements between the current position and the limit, i.e. remaining elements to write in this buffer.
+     * @see #remainingBytes()
+     * @see #getElemCount()
+     * @see #elemPosition()
+     * @see #getElemCapacity()
+     */
+    public int remainingElems();
+
+    /**
+     * Return the element capacity.
+     * <p>
+     * On element consist out of {@link #getCompsPerElem()} components.
+     * </p>
+     * @see #getByteCapacity()
+     * @see #getElemCount()
+     * @see #elemPosition()
+     * @see #remainingElems()
+     */
+    public int getElemCapacity();
+
+    /**
+     * Returns the byte position (written elements) if not {@link #sealed()} or
+     * the byte limit (available to read) after {@link #sealed()} (flip).
+     * @see #sealed()
+     * @see #getElemCount()
+     * @see #bytePosition()
+     * @see #remainingBytes()
+     * @see #getByteCapacity()
+     */
+    public int getByteCount();
+
+    /**
+     * Returns the bytes position.
+     * @see #elemPosition()
+     * @see #getByteCount()
+     * @see #remainingElems()
+     * @see #getElemCapacity()
+     */
+    public int bytePosition();
+
+    /**
+     * The current number of remaining bytes.
+     * <p>
+     * Returns the number of bytes between the current position and the limit, i.e. remaining bytes to write in this buffer.
+     * </p>
+     * @see #remainingElems()
+     * @see #getByteCount()
+     * @see #bytePosition()
+     * @see #getByteCapacity()
      */
-    public int getSizeInBytes();
+    public int remainingBytes();
 
     /**
-     * The current capacity in bytes.
+     * Return the capacity in bytes.
+     * @see #getElemCapacity()
+     * @see #getByteCount()
+     * @see #bytePosition()
+     * @see #remainingBytes()
      */
-    public int getCapacityInBytes();
+    public int getByteCapacity();
 
-    public void printStats(final PrintStream out);
+    /** Returns a string with detailed buffer fill stats. */
+    public String fillStatsToString();
+    /** Returns a string with detailed buffer element stats, i.e. sealed, count, position, remaining, limit and capacity.  */
+    public String elemStatsToString();
 
     /**
      * True, if GL shall normalize fixed point data while converting
-- 
cgit v1.2.3