Fixed Issue 199: Incorporate tile rendering library

With the permission of the author, Brian Paul, the Mesa tile rendering
library has been incorporated under BSD-compatible licensing terms
thanks to porting work by user bleb from the javagaming.org forums.
Added demos.misc.TiledRendering demo creating a high-resolution
screenshot of the Gears demo.


git-svn-id: file:///usr/local/projects/SUN/JOGL/git-svn/svn-server-sync/jogl/trunk@580 232f8b59-042b-4e1e-8c03-345bb8c30851

2 files changed, 637 insertions, 2 deletions

diff --git a/LICENSE.txt b/LICENSE.txt
index 594856601..f1238959c 100755
--- a/LICENSE.txt
+++ b/LICENSE.txt
@@ -70,8 +70,8 @@ the SGI Free Software License B:
    published by SGI, but has not been independently verified as being
    compliant with the OpenGL(R) version 1.2.1 Specification.
 
-The JOGL source tree also contains code from the LWJGL project which
-is similarly covered by the BSD license:
+The JOGL source tree contains code from the LWJGL project which is
+similarly covered by the BSD license:
 
    Copyright (c) 2002-2004 LWJGL Project
    All rights reserved.
@@ -102,3 +102,38 @@ is similarly covered by the BSD license:
    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The JOGL source tree also contains a Java port of Brian Paul's Tile
+Rendering library, used with permission of the author under the BSD
+license instead of the original LGPL:
+
+   Copyright (c) 1997-2005 Brian Paul. All Rights Reserved.
+ 
+   Redistribution and use in source and binary forms, with or without
+   modification, are permitted provided that the following conditions are
+   met:
+   
+   - Redistribution of source code must retain the above copyright
+     notice, this list of conditions and the following disclaimer.
+   
+   - Redistribution in binary form must reproduce the above copyright
+     notice, this list of conditions and the following disclaimer in the
+     documentation and/or other materials provided with the distribution.
+   
+   Neither the name of Brian Paul or the names of contributors may be
+   used to endorse or promote products derived from this software
+   without specific prior written permission.
+   
+   This software is provided "AS IS," without a warranty of any
+   kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
+   WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY
+   EXCLUDED. THE COPYRIGHT HOLDERS AND CONTRIBUTORS SHALL NOT BE
+   LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING,
+   MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO
+   EVENT WILL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY
+   LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
+   CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
+   REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR
+   INABILITY TO USE THIS SOFTWARE, EVEN IF THE COPYRIGHT HOLDERS OR
+   CONTRIBUTORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
diff --git a/src/classes/com/sun/opengl/util/TileRenderer.java b/src/classes/com/sun/opengl/util/TileRenderer.java
new file mode 100755
index 000000000..982ea4a16
--- /dev/null
+++ b/src/classes/com/sun/opengl/util/TileRenderer.java
@@ -0,0 +1,600 @@
+package com.sun.opengl.util;
+
+import java.awt.Dimension;
+import java.nio.Buffer;
+
+import javax.media.opengl.*;
+import javax.media.opengl.glu.*;
+
+/**
+ * A fairly direct port of Brian Paul's tile rendering library, found
+ * at <a href = "http://www.mesa3d.org/brianp/TR.html">
+ * http://www.mesa3d.org/brianp/TR.html </a> . I've java-fied it, but
+ * the functionality is the same.
+ * 
+ * Original code Copyright (C) 1997-2005 Brian Paul. Licensed under
+ * BSD-compatible terms with permission of the author. See LICENSE.txt
+ * for license information.
+ * 
+ * @author ryanm
+ */
+public class TileRenderer
+{
+  private static final int DEFAULT_TILE_WIDTH = 256;
+
+  private static final int DEFAULT_TILE_HEIGHT = 256;
+
+  private static final int DEFAULT_TILE_BORDER = 0;
+
+  //
+  // Enumeration flags for accessing variables
+  //
+  // @author ryanm
+  //
+
+  /**
+   * The width of a tile
+   */
+  public static final int TR_TILE_WIDTH = 0;
+  /**
+   * The height of a tile
+   */
+  public static final int TR_TILE_HEIGHT = 1;
+  /**
+   * The width of the border around the tiles
+   */
+  public static final int TR_TILE_BORDER = 2;
+  /**
+   * The width of the final image
+   */
+  public static final int TR_IMAGE_WIDTH = 3;
+  /**
+   * The height of the final image
+   */
+  public static final int TR_IMAGE_HEIGHT = 4;
+  /**
+   * The number of rows of tiles
+   */
+  public static final int TR_ROWS = 5;
+  /**
+   * The number of columns of tiles
+   */
+  public static final int TR_COLUMNS = 6;
+  /**
+   * The current row number
+   */
+  public static final int TR_CURRENT_ROW = 7;
+  /**
+   * The current column number
+   */
+  public static final int TR_CURRENT_COLUMN = 8;
+  /**
+   * The width of the current tile
+   */
+  public static final int TR_CURRENT_TILE_WIDTH = 9;
+  /**
+   * The height of the current tile
+   */
+  public static final int TR_CURRENT_TILE_HEIGHT = 10;
+  /**
+   * The order that the rows are traversed
+   */
+  public static final int TR_ROW_ORDER = 11;
+
+
+  /**
+   * Indicates we are traversing rows from the top to the bottom
+   */
+  public static final int TR_TOP_TO_BOTTOM = 1;
+
+  /**
+   * Indicates we are traversing rows from the bottom to the top
+   */
+  public static final int TR_BOTTOM_TO_TOP = 2;
+
+  /* Final image parameters */
+  private Dimension imageSize = new Dimension();
+
+  private int imageFormat, imageType;
+
+  private Buffer imageBuffer;
+
+  /* Tile parameters */
+  private Dimension tileSize = new Dimension();
+
+  private Dimension tileSizeNB = new Dimension();
+
+  private int tileBorder;
+
+  private int tileFormat, tileType;
+
+  private Buffer tileBuffer;
+
+  /* Projection parameters */
+  private boolean perspective;
+
+  private double left;
+
+  private double right;
+
+  private double bottom;
+
+  private double top;
+
+  private double near;
+
+  private double far;
+
+  /* Misc */
+  private int rowOrder;
+
+  private int rows, columns;
+
+  private int currentTile;
+
+  private int currentTileWidth, currentTileHeight;
+
+  private int currentRow, currentColumn;
+
+  private int[] viewportSave = new int[ 4 ];
+
+  /**
+   * Creates a new TileRenderer object
+   */
+  public TileRenderer()
+  {
+    tileSize.width = DEFAULT_TILE_WIDTH;
+    tileSize.height = DEFAULT_TILE_HEIGHT;
+    tileBorder = DEFAULT_TILE_BORDER;
+    rowOrder = TR_BOTTOM_TO_TOP;
+    currentTile = -1;
+  }
+
+  /**
+   * Sets up the number of rows and columns needed
+   */
+  private void setup()
+  {
+    columns = ( imageSize.width + tileSizeNB.width - 1 ) / tileSizeNB.width;
+    rows = ( imageSize.height + tileSizeNB.height - 1 ) / tileSizeNB.height;
+    currentTile = 0;
+
+    assert columns >= 0;
+    assert rows >= 0;
+  }
+
+  /**
+   * Sets the size of the tiles to use in rendering. The actual
+   * effective size of the tile depends on the border size, ie (
+   * width - 2*border ) * ( height - 2 * border )
+   * 
+   * @param width
+   *           The width of the tiles. Must not be larger than the GL
+   *           context
+   * @param height
+   *           The height of the tiles. Must not be larger than the
+   *           GL context
+   * @param border
+   *           The width of the borders on each tile. This is needed
+   *           to avoid artifacts when rendering lines or points with
+   *           thickness > 1.
+   */
+  public void setTileSize( int width, int height, int border )
+  {
+    assert ( border >= 0 );
+    assert ( width >= 1 );
+    assert ( height >= 1 );
+    assert ( width >= 2 * border );
+    assert ( height >= 2 * border );
+
+    tileBorder = border;
+    tileSize.width = width;
+    tileSize.height = height;
+    tileSizeNB.width = width - 2 * border;
+    tileSizeNB.height = height - 2 * border;
+    setup();
+  }
+
+  /**
+   * Specify a buffer the tiles to be copied to. This is not
+   * necessary for the creation of the final image, but useful if you
+   * want to inspect each tile in turn.
+   * 
+   * @param format
+   *           Interpreted as in glReadPixels
+   * @param type
+   *           Interpreted as in glReadPixels
+   * @param image
+   *           The buffer itself. Must be large enough to contain a
+   *           tile, minus any borders
+   */
+  public void setTileBuffer( int format, int type, Buffer image )
+  {
+    tileFormat = format;
+    tileType = type;
+    tileBuffer = image;
+  }
+
+  /**
+   * Sets the desired size of the final image
+   * 
+   * @param width
+   *           The width of the final image
+   * @param height
+   *           The height of the final image
+   */
+  public void setImageSize( int width, int height )
+  {
+    imageSize.width = width;
+    imageSize.height = height;
+    setup();
+  }
+
+  /**
+   * Sets the buffer in which to store the final image
+   * 
+   * @param format
+   *           Interpreted as in glReadPixels
+   * @param type
+   *           Interpreted as in glReadPixels
+   * @param image
+   *           the buffer itself, must be large enough to hold the
+   *           final image
+   */
+  public void setImageBuffer( int format, int type, Buffer image )
+  {
+    imageFormat = format;
+    imageType = type;
+    imageBuffer = image;
+  }
+
+  /**
+   * Gets the parameters of this TileRenderer object
+   * 
+   * @param param
+   *           The parameter that is to be retrieved
+   * @return the value of the parameter
+   */
+  public int getParam( int param )
+  {
+    switch (param) {
+      case TR_TILE_WIDTH:
+        return tileSize.width;
+      case TR_TILE_HEIGHT:
+        return tileSize.height;
+      case TR_TILE_BORDER:
+        return tileBorder;
+      case TR_IMAGE_WIDTH:
+        return imageSize.width;
+      case TR_IMAGE_HEIGHT:
+        return imageSize.height;
+      case TR_ROWS:
+        return rows;
+      case TR_COLUMNS:
+        return columns;
+      case TR_CURRENT_ROW:
+        if( currentTile < 0 )
+          return -1;
+        else
+          return currentRow;
+      case TR_CURRENT_COLUMN:
+        if( currentTile < 0 )
+          return -1;
+        else
+          return currentColumn;
+      case TR_CURRENT_TILE_WIDTH:
+        return currentTileWidth;
+      case TR_CURRENT_TILE_HEIGHT:
+        return currentTileHeight;
+      case TR_ROW_ORDER:
+        return rowOrder;
+      default:
+        throw new IllegalArgumentException("Invalid enumerant as argument");
+    }
+  }
+
+  /**
+   * Sets the order of row traversal
+   * 
+   * @param order
+   *           The row traversal order, must be
+   *           eitherTR_TOP_TO_BOTTOM or TR_BOTTOM_TO_TOP
+   */
+  public void setRowOrder( int order )
+  {
+    if (order == TR_TOP_TO_BOTTOM || order == TR_BOTTOM_TO_TOP) {
+      rowOrder = order;
+    } else {
+      throw new IllegalArgumentException("Must pass TR_TOP_TO_BOTTOM or TR_BOTTOM_TO_TOP");
+    }
+  }
+
+  /**
+   * Sets the context to use an orthographic projection. Must be
+   * called before rendering the first tile
+   * 
+   * @param left
+   *           As in glOrtho
+   * @param right
+   *           As in glOrtho
+   * @param bottom
+   *           As in glOrtho
+   * @param top
+   *           As in glOrtho
+   * @param zNear
+   *           As in glOrtho
+   * @param zFar
+   *           As in glOrtho
+   */
+  public void trOrtho( double left, double right, double bottom, double top, double zNear,
+                       double zFar )
+  {
+    this.perspective = false;
+    this.left = left;
+    this.right = right;
+    this.bottom = bottom;
+    this.top = top;
+    this.near = zNear;
+    this.far = zFar;
+  }
+
+  /**
+   * Sets the perspective projection frustrum. Must be called before
+   * rendering the first tile
+   * 
+   * @param left
+   *           As in glFrustrum
+   * @param right
+   *           As in glFrustrum
+   * @param bottom
+   *           As in glFrustrum
+   * @param top
+   *           As in glFrustrum
+   * @param zNear
+   *           As in glFrustrum
+   * @param zFar
+   *           As in glFrustrum
+   */
+  public void trFrustum( double left, double right, double bottom, double top, double zNear,
+                         double zFar )
+  {
+    this.perspective = true;
+    this.left = left;
+    this.right = right;
+    this.bottom = bottom;
+    this.top = top;
+    this.near = zNear;
+    this.far = zFar;
+  }
+
+  /**
+   * Convenient way to specify a perspective projection
+   * 
+   * @param fovy
+   *           As in gluPerspective
+   * @param aspect
+   *           As in gluPerspective
+   * @param zNear
+   *           As in gluPerspective
+   * @param zFar
+   *           As in gluPerspective
+   */
+  public void trPerspective( double fovy, double aspect, double zNear, double zFar )
+  {
+    double xmin, xmax, ymin, ymax;
+    ymax = zNear * Math.tan( fovy * 3.14159265 / 360.0 );
+    ymin = -ymax;
+    xmin = ymin * aspect;
+    xmax = ymax * aspect;
+    trFrustum( xmin, xmax, ymin, ymax, zNear, zFar );
+  }
+
+  /**
+   * Begins rendering a tile. The projection matrix stack should be
+   * left alone after calling this
+   * 
+   * @param gl
+   *           The gl context
+   */
+  public void beginTile( GL gl )
+  {
+    if (currentTile <= 0) {
+      setup();
+      /*
+       * Save user's viewport, will be restored after last tile
+       * rendered
+       */
+      gl.glGetIntegerv( GL.GL_VIEWPORT, viewportSave, 0 );
+    }
+
+    /* which tile (by row and column) we're about to render */
+    if (rowOrder == TR_BOTTOM_TO_TOP) {
+      currentRow = currentTile / columns;
+      currentColumn = currentTile % columns;
+    } else {
+      currentRow = rows - ( currentTile / columns ) - 1;
+      currentColumn = currentTile % columns;
+    }
+    assert ( currentRow < rows );
+    assert ( currentColumn < columns );
+
+    int border = tileBorder;
+
+    int th, tw;
+
+    /* Compute actual size of this tile with border */
+    if (currentRow < rows - 1) {
+      th = tileSize.height;
+    } else {
+      th = imageSize.height - ( rows - 1 ) * ( tileSizeNB.height  ) + 2 * border;
+    }
+
+    if (currentColumn < columns - 1) {
+      tw = tileSize.width;
+    } else {
+      tw = imageSize.width - ( columns - 1 ) * ( tileSizeNB.width  ) + 2 * border;
+    }
+
+    /* Save tile size, with border */
+    currentTileWidth = tw;
+    currentTileHeight = th;
+
+    gl.glViewport( 0, 0, tw, th );
+
+    /* save current matrix mode */
+    int[] matrixMode = new int[ 1 ];
+    gl.glGetIntegerv( GL.GL_MATRIX_MODE, matrixMode, 0 );
+    gl.glMatrixMode( GL.GL_PROJECTION );
+    gl.glLoadIdentity();
+
+    /* compute projection parameters */
+    double l =
+      left + ( right - left ) * ( currentColumn * tileSizeNB.width - border )
+      / imageSize.width;
+    double r = l + ( right - left ) * tw / imageSize.width;
+    double b =
+      bottom + ( top - bottom ) * ( currentRow * tileSizeNB.height - border )
+      / imageSize.height;
+    double t = b + ( top - bottom ) * th / imageSize.height;
+
+    if( perspective ) {
+      gl.glFrustum( l, r, b, t, near, far );
+    } else {
+      gl.glOrtho( l, r, b, t, near, far );
+    }
+
+    /* restore user's matrix mode */
+    gl.glMatrixMode( matrixMode[ 0 ] );
+  }
+
+  /**
+   * Must be called after rendering the scene
+   * 
+   * @param gl
+   *           the gl context
+   * @return true if there are more tiles to be rendered, false if
+   *         the final image is complete
+   */
+  public boolean endTile( GL gl )
+  {
+    int[] prevRowLength = new int[ 1 ], prevSkipRows = new int[ 1 ], prevSkipPixels = new int[ 1 ], prevAlignment =
+      new int[ 1 ];
+
+    assert ( currentTile >= 0 );
+
+    // be sure OpenGL rendering is finished
+    gl.glFlush();
+
+    // save current glPixelStore values
+    gl.glGetIntegerv( GL.GL_PACK_ROW_LENGTH, prevRowLength, 0 );
+    gl.glGetIntegerv( GL.GL_PACK_SKIP_ROWS, prevSkipRows, 0 );
+    gl.glGetIntegerv( GL.GL_PACK_SKIP_PIXELS, prevSkipPixels, 0 );
+    gl.glGetIntegerv( GL.GL_PACK_ALIGNMENT, prevAlignment, 0 );
+
+    if( tileBuffer != null ) {
+      int srcX = tileBorder;
+      int srcY = tileBorder;
+      int srcWidth = tileSizeNB.width;
+      int srcHeight = tileSizeNB.height;
+      gl.glReadPixels( srcX, srcY, srcWidth, srcHeight, tileFormat, tileType, tileBuffer );
+    }
+
+    if( imageBuffer != null ) {
+      int srcX = tileBorder;
+      int srcY = tileBorder;
+      int srcWidth = currentTileWidth - 2 * tileBorder;
+      int srcHeight = currentTileHeight - 2 * tileBorder;
+      int destX = tileSizeNB.width * currentColumn;
+      int destY = tileSizeNB.height * currentRow;
+
+      /* setup pixel store for glReadPixels */
+      gl.glPixelStorei( GL.GL_PACK_ROW_LENGTH, imageSize.width );
+      gl.glPixelStorei( GL.GL_PACK_SKIP_ROWS, destY );
+      gl.glPixelStorei( GL.GL_PACK_SKIP_PIXELS, destX );
+      gl.glPixelStorei( GL.GL_PACK_ALIGNMENT, 1 );
+
+      /* read the tile into the final image */
+      gl.glReadPixels( srcX, srcY, srcWidth, srcHeight, imageFormat, imageType, imageBuffer );
+    }
+
+    /* restore previous glPixelStore values */
+    gl.glPixelStorei( GL.GL_PACK_ROW_LENGTH, prevRowLength[ 0 ] );
+    gl.glPixelStorei( GL.GL_PACK_SKIP_ROWS, prevSkipRows[ 0 ] );
+    gl.glPixelStorei( GL.GL_PACK_SKIP_PIXELS, prevSkipPixels[ 0 ] );
+    gl.glPixelStorei( GL.GL_PACK_ALIGNMENT, prevAlignment[ 0 ] );
+
+    /* increment tile counter, return 1 if more tiles left to render */
+    currentTile++;
+    if( currentTile >= rows * columns ) {
+      /* restore user's viewport */
+      gl.glViewport( viewportSave[ 0 ], viewportSave[ 1 ], viewportSave[ 2 ], viewportSave[ 3 ] );
+      currentTile = -1; /* all done */
+      return false;
+    } else {
+      return true;
+    }
+  }
+
+  /**
+   * Tile rendering causes problems with using glRasterPos3f, so you
+   * should use this replacement instead
+   * 
+   * @param x
+   *           As in glRasterPos3f
+   * @param y
+   *           As in glRasterPos3f
+   * @param z
+   *           As in glRasterPos3f
+   * @param gl
+   *           The gl context
+   * @param glu
+   *           A GLU object
+   */
+  public void trRasterPos3f( float x, float y, float z, GL gl, GLU glu )
+  {
+    if (currentTile < 0) {
+      /* not doing tile rendering right now. Let OpenGL do this. */
+      gl.glRasterPos3f( x, y, z );
+    } else {
+      double[] modelview = new double[ 16 ], proj = new double[ 16 ];
+      int[] viewport = new int[ 4 ];
+      double[] win = new double[3];
+
+      /* Get modelview, projection and viewport */
+      gl.glGetDoublev( GL.GL_MODELVIEW_MATRIX, modelview, 0 );
+      gl.glGetDoublev( GL.GL_PROJECTION_MATRIX, proj, 0 );
+      viewport[ 0 ] = 0;
+      viewport[ 1 ] = 0;
+      viewport[ 2 ] = currentTileWidth;
+      viewport[ 3 ] = currentTileHeight;
+
+      /* Project object coord to window coordinate */
+      if( glu.gluProject( x, y, z, modelview, 0, proj, 0, viewport, 0, win, 0 ) ) {
+
+        /* set raster pos to window coord (0,0) */
+        gl.glMatrixMode( GL.GL_MODELVIEW );
+        gl.glPushMatrix();
+        gl.glLoadIdentity();
+        gl.glMatrixMode( GL.GL_PROJECTION );
+        gl.glPushMatrix();
+        gl.glLoadIdentity();
+        gl.glOrtho( 0.0, currentTileWidth, 0.0, currentTileHeight, 0.0, 1.0 );
+        gl.glRasterPos3d( 0.0, 0.0, -win[ 2 ] );
+
+        /*
+         * Now use empty bitmap to adjust raster position to
+         * (winX,winY)
+         */
+        {
+          byte[] bitmap = { 0 };
+          gl.glBitmap( 1, 1, 0.0f, 0.0f, ( float ) win[ 0 ], ( float ) win[ 1 ], bitmap , 0 );
+        }
+
+        /* restore original matrices */
+        gl.glPopMatrix(); /* proj */
+        gl.glMatrixMode( GL.GL_MODELVIEW );
+        gl.glPopMatrix();
+      }
+    }
+  }
+}