1 files changed, 61 insertions, 13 deletions

diff --git a/src/jogl/classes/javax/media/opengl/GLArrayData.java b/src/jogl/classes/javax/media/opengl/GLArrayData.java
index 7c56b53cb..97f58a92a 100644
--- a/src/jogl/classes/javax/media/opengl/GLArrayData.java
+++ b/src/jogl/classes/javax/media/opengl/GLArrayData.java
@@ -30,6 +30,8 @@ package javax.media.opengl;
 
 import java.nio.Buffer;
 
+import javax.media.opengl.fixedfunc.GLPointerFunc;
+
 /**
  *
  * The total number of bytes hold by the referenced buffer is:
@@ -38,6 +40,19 @@ import java.nio.Buffer;
  */
 public interface GLArrayData {
     /**
+     * Implementation and type dependent object association.
+     * <p>
+     * One currently known use case is to associate a {@link com.jogamp.opengl.util.glsl.ShaderState ShaderState}
+     * to an GLSL aware vertex attribute object, allowing to use the ShaderState to handle it's
+     * data persistence, location and state change.<br/>
+     * This is implicitly done via {@link com.jogamp.opengl.util.glsl.ShaderState#ownAttribute(GLArrayData, boolean) shaderState.ownAttribute(GLArrayData, boolean)}.
+     * </p>
+     * @param obj implementation and type dependent association
+     * @param enable pass true to enable the association and false to disable it.
+     */
+    public void associate(Object obj, boolean enable);
+
+    /**
      * Returns true if this data set is intended for a GLSL vertex shader attribute,
      * otherwise false, ie intended for fixed function vertex pointer
      */
@@ -47,10 +62,10 @@ public interface GLArrayData {
      * The index of the predefined array index, see list below,
      * or -1 in case of a shader attribute array.
      *
-     * @see javax.media.opengl.GL2#GL_VERTEX_ARRAY
-     * @see javax.media.opengl.GL2#GL_NORMAL_ARRAY
-     * @see javax.media.opengl.GL2#GL_COLOR_ARRAY
-     * @see javax.media.opengl.GL2#GL_TEXTURE_COORD_ARRAY
+     * @see GLPointerFunc#GL_VERTEX_ARRAY
+     * @see GLPointerFunc#GL_NORMAL_ARRAY
+     * @see GLPointerFunc#GL_COLOR_ARRAY
+     * @see GLPointerFunc#GL_TEXTURE_COORD_ARRAY
      */
     public int getIndex();
 
@@ -61,6 +76,11 @@ public interface GLArrayData {
 
     /**
      * Set a new name for this array.
+     * <p>
+     * This clears the location, i.e. sets it to -1.
+     * </p>
+     * @see #setLocation(int)
+     * @see #setLocation(GL2ES2, int)
      */
     public void setName(String newName);
 
@@ -72,12 +92,35 @@ public interface GLArrayData {
     public int getLocation();
 
     /**
-     * Sets the determined location of the shader attribute
-     * This is usually done within ShaderState.
+     * Sets the given location of the shader attribute
      *
+     * @return the given location
      * @see com.jogamp.opengl.util.glsl.ShaderState#vertexAttribPointer(GL2ES2, GLArrayData)
      */
-    public void setLocation(int v);
+    public int setLocation(int v);
+
+    /**
+     * Retrieves the location of the shader attribute from the linked shader program.
+     * <p>
+     * No validation is performed within the implementation.
+     * </p>
+     * @param gl
+     * @param program
+     * @return &ge;0 denotes a valid attribute location as found and used in the given shader program.
+     *         &lt;0 denotes an invalid location, i.e. not found or used in the given shader program.
+     */
+    public int setLocation(GL2ES2 gl, int program);
+
+    /**
+     * Binds the location of the shader attribute to the given location for the unlinked shader program.
+     * <p>
+     * No validation is performed within the implementation.
+     * </p>
+     * @param gl
+     * @param program
+     * @return the given location
+     */
+    public int setLocation(GL2ES2 gl, int program, int location);
 
     /**
      * Determines whether the data is server side (VBO) and enabled,
@@ -107,7 +150,7 @@ public interface GLArrayData {
      */
     public int getVBOTarget();
 
-    
+
     /**
      * The Buffer holding the data, may be null if a GPU buffer without client bound data
      */
@@ -136,7 +179,7 @@ public interface GLArrayData {
      * In case the buffer's position is 0 (sealed, flipped), it's based on it's limit instead of it's position.
      */
     public int getElementCount();
-    
+
     /**
      * 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.
@@ -144,16 +187,21 @@ public interface GLArrayData {
     public int getSizeInBytes();
 
     /**
-     * True, if GL shall normalize fixed point data while converting 
-     * them into float
+     * True, if GL shall normalize fixed point data while converting
+     * them into float.
+     * <p>
+     * Default behavior (of the fixed function pipeline) is <code>true</code>
+     * for fixed point data type and <code>false</code> for floating point data types.
+     * </p>
      */
     public boolean getNormalized();
 
-    /** 
+    /**
      * @return the byte offset between consecutive components
-     */      
+     */
     public int getStride();
 
+    @Override
     public String toString();
 
     public void destroy(GL gl);