From 604434f8a1ea43f306e21fe81ac7471f27e3c9cf Mon Sep 17 00:00:00 2001 From: Sven Gothel Date: Thu, 5 Sep 2013 08:32:31 +0200 Subject: TileRenderer*: Enhance API Doc; Cleanup OO; Remove PMVMatrixCallback, use GLEventListener reshape(..) or manual reshape after beginTile(..) method. GLEventListener reshape(..) method should be aware of TileRenderer usage and get the missing tile position and image size from it (-> see Gears example). TestRandomTiledRendering3GL2AWT demos AWT GLCanvas onscreen being used for random tile rendering to produce a PNG file. TestTiledRendering1GL2 is now GLAutoDrawable/GLEventListener agnostic, hence demos plain GLDrawable tile rendering usage. --- .../com/jogamp/opengl/util/RandomTileRenderer.java | 83 ++-------- .../com/jogamp/opengl/util/TileRenderer.java | 105 +++--------- .../com/jogamp/opengl/util/TileRendererBase.java | 178 ++++++++++++++++----- 3 files changed, 165 insertions(+), 201 deletions(-) (limited to 'src/jogl/classes/com/jogamp') diff --git a/src/jogl/classes/com/jogamp/opengl/util/RandomTileRenderer.java b/src/jogl/classes/com/jogamp/opengl/util/RandomTileRenderer.java index 0fba1170d..4fcf0b6cc 100644 --- a/src/jogl/classes/com/jogamp/opengl/util/RandomTileRenderer.java +++ b/src/jogl/classes/com/jogamp/opengl/util/RandomTileRenderer.java @@ -29,12 +29,14 @@ package com.jogamp.opengl.util; import javax.media.opengl.GL2ES3; import javax.media.opengl.GLAutoDrawable; -import javax.media.opengl.GLEventListener; import com.jogamp.opengl.util.GLPixelBuffer.GLPixelAttributes; /** * Variation of {@link TileRenderer} w/o using fixed tiles but arbitrary rectangular regions. + *

+ * See {@link TileRendererBase} for details. + *

*/ public class RandomTileRenderer extends TileRendererBase { private boolean tileRectSet = false; @@ -47,8 +49,8 @@ public class RandomTileRenderer extends TileRendererBase { } @Override - public final int getParam(int param) { - switch (param) { + public final int getParam(int pname) { + switch (pname) { case TR_IMAGE_WIDTH: return imageSize.getWidth(); case TR_IMAGE_HEIGHT: @@ -62,7 +64,7 @@ public class RandomTileRenderer extends TileRendererBase { case TR_CURRENT_TILE_HEIGHT: return currentTileHeight; default: - throw new IllegalArgumentException("Invalid enumerant as argument"); + throw new IllegalArgumentException("Invalid pname: "+pname); } } @@ -94,15 +96,14 @@ public class RandomTileRenderer extends TileRendererBase { if( 0 >= imageSize.getWidth() || 0 >= imageSize.getHeight() ) { throw new IllegalStateException("Image size has not been set"); } - if( null == this.pmvMatrixCB ) { - throw new IllegalStateException("pmvMatrixCB has not been set"); - } if( !tileRectSet ) { throw new IllegalStateException("tileRect has not been set"); } gl.glViewport( 0, 0, currentTileWidth, currentTileHeight ); - pmvMatrixCB.reshapePMVMatrix(gl, currentTileXPos, currentTileYPos, currentTileWidth, currentTileHeight, imageSize.getWidth(), imageSize.getHeight()); + // Do not forget to issue: + // reshape( 0, 0, tW, tH ); + // which shall reflect tile renderer fileds: currentTileXPos, currentTileYPos and imageSize beginCalled = true; } @@ -178,75 +179,11 @@ public class RandomTileRenderer extends TileRendererBase { /** * Rendering one tile, by simply calling {@link GLAutoDrawable#display()}. * - * @throws IllegalStateException if no {@link GLAutoDrawable} is {@link #attachToAutoDrawable(GLAutoDrawable, int) attached} + * @throws IllegalStateException if no {@link GLAutoDrawable} is {@link #attachToAutoDrawable(GLAutoDrawable) attached} * or imageSize is not set */ public void display(int tX, int tY, int tWidth, int tHeight) throws IllegalStateException { setTileRect(tX, tY, tWidth, tHeight); display(); } - - protected final GLEventListener getTiledGLEL() { return tiledGLEL; } - private final GLEventListener tiledGLEL = new GLEventListener() { - @Override - public void init(GLAutoDrawable drawable) { - if( null != glEventListenerPre ) { - glEventListenerPre.init(drawable); - } - final int aSz = listenersInit.length; - for(int i=0; i * Enhanced for {@link GL2ES3}. *

+ *

+ * See {@link TileRendererBase} for details. + *

* * @author ryanm, sgothel */ public class TileRenderer extends TileRendererBase { /** - * The width of a tile + * The width of a tile. See {@link #getParam(int)}. */ public static final int TR_TILE_WIDTH = 7; /** - * The height of a tile + * The height of a tile. See {@link #getParam(int)}. */ public static final int TR_TILE_HEIGHT = 8; /** - * The width of the border around the tiles + * The width of the border around the tiles. See {@link #getParam(int)}. */ public static final int TR_TILE_BORDER = 9; /** - * The number of rows of tiles + * The number of rows of tiles. See {@link #getParam(int)}. */ public static final int TR_ROWS = 10; /** - * The number of columns of tiles + * The number of columns of tiles. See {@link #getParam(int)}. */ public static final int TR_COLUMNS = 11; /** - * The current row number + * The current row number. See {@link #getParam(int)}. */ public static final int TR_CURRENT_ROW = 12; /** - * The current column number + * The current column number. See {@link #getParam(int)}. */ public static final int TR_CURRENT_COLUMN = 13; /** - * The order that the rows are traversed + * The order that the rows are traversed. See {@link #getParam(int)}. */ public static final int TR_ROW_ORDER = 14; /** - * Indicates we are traversing rows from the top to the bottom + * Indicates we are traversing rows from the top to the bottom. See {@link #getParam(int)}. */ public static final int TR_TOP_TO_BOTTOM = 15; /** - * Indicates we are traversing rows from the bottom to the top + * Indicates we are traversing rows from the bottom to the top. See {@link #getParam(int)}. */ public static final int TR_BOTTOM_TO_TOP = 16; @@ -180,8 +182,8 @@ public class TileRenderer extends TileRendererBase { public final boolean eot() { return 0 > currentTile; } @Override - public final int getParam(int param) { - switch (param) { + public final int getParam(int pname) { + switch (pname) { case TR_TILE_WIDTH: return tileSize.getWidth(); case TR_TILE_HEIGHT: @@ -219,7 +221,7 @@ public class TileRenderer extends TileRendererBase { case TR_ROW_ORDER: return rowOrder; default: - throw new IllegalArgumentException("Invalid enumerant as argument"); + throw new IllegalArgumentException("Invalid pname: "+pname); } } @@ -243,9 +245,6 @@ public class TileRenderer extends TileRendererBase { if( 0 >= imageSize.getWidth() || 0 >= imageSize.getHeight() ) { throw new IllegalStateException("Image size has not been set"); } - if( null == this.pmvMatrixCB ) { - throw new IllegalStateException("pmvMatrixCB has not been set"); - } if (currentTile <= 0) { setup(); } @@ -297,7 +296,9 @@ public class TileRenderer extends TileRendererBase { } gl.glViewport( 0, 0, tW, tH ); - pmvMatrixCB.reshapePMVMatrix(gl, currentTileXPos, currentTileYPos, tW, tH, imageSize.getWidth(), imageSize.getHeight()); + // Do not forget to issue: + // reshape( 0, 0, tW, tH ); + // which shall reflect tile renderer fileds: currentTileXPos, currentTileYPos and imageSize beginCalled = true; } @@ -385,72 +386,8 @@ public class TileRenderer extends TileRendererBase { *

*/ @Override - public void attachToAutoDrawable(GLAutoDrawable glad, PMVMatrixCallback pmvMatrixCB) throws IllegalStateException { - super.attachToAutoDrawable(glad, pmvMatrixCB); + public void attachToAutoDrawable(GLAutoDrawable glad) throws IllegalStateException { + super.attachToAutoDrawable(glad); setTileSize(glad.getWidth(), glad.getHeight(), 0); } - - protected final GLEventListener getTiledGLEL() { return tiledGLEL; } - private final GLEventListener tiledGLEL = new GLEventListener() { - @Override - public void init(GLAutoDrawable drawable) { - if( null != glEventListenerPre ) { - glEventListenerPre.init(drawable); - } - final int aSz = listenersInit.length; - for(int i=0; i * Enhanced for {@link GL2ES3}, abstracted to suit {@link TileRenderer} and {@link RandomTileRenderer}. *

+ *
PMV Matrix Considerations
 + *

+ * The PMV matrix needs to be reshaped in user code + * after calling {@link #beginTile(GL2ES3)}, See {@link #beginTile(GL2ES3)}. + *

+ *

+ * 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(GL2ES3)}. + * It's implementation shall reshape the PMV matrix according to {@link #beginTile(GL2ES3)}. + *

* * @author ryanm, sgothel */ public abstract class TileRendererBase { /** - * The width of the final image + * The width of the final image. See {@link #getParam(int)}. */ public static final int TR_IMAGE_WIDTH = 1; /** - * The height of the final image + * The height of the final image. See {@link #getParam(int)}. */ public static final int TR_IMAGE_HEIGHT = 2; /** - * The width of the current tile + * The width of the current tile. See {@link #getParam(int)}. */ public static final int TR_CURRENT_TILE_X_POS = 3; /** - * The height of the current tile + * The height of the current tile. See {@link #getParam(int)}. */ public static final int TR_CURRENT_TILE_Y_POS = 4; /** - * The width of the current tile + * The width of the current tile. See {@link #getParam(int)}. */ public static final int TR_CURRENT_TILE_WIDTH = 5; /** - * The height of the current tile + * The height of the current tile. See {@link #getParam(int)}. */ public static final int TR_CURRENT_TILE_HEIGHT = 6; @@ -88,7 +98,6 @@ public abstract class TileRendererBase { protected final GLPixelStorageModes psm = new GLPixelStorageModes(); protected GLPixelBuffer imageBuffer; protected GLPixelBuffer tileBuffer; - protected PMVMatrixCallback pmvMatrixCB = null; protected boolean beginCalled = false; protected int currentTileXPos; protected int currentTileYPos; @@ -100,33 +109,18 @@ public abstract class TileRendererBase { protected GLEventListener glEventListenerPre = null; protected GLEventListener glEventListenerPost = null; - public static interface PMVMatrixCallback { - void reshapePMVMatrix(GL gl, int tileX, int tileY, int tileWidth, int tileHeight, int imageWidth, int imageHeight); - } - protected TileRendererBase() { } /** * Gets the parameters of this TileRenderer object * - * @param param The parameter that is to be retrieved + * @param pname The parameter name that is to be retrieved * @return the value of the parameter - * @throws IllegalArgumentException if param is not handled + * @throws IllegalArgumentException if pname is not handled */ - public abstract int getParam(int param) throws IllegalArgumentException; + public abstract int getParam(int pname) throws IllegalArgumentException; - /** - * @param pmvMatrixCB - * @throws IllegalArgumentException if pmvMatrixCB is null - */ - public final void setPMVMatrixCallback(PMVMatrixCallback pmvMatrixCB) throws IllegalArgumentException { - if( null == pmvMatrixCB ) { - throw new IllegalArgumentException("pmvMatrixCB is null"); - } - this.pmvMatrixCB = pmvMatrixCB; - } - /** * Specify a buffer the tiles to be copied to. This is not * necessary for the creation of the final image, but useful if you @@ -170,13 +164,26 @@ public abstract class TileRendererBase { /** * Begins rendering a tile. *

- * Methods modifies the viewport. - * User shall reset the viewport when finishing tile rendering, - * i.e. after last call of {@link #endTile(GL2ES3)}! + * Methods modifies the viewport, see below. + * User shall reset the viewport when finishing all tile rendering, + * i.e. after very last call of {@link #endTile(GL2ES3)}! *

- *

- * The projection matrix stack should be - * left alone after calling this method! + *

+ * The PMV Matrix + * must be reshaped after this call using: + *

    + *
  • Current Viewport + *
      + *
    • x 0
      • + *
    • y 0
      • + *
    • {@link #TR_CURRENT_TILE_WIDTH tile width}
      • + *
    • {@link #TR_CURRENT_TILE_HEIGHT tile height}
      • + *
    • + *
  • {@link #TR_CURRENT_TILE_X_POS tile x-pos}
    • + *
  • {@link #TR_CURRENT_TILE_Y_POS tile y-pos}
    • + *
  • {@link #TR_IMAGE_WIDTH image width}
    • + *
  • {@link #TR_IMAGE_HEIGHT image height}
    • + *
*

*

* Use shall render the scene afterwards, concluded with a call to @@ -200,23 +207,46 @@ public abstract class TileRendererBase { /** * Attaches this renderer to the {@link GLAutoDrawable}. *

- * The {@link GLAutoDrawable}'s {@link GLEventListener} are removed first and stored locally. + * The {@link GLAutoDrawable}'s original {@link GLEventListener} are moved to local storage. * This renderer {@link GLEventListener} is then added to handle the tile rendering - * for the original {@link GLEventListener}. + * for the original {@link GLEventListener}, i.e. it's {@link GLEventListener#display(GLAutoDrawable) display} issues: + *

    + *
  • Optional {@link #setGLEventListener(GLEventListener, GLEventListener) pre-glel}.{@link GLEventListener#display(GLAutoDrawable) display(..)}
    • + *
  • {@link #beginTile(GL2ES3)}
    • + *
  • for all original {@link GLEventListener}: + *
      + *
    • {@link GLEventListener#reshape(GLAutoDrawable, int, int, int, int) reshape(0, 0, tile-width, tile-height)}
      • + *
    • {@link GLEventListener#display(GLAutoDrawable) display(autoDrawable)}
      • + *
    • + *
  • {@link #endTile(GL2ES3)}
    • + *
  • Optional {@link #setGLEventListener(GLEventListener, GLEventListener) post-glel}.{@link GLEventListener#display(GLAutoDrawable) display(..)}
    • + *
+ *

+ *

+ * Consider using {@link #setGLEventListener(GLEventListener, GLEventListener)} to add pre- and post + * hooks to be performed on this renderer {@link GLEventListener}.
+ * The pre-hook is able to allocate memory and setup parameters, since it's called before {@link #beginTile(GL2ES3)}.
+ * The post-hook is able to use the rendering result and can even shutdown tile-rendering, + * since it's called after {@link #endTile(GL2ES3)}. *

*

* Call {@link #detachFromAutoDrawable()} to remove this renderer from the {@link GLAutoDrawable} * and to restore it's original {@link GLEventListener}. *

+ *

+ * The PMV Matrix shall be reshaped in the + * original {@link GLEventListener}'s {@link GLEventListener#reshape(GLAutoDrawable, int, int, int, int) reshape} + * method. The latter is called for each tile w/ the current viewport. + * The tile's position and image size can be utilized. See details in {@link #beginTile(GL2ES3)}. + *

* @param glad * @throws IllegalStateException if an {@link GLAutoDrawable} is already attached */ - public void attachToAutoDrawable(GLAutoDrawable glad, PMVMatrixCallback pmvMatrixCB) throws IllegalStateException { + public void attachToAutoDrawable(GLAutoDrawable glad) throws IllegalStateException { if( null != this.glad ) { throw new IllegalStateException("GLAutoDrawable already attached"); } this.glad = glad; - setPMVMatrixCallback(pmvMatrixCB); final int aSz = glad.getGLEventListenerCount(); listeners = new GLEventListener[aSz]; @@ -226,18 +256,18 @@ public abstract class TileRendererBase { listenersInit[i] = glad.getGLEventListenerInitState(l); listeners[i] = glad.removeGLEventListener( l ); } - glad.addGLEventListener(getTiledGLEL()); + glad.addGLEventListener(tiledGLEL); } /** * Detaches this renderer from the {@link GLAutoDrawable}. *

- * See {@link #attachToAutoDrawable(GLAutoDrawable, PMVMatrixCallback)}. + * See {@link #attachToAutoDrawable(GLAutoDrawable)}. *

*/ public void detachFromAutoDrawable() { if( null != glad ) { - glad.removeGLEventListener(getTiledGLEL()); + glad.removeGLEventListener(tiledGLEL); final int aSz = listenersInit.length; for(int i=0; i