TileRenderer*: TileRendererNotify -> TileRendererListener w/ clarifying functionality (reshapeTile(..), ..); Only process GLEventListener impl. TileRendererListener; attachToAutoDrawable -> attachAutoDrawable, etc.

-TileRendererNotify -> TileRendererListener
  - Added methods:
    - void reshapeTile(TileRendererBase tr,int tileX, int tileY, int tileWidth, int tileHeight, int imageWidth, int imageHeight);
    - void startTileRendering(TileRendererBase tr);
    - void endTileRendering(TileRendererBase tr);

  allowing to clarify user code and API specification,
  i.e. TR only processes GLEventListener which impl. TileRendererListener.

  This also allows simplifying the API doc, while having a more descriptive
  reshape method focusing solely on tile rendering.

  Further more, the start/end TR methods allow certain GL related actions
  while the context is current before and after iterating through the tiles.
  This is even used for RandomTileRenderer (one tile only), to allow
  to reuse same TileRendererListener for diff TRs.

- Fix language, attach and detach usage was vice versa. We do attach an GLAutoDrawable to a TR
  - attachToAutoDrawable -> attachAutoDrawable
  - detachFromAutoDrawable -> detachAutoDrawable

- Adapted unit tests.

3 files changed, 165 insertions, 62 deletions

diff --git a/src/jogl/classes/com/jogamp/opengl/util/RandomTileRenderer.java b/src/jogl/classes/com/jogamp/opengl/util/RandomTileRenderer.java
index 03b782ff8..dcf229716 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/RandomTileRenderer.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/RandomTileRenderer.java
@@ -201,7 +201,7 @@ public class RandomTileRenderer extends TileRendererBase {
     /**
      * Rendering one tile, by simply calling {@link GLAutoDrawable#display()}.
      * 
-     * @throws IllegalStateException if no {@link GLAutoDrawable} is {@link #attachToAutoDrawable(GLAutoDrawable) attached}
+     * @throws IllegalStateException if no {@link GLAutoDrawable} is {@link #attachAutoDrawable(GLAutoDrawable) attached}
      *                               or imageSize is not set
      */
     public void display(int tX, int tY, int tWidth, int tHeight) throws IllegalStateException {
diff --git a/src/jogl/classes/com/jogamp/opengl/util/TileRenderer.java b/src/jogl/classes/com/jogamp/opengl/util/TileRenderer.java
index 266909470..7c57627e9 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/TileRenderer.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/TileRenderer.java
@@ -137,7 +137,7 @@ public class TileRenderer extends TileRendererBase {
     private int rowOrder = TR_BOTTOM_TO_TOP;
     private int rows;
     private int columns;
-    private int currentTile = -1;
+    private int currentTile = -1; 
     private int currentRow;
     private int currentColumn;
     private int offsetX;
@@ -269,6 +269,8 @@ public class TileRenderer extends TileRendererBase {
         assert rows >= 0;
     }
 
+    /* pp */ final int getCurrentTile() { return currentTile; }
+    
     /** 
      * Returns <code>true</code> if all tiles have been rendered or {@link #setup()}
      * has not been called, otherwise <code>false</code>.
diff --git a/src/jogl/classes/com/jogamp/opengl/util/TileRendererBase.java b/src/jogl/classes/com/jogamp/opengl/util/TileRendererBase.java
index 74e1df316..5b3644f59 100644
--- a/src/jogl/classes/com/jogamp/opengl/util/TileRendererBase.java
+++ b/src/jogl/classes/com/jogamp/opengl/util/TileRendererBase.java
@@ -67,9 +67,9 @@ import jogamp.opengl.Debug;
  * after calling {@link #beginTile(GL)}, See {@link #beginTile(GL)}.
  * </p>
  * <p> 
- * If {@link #attachToAutoDrawable(GLAutoDrawable) attaching to} an {@link GLAutoDrawable},
- * the {@link GLEventListener#reshape(GLAutoDrawable, int, int, int, int)} method
- * is being called after {@link #beginTile(GL)}.
+ * If {@link #attachAutoDrawable(GLAutoDrawable) attaching to} an {@link GLAutoDrawable},
+ * the {@link TileRendererListener#reshapeTile(TileRendererBase, int, int, int, int, int, int)} method
+ * is being called after {@link #beginTile(GL)} for each rendered tile.
  * It's implementation shall reshape the PMV matrix according to {@link #beginTile(GL)}. 
  * </p>
  * <a name="glprequirement"><h5>GL Profile Requirement</h5></a>
@@ -118,15 +118,97 @@ public abstract class TileRendererBase {
     /* pp */ static final boolean DEBUG = Debug.debug("TileRenderer");
     
     /** 
-     * Notifies {@link GLEventListener} implementing this interface
-     * that the owning {@link GLAutoDrawable} is {@link TileRendererBase#attachToAutoDrawable(GLAutoDrawable) attached} 
-     * to a tile renderer or {@link TileRendererBase#detachFromAutoDrawable() detached} from it.
+     * Listener for tile renderer events, intended to extend {@link GLEventListener} implementations,
+     * enabling tile rendering via {@link TileRendererBase#attachAutoDrawable(GLAutoDrawable)}.
      */
-    public static interface TileRendererNotify {
-        /** The owning {@link GLAutoDrawable} is {@link TileRendererBase#attachToAutoDrawable(GLAutoDrawable) attached} to a {@link TileRendererBase}. */
+    public static interface TileRendererListener {
+        /** 
+         * The owning {@link GLAutoDrawable} is {@link TileRendererBase#attachAutoDrawable(GLAutoDrawable) attached} 
+         * to the given {@link TileRendererBase} instance.
+         * <p>
+         * The {@link GLContext} of the {@link TileRendererBase}'s {@link TileRendererBase#getAttachedDrawable() attached} {@link GLAutoDrawable}
+         * <i>is not</i> current.
+         * </p>
+         * @param tr the associated {@link TileRendererBase}
+         * @see TileRendererBase#getAttachedDrawable()
+         */
         public void addTileRendererNotify(TileRendererBase tr);
-        /** The owning {@link GLAutoDrawable} is {@link TileRendererBase#detachFromAutoDrawable() detached} from a {@link TileRendererBase}. */
+        
+        /** 
+         * The owning {@link GLAutoDrawable} is {@link TileRendererBase#detachAutoDrawable() detached} 
+         * from the given {@link TileRendererBase} instance.
+         * <p>
+         * The {@link GLContext} of the {@link TileRendererBase}'s {@link TileRendererBase#getAttachedDrawable() attached} {@link GLAutoDrawable}
+         * <i>is not</i> current.
+         * </p>
+         * @param tr the disassociated {@link TileRendererBase}
+         * @see TileRendererBase#getAttachedDrawable()
+         */
         public void removeTileRendererNotify(TileRendererBase tr);
+        
+        /** 
+         * Called by the {@link TileRendererBase} during tile-rendering via an
+         * {@link TileRendererBase#getAttachedDrawable() attached} {@link GLAutoDrawable}'s 
+         * {@link GLAutoDrawable#display()} call for each tile before {@link #display(GLAutoDrawable)}.
+         * <p>
+         * The <a href="#pmvmatrix">PMV Matrix</a> shall be reshaped
+         * according to the given
+         * <ul>
+         *   <li>current tile-position</li>
+         *   <li>current tile-size</li>
+         *   <li>final image-size</li>
+         * </ul>
+         * The GL viewport is already set to origin 0/0 and the current tile-size.<br>
+         * See details in {@link TileRendererBase#beginTile(GL)}.<br>
+         * </p>
+         * <p>
+         * The {@link GLContext} of the {@link TileRendererBase}'s {@link TileRendererBase#getAttachedDrawable() attached} {@link GLAutoDrawable}
+         * <i>is</i> current.
+         * </p>
+         * @param tr the issuing {@link TileRendererBase}
+         * @param tileX the {@link TileRendererBase#TR_CURRENT_TILE_X_POS current tile's x-pos}
+         * @param tileY the {@link TileRendererBase#TR_CURRENT_TILE_Y_POS current tile's y-pos}
+         * @param tileWidth the {@link TileRendererBase#TR_CURRENT_TILE_WIDTH current tile's width}
+         * @param tileHeight the {@link TileRendererBase#TR_CURRENT_TILE_HEIGHT current tile's height}
+         * @param imageWidth the {@link TileRendererBase#TR_IMAGE_WIDTH final image width}
+         * @param imageHeight the {@link TileRendererBase#TR_IMAGE_HEIGHT final image height}
+         * @see TileRendererBase#getAttachedDrawable()
+         */
+        public void reshapeTile(TileRendererBase tr,
+                                int tileX, int tileY, int tileWidth, int tileHeight, 
+                                int imageWidth, int imageHeight);
+
+        /**
+         * Called by the {@link TileRendererBase} during tile-rendering 
+         * after {@link TileRendererBase#beginTile(GL)} and before {@link #reshapeTile(TileRendererBase, int, int, int, int, int, int) reshapeTile(..)}.
+         * <p>
+         * If {@link TileRendererBase} is of type {@link TileRenderer}, 
+         * method is called for the first tile of all tiles.<br>
+         * Otherwise, i.e. {@link RandomTileRenderer}, method is called for each particular tile.
+         * </p>
+         * <p>
+         * The {@link GLContext} of the {@link TileRenderer}'s {@link TileRenderer#getAttachedDrawable() attached} {@link GLAutoDrawable}
+         * <i>is</i> current.
+         * </p>
+         * @param tr the issuing {@link TileRendererBase}
+         */
+        public void startTileRendering(TileRendererBase tr);
+        
+        /**
+         * Called by the {@link TileRenderer} during tile-rendering
+         * after {@link TileRendererBase#endTile(GL)} and {@link GLAutoDrawable#swapBuffers()}.
+         * <p>
+         * If {@link TileRendererBase} is of type {@link TileRenderer}, 
+         * method is called for the last tile of all tiles.<br>
+         * Otherwise, i.e. {@link RandomTileRenderer}, method is called for each particular tile.
+         * </p>
+         * <p>
+         * The {@link GLContext} of the {@link TileRenderer}'s {@link TileRenderer#getAttachedDrawable() attached} {@link GLAutoDrawable}
+         * <i>is</i> current.
+         * </p>
+         * @param tr the issuing {@link TileRendererBase}
+         */
+        public void endTileRendering(TileRendererBase tr);
     }
     
     protected final Dimension imageSize = new Dimension(0, 0);
@@ -246,13 +328,13 @@ public abstract class TileRendererBase {
      *   <ul>
      *      <li>x 0</li>
      *      <li>y 0</li>
-     *      <li>{@link #TR_CURRENT_TILE_WIDTH tile width}</li>
-     *      <li>{@link #TR_CURRENT_TILE_HEIGHT tile height}</li>
+     *      <li>{@link #TR_CURRENT_TILE_WIDTH current tile's width}</li>
+     *      <li>{@link #TR_CURRENT_TILE_HEIGHT current tile's height}</li>
      *   </ul></li>
-     *   <li>{@link #TR_CURRENT_TILE_X_POS tile x-pos}</li>
-     *   <li>{@link #TR_CURRENT_TILE_Y_POS tile y-pos}</li>
-     *   <li>{@link #TR_IMAGE_WIDTH image width}</li>
-     *   <li>{@link #TR_IMAGE_HEIGHT image height}</li>
+     *   <li>{@link #TR_CURRENT_TILE_X_POS current tile's x-pos}</li>
+     *   <li>{@link #TR_CURRENT_TILE_Y_POS current tile's y-pos}</li>
+     *   <li>{@link #TR_IMAGE_WIDTH final image width}</li>
+     *   <li>{@link #TR_IMAGE_HEIGHT final image height}</li>
      * </ul>
      * </p>
      * <p>
@@ -311,12 +393,12 @@ public abstract class TileRendererBase {
     }
     
     /**
-     * Attaches this renderer to the {@link GLAutoDrawable}.
+     * Attaches the given {@link GLAutoDrawable} to this tile renderer.
+     * <p>
+     * The {@link GLAutoDrawable}'s original {@link GLEventListener} are moved to this tile renderer.
+     * </p>
      * <p>
-     * The {@link GLAutoDrawable}'s original {@link GLEventListener} are moved to this tile renderer.<br>
-     * It is <i>highly recommended</i> that the original {@link GLEventListener} implement 
-     * {@link TileRendererNotify}, so they get {@link TileRendererNotify#addTileRendererNotify(TileRendererBase) notified}
-     * about this event.
+     * {@link GLEventListeners} not implementing {@link TileRendererListener} are ignored while tile rendering.
      * </p>
      * <p>
      * The {@link GLAutoDrawable}'s {@link GLAutoDrawable#getAutoSwapBufferMode() auto-swap mode} is cached
@@ -324,15 +406,15 @@ public abstract class TileRendererBase {
      * see {@link #reqPreSwapBuffers(GLCapabilitiesImmutable)}.  
      * </p>
      * <p>
-     * This tile renderer's {@link GLEventListener} is then added to handle the tile rendering,
-     * replacing the original {@link GLEventListener}.<br>
-     * This {@link GLEventListener#display(GLAutoDrawable) display} implementations issues:
+     * This tile renderer's internal {@link GLEventListener} is then added to the attached {@link GLAutoDrawable} 
+     * to handle the tile rendering, replacing the original {@link GLEventListener}.<br>
+     * It's {@link GLEventListener#display(GLAutoDrawable) display} implementations issues:
      * <ul>
      *   <li>Optional {@link #setGLEventListener(GLEventListener, GLEventListener) pre-glel}.{@link GLEventListener#display(GLAutoDrawable) display(..)}</li>
      *   <li>{@link #beginTile(GL)}</li>
-     *   <li>for all original {@link GLEventListener}:
+     *   <li>for all original {@link TileRendererListener}:
      *   <ul> 
-     *     <li>{@link GLEventListener#reshape(GLAutoDrawable, int, int, int, int) reshape(0, 0, tile-width, tile-height)}</li>
+     *     <li>{@link TileRendererListener#reshapeTile(TileRendererBase, int, int, int, int, int, int) reshapeTile(tileX, tileY, tileWidth, tileHeight, imageWidth, imageHeight)}</li>
      *     <li>{@link GLEventListener#display(GLAutoDrawable) display(autoDrawable)}</li>
      *   </ul></li>
      *   <li>if ( {@link #reqPreSwapBuffers(GLCapabilitiesImmutable) pre-swap} ) { {@link GLAutoDrawable#swapBuffers() swapBuffers()} }</li>
@@ -342,16 +424,6 @@ public abstract class TileRendererBase {
      * </ul>
      * </p>
      * <p>
-     * The <a href="#pmvmatrix">PMV Matrix</a> shall be reshaped in the 
-     * original {@link GLEventListener}'s {@link GLEventListener#reshape(GLAutoDrawable, int, int, int, int) reshape} method
-     * according to the tile-position, -size and image-size<br>
-     * The {@link GLEventListener#reshape(GLAutoDrawable, int, int, int, int) reshape} method is called for each tile 
-     * w/ the current viewport of tile-size, where the tile-position and image-size can be retrieved by this tile renderer,
-     * see  details in {@link #beginTile(GL)}.<br>
-     * The original {@link GLEventListener} implementing {@link TileRendererNotify} is aware of this
-     * tile renderer instance.
-     * </p>
-     * <p>
      * Consider using {@link #setGLEventListener(GLEventListener, GLEventListener)} to add pre- and post
      * hooks to be performed on this renderer {@link GLEventListener}.<br>
      * The pre-hook is able to allocate memory and setup parameters, since it's called before {@link #beginTile(GL)}.<br>
@@ -359,13 +431,15 @@ public abstract class TileRendererBase {
      * since it's called after {@link #endTile(GL)}.
      * </p>
      * <p>
-     * Call {@link #detachFromAutoDrawable()} to remove this renderer from the {@link GLAutoDrawable} 
+     * Call {@link #detachAutoDrawable()} to remove the attached {@link GLAutoDrawable} from this tile renderer 
      * and to restore it's original {@link GLEventListener}.
      * </p>
-     * @param glad
+     * @param glad the {@link GLAutoDrawable} to attach.
      * @throws IllegalStateException if an {@link GLAutoDrawable} is already attached
+     * @see #getAttachedDrawable()
+     * @see #detachAutoDrawable()
      */
-    public void attachToAutoDrawable(GLAutoDrawable glad) throws IllegalStateException {
+    public final void attachAutoDrawable(GLAutoDrawable glad) throws IllegalStateException {
         if( null != this.glad ) {
             throw new IllegalStateException("GLAutoDrawable already attached");
         }
@@ -379,9 +453,9 @@ public abstract class TileRendererBase {
             listenersInit[i] = glad.getGLEventListenerInitState(l);
             listeners[i] = glad.removeGLEventListener( l );
             final boolean trn;
-            if( listeners[i] instanceof TileRendererNotify ) {
+            if( listeners[i] instanceof TileRendererListener ) {
                 trn = true;
-                ((TileRendererNotify)listeners[i]).addTileRendererNotify(this);
+                ((TileRendererListener)listeners[i]).addTileRendererNotify(this);
             } else {
                 trn = false;
             }
@@ -399,25 +473,34 @@ public abstract class TileRendererBase {
         }
     }
 
-    /**
-     * Detaches this renderer from the {@link GLAutoDrawable}.
-     * <p>
-     * It is <i>highly recommended</i> that the original {@link GLEventListener} implement 
-     * {@link TileRendererNotify}, so they get {@link TileRendererNotify#removeTileRendererNotify(TileRendererBase) notified}
-     * about this event.
-     * </p>
+    /** 
+     * Returns a previously {@link #attachAutoDrawable(GLAutoDrawable) attached} {@link GLAutoDrawable}, 
+     * <code>null</code> if none is attached.
      * <p>
-     * See {@link #attachToAutoDrawable(GLAutoDrawable)}.
+     * If called from {@link TileRendererListener#addTileRendererNotify(TileRendererBase)} 
+     * or {@link TileRendererListener#removeTileRendererNotify(TileRendererBase)}, method returns the
+     * just attached or soon to be detached {@link GLAutoDrawable}.
      * </p>
+     * @see #attachAutoDrawable(GLAutoDrawable)
+     * @see #detachAutoDrawable()
+     */
+    public final GLAutoDrawable getAttachedDrawable() {
+        return glad;        
+    }
+    
+    /**
+     * Detaches the given {@link GLAutoDrawable} from this tile renderer.
+     * @see #attachAutoDrawable(GLAutoDrawable)
+     * @see #getAttachedDrawable()
      */
-    public void detachFromAutoDrawable() {
+    public final void detachAutoDrawable() {
         if( null != glad ) {
             glad.removeGLEventListener(tiledGLEL);
             final int aSz = listenersInit.length;
             for(int i=0; i<aSz; i++) {
                 final GLEventListener l = listeners[i];
-                if( l instanceof TileRendererNotify ) {
-                    ((TileRendererNotify)l).removeTileRendererNotify(this);
+                if( l instanceof TileRendererListener ) {
+                    ((TileRendererListener)l).removeTileRendererNotify(this);
                 }
                 glad.addGLEventListener(l);
                 glad.setGLEventListenerInitState(l, listenersInit[i]);
@@ -436,12 +519,12 @@ public abstract class TileRendererBase {
     
     /**
      * Set {@link GLEventListener} for pre- and post operations when used w/
-     * {@link #attachToAutoDrawable(GLAutoDrawable)} 
+     * {@link #attachAutoDrawable(GLAutoDrawable)} 
      * for each {@link GLEventListener} callback.
      * @param preTile the pre operations
      * @param postTile the post operations
      */
-    public void setGLEventListener(GLEventListener preTile, GLEventListener postTile) {
+    public final void setGLEventListener(GLEventListener preTile, GLEventListener postTile) {
         glEventListenerPre = preTile;
         glEventListenerPost = postTile;
     }
@@ -449,10 +532,10 @@ public abstract class TileRendererBase {
     /**
      * Rendering one tile, by simply calling {@link GLAutoDrawable#display()}.
      * 
-     * @throws IllegalStateException if no {@link GLAutoDrawable} is {@link #attachToAutoDrawable(GLAutoDrawable) attached}
+     * @throws IllegalStateException if no {@link GLAutoDrawable} is {@link #attachAutoDrawable(GLAutoDrawable) attached}
      *                               or imageSize is not set
      */
-    public void display() throws IllegalStateException {
+    public final void display() throws IllegalStateException {
         if( null == glad ) {
             throw new IllegalStateException("No GLAutoDrawable attached");
         }
@@ -460,6 +543,8 @@ public abstract class TileRendererBase {
     }
     
     private final GLEventListener tiledGLEL = new GLEventListener() {
+        final TileRenderer tileRenderer = TileRendererBase.this instanceof TileRenderer ? (TileRenderer) TileRendererBase.this : null;
+        
         @Override
         public void init(GLAutoDrawable drawable) {
             if( null != glEventListenerPre ) {
@@ -468,7 +553,7 @@ public abstract class TileRendererBase {
             final int aSz = listenersInit.length;
             for(int i=0; i<aSz; i++) {
                 final GLEventListener l = listeners[i];
-                if( !listenersInit[i] ) {
+                if( !listenersInit[i] && l instanceof TileRendererListener ) {
                     l.init(drawable);
                     listenersInit[i] = true;
                 }
@@ -483,7 +568,7 @@ public abstract class TileRendererBase {
                 glEventListenerPre.dispose(drawable);
             }
             final int aSz = listenersInit.length;
-            for(int i=0; i<aSz; i++) {
+            for(int i=0; i<aSz; i++) { // dispose all GLEventListener, last chance!
                 listeners[i].dispose(drawable);
             }
             if( null != glEventListenerPost ) {
@@ -502,8 +587,17 @@ public abstract class TileRendererBase {
 
             final int aSz = listenersInit.length;
             for(int i=0; i<aSz; i++) {
-                listeners[i].reshape(drawable, 0, 0, currentTileWidth, currentTileHeight);
-                listeners[i].display(drawable);
+                final GLEventListener l = listeners[i];
+                if( l instanceof TileRendererListener ) {
+                    final TileRendererListener tl = (TileRendererListener)l;
+                    if( null == tileRenderer || 0 == tileRenderer.getCurrentTile() ) {
+                        tl.startTileRendering(TileRendererBase.this);
+                    }
+                    tl.reshapeTile(TileRendererBase.this, 
+                                   currentTileXPos, currentTileYPos, currentTileWidth, currentTileHeight,
+                                   imageSize.getWidth(), imageSize.getHeight());
+                    l.display(drawable);
+                }
             }
             
             if( gladRequiresPreSwap ) {
@@ -513,7 +607,14 @@ public abstract class TileRendererBase {
                 endTile(gl);
                 glad.swapBuffers();
             }
-            
+            if( null == tileRenderer || tileRenderer.eot() ) {
+                for(int i=0; i<aSz; i++) {
+                    final GLEventListener l = listeners[i];
+                    if( l instanceof TileRendererListener ) {
+                        ((TileRendererListener)l).endTileRendering(TileRendererBase.this);
+                    }
+                }                
+            }
             if( null != glEventListenerPost ) {
                 glEventListenerPost.reshape(drawable, 0, 0, currentTileWidth, currentTileHeight);
                 glEventListenerPost.display(drawable);