GLArrayData* VBO binding: Properly document and impl. bindBuffer(..) in detail w/ data sync within GLArrayHandle,

which also removed redundant code (VBO data sync and binding).

Refines commit 8582ece7dc7f65271b3184261697a542766d9864
           and f49f8e22953ed2426fd4264ee407e2dc3fc07cfc

2 files changed, 42 insertions, 14 deletions

diff --git a/src/jogl/classes/com/jogamp/opengl/util/GLArrayDataClient.java b/src/jogl/classes/com/jogamp/opengl/util/GLArrayDataClient.java
index 30fc0012b..af091d52b 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/GLArrayDataClient.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/GLArrayDataClient.java
@@ -124,33 +124,41 @@ public class GLArrayDataClient extends GLArrayDataWrapper implements GLArrayData
   // Data read access
   //
 
+  @Override
   public final boolean isVBOWritten() { return bufferWritten; }
 
+  @Override
   public final boolean sealed() { return sealed; }
   
+  @Override
   public final boolean enabled() { return bufferEnabled; }
 
   //
   // Data and GL state modification ..
   //
 
+  @Override
   public final void setVBOWritten(boolean written) { bufferWritten=written; }
 
+  @Override
   public void destroy(GL gl) {
     reset(gl);
     super.destroy(gl);
   }
 
+  @Override
   public void reset(GL gl) {
     enableBuffer(gl, false);
     reset();
   }
 
+  @Override
   public void seal(GL gl, boolean seal) {
     seal(seal);
     enableBuffer(gl, seal);
   }
 
+  @Override
   public void enableBuffer(GL gl, boolean enable) {
     if( enableBufferAlways || bufferEnabled != enable ) { 
         if(enable) {
@@ -172,12 +180,12 @@ public class GLArrayDataClient extends GLArrayDataWrapper implements GLArrayData
     }
   }
   
-  public void bindBuffer(GL gl, boolean bind) {
-      if(isVBO()) {
-          gl.glBindBuffer(getVBOTarget(), bind ? getVBOName() : 0);
-      }
+  @Override
+  public boolean bindBuffer(GL gl, boolean bind) {
+      return glArrayHandler.bindBuffer(gl, bind);
   }
   
+  @Override
   public void setEnableAlways(boolean always) {
     enableBufferAlways = always;
   }
@@ -186,6 +194,7 @@ public class GLArrayDataClient extends GLArrayDataWrapper implements GLArrayData
   // Data modification ..
   //
 
+  @Override
   public void reset() {
     if(buffer!=null) {
         buffer.clear();
@@ -195,6 +204,7 @@ public class GLArrayDataClient extends GLArrayDataWrapper implements GLArrayData
     this.bufferWritten=false;
   }
 
+  @Override
   public void seal(boolean seal)
   {
     if(sealed==seal) return;
@@ -211,12 +221,14 @@ public class GLArrayDataClient extends GLArrayDataWrapper implements GLArrayData
   }
 
 
+  @Override
   public void rewind() {
     if(buffer!=null) {
         buffer.rewind();
     }
   }
 
+  @Override
   public void padding(int doneInByteSize) {
     if ( buffer==null || sealed ) return;
     while(doneInByteSize<strideB) {
@@ -231,6 +243,7 @@ public class GLArrayDataClient extends GLArrayDataWrapper implements GLArrayData
    * This class buffer Class must match the arguments buffer class.
    * The arguments remaining elements must be a multiple of this arrays element stride.
    */
+  @Override
   public void put(Buffer v) {
     if ( sealed ) return;
     /** FIXME: isn't true for interleaved arrays !
@@ -241,28 +254,33 @@ public class GLArrayDataClient extends GLArrayDataWrapper implements GLArrayData
     Buffers.put(buffer, v);
   }
 
+  @Override
   public void putb(byte v) {
     if ( sealed ) return;
     growBufferIfNecessary(1);
     Buffers.putb(buffer, v);
   }
 
+  @Override
   public void puts(short v) {
     if ( sealed ) return;
     growBufferIfNecessary(1);
     Buffers.puts(buffer, v);
   }
 
+  @Override
   public void puti(int v) {
     if ( sealed ) return;
     growBufferIfNecessary(1);
     Buffers.puti(buffer, v);
   }
 
+  @Override
   public void putx(int v) {
     puti(v);
   }
 
+  @Override
   public void putf(float v) {
     if ( sealed ) return;
     growBufferIfNecessary(1);
diff --git a/src/jogl/classes/com/jogamp/opengl/util/GLArrayDataEditable.java b/src/jogl/classes/com/jogamp/opengl/util/GLArrayDataEditable.java
index 588e90d1e..9b04a48aa 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/GLArrayDataEditable.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/GLArrayDataEditable.java
@@ -14,7 +14,7 @@ import java.nio.*;
 public interface GLArrayDataEditable extends GLArrayData {
 
     public boolean sealed();
-    
+
     public boolean enabled();
 
     /**
@@ -45,12 +45,11 @@ public interface GLArrayDataEditable extends GLArrayData {
     public void seal(GL gl, boolean seal);
 
     /**
-     * <p>
      * Enables the buffer if <code>enable</code> is <code>true</code>, 
      * and transfers the data if required.
-     * In case {@link #isVBO() VBO is used}, it is bound accordingly for the data transfer and data association.
+     * In case {@link #isVBO() VBO is used}, it is bound accordingly for the data transfer and association,
+     * i.e. it issued {@link #bindBuffer(GL, boolean)}.
      * The VBO buffer is unbound when the method returns. 
-     * </p>
      * <p>
      * Disables the buffer if <code>enable</code> is <code>false</code>. 
      * </p>
@@ -67,15 +66,26 @@ public interface GLArrayDataEditable extends GLArrayData {
      * @see #setEnableAlways(boolean)
      */
     public void enableBuffer(GL gl, boolean enable);
-    
+
     /**
-     * In case {@link #isVBO() VBO is used}, the buffer is bound 
-     * if <code>bind</code> is <code>true</code>, otherwise the buffer is unbound.
+     * if <code>bind</code> is true and the data uses {@link #isVBO() VBO}, 
+     * the latter will be bound and data written to the GPU if required.
+     * <p>
+     * If  <code>bind</code> is false and the data uses {@link #isVBO() VBO},
+     * the latter will be unbound.
+     * </p>
+     * <p>
+     * This method is exposed to allow data VBO arrays, i.e. {@link GL#GL_ELEMENT_ARRAY_BUFFER},
+     * to be bounded and written while keeping the VBO bound. The latter is in contrast to {@link #enableBuffer(GL, boolean)},
+     * which leaves the VBO unbound, since it's not required for vertex attributes or pointers.
+     * </p>
      * 
-     * @param gl
-     * @param bind
+     * @param gl current GL object
+     * @param bind true if VBO shall be bound and data written, 
+     *        otherwise clear VBO binding. 
+     * @return true if data uses VBO and action was performed, otherwise false 
      */
-    public void bindBuffer(GL gl, boolean bind);
+    public boolean bindBuffer(GL gl, boolean bind);
 
     /**
      * Affects the behavior of 'enableBuffer'.