com.jogamp.opengl.util

## Class TileRenderer

- java.lang.Object
- - com.jogamp.opengl.util.TileRendererBase
  - - com.jogamp.opengl.util.TileRenderer

-     public class TileRenderer
      extends TileRendererBase

  A fairly direct port of Brian Paul's tile rendering library, found at http://www.mesa3d.org/brianp/TR.html . 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.

  Enhanced for `GL2ES3`.

  See `TileRendererBase` for details.

  Author:
    ryanm, sgothel

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class com.jogamp.opengl.util.TileRendererBase

      `TileRendererBase.TileRendererListener`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `TR_BOTTOM_TO_TOP` Indicates we are traversing rows from the bottom to the top (default).
    `static int` | `TR_COLUMNS` The number of columns of tiles.
    `static int` | `TR_CURRENT_COLUMN` The current column number.
    `static int` | `TR_CURRENT_ROW` The current row number.
    `static int` | `TR_CURRENT_TILE_NUM` The current tile number.
    `static int` | `TR_IMAGE_CLIPPING_HEIGHT` The height of the final clipped image.
    `static int` | `TR_IMAGE_CLIPPING_WIDTH` The width of the final clipped image.
    `static int` | `TR_ROW_ORDER` The order that the rows are traversed.
    `static int` | `TR_ROWS` The number of rows of tiles.
    `static int` | `TR_TILE_BORDER` The width of the border around the tiles.
    `static int` | `TR_TILE_HEIGHT` The height of the tiles.
    `static int` | `TR_TILE_WIDTH` The width of the tiles.
    `static int` | `TR_TILE_X_OFFSET` The tiles x-offset.
    `static int` | `TR_TILE_Y_OFFSET` The tiles y-offset.
    `static int` | `TR_TOP_TO_BOTTOM` Indicates we are traversing rows from the top to the bottom.

    - ### Fields inherited from class com.jogamp.opengl.util.TileRendererBase

      `TR_CURRENT_TILE_HEIGHT, TR_CURRENT_TILE_WIDTH, TR_CURRENT_TILE_X_POS, TR_CURRENT_TILE_Y_POS, TR_IMAGE_HEIGHT, TR_IMAGE_WIDTH`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TileRenderer()` Creates a new TileRenderer object

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `beginTile(GL gl)` Begins rendering a tile.
    `void` | `clipImageSize(int width, int height)` Clips the image-size this tile-renderer iterates through, which can be retrieved via `getClippedImageSize()`.
    `void` | `endTile(GL gl)` Must be called after rendering the scene, see `TileRendererBase.beginTile(GL)`.
    `boolean` | `eot()` Returns true if end of tiling has been reached, otherwise false.
    `DimensionImmutable` | `getClippedImageSize()` Returns the clipped image-size.
    `int` | `getParam(int pname)` Gets the parameters of this TileRenderer object
    `boolean` | `isSetup()` Returns true if this instance is setup properly, i.e.
    `void` | `reset()` Method resets implementation's internal state to start of tiling as required for `TileRendererBase.beginTile(GL)` if `end of tiling` has been reached.
    `void` | `setImageSize(int width, int height)` Sets the desired size of the final image
    `void` | `setRowOrder(int order)` Sets the order of row traversal, default is `TR_BOTTOM_TO_TOP`.
    `void` | `setTileOffset(int xoff, int yoff)` Sets an xy offset for the resulting tiles `x-pos` and `y-pos`.
    `void` | `setTileSize(int width, int height, int border)` Sets the size of the tiles to use in rendering.

    - ### Methods inherited from class com.jogamp.opengl.util.TileRendererBase

      `attachAutoDrawable, detachAutoDrawable, display, getAttachedDrawable, getImageBuffer, getImageSize, getTileBuffer, reqPreSwapBuffers, setGLEventListener, setImageBuffer, setTileBuffer, toString, toString`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### TR_IMAGE_CLIPPING_WIDTH

          public static final int TR_IMAGE_CLIPPING_WIDTH

      The width of the final clipped image. See `getParam(int)`.
      See Also:
        Constant Field Values

    - #### TR_IMAGE_CLIPPING_HEIGHT

          public static final int TR_IMAGE_CLIPPING_HEIGHT

      The height of the final clipped image. See `getParam(int)`.
      See Also:
        Constant Field Values

    - #### TR_TILE_WIDTH

          public static final int TR_TILE_WIDTH

      The width of the tiles. See `getParam(int)`.
      See Also:
        Constant Field Values

    - #### TR_TILE_HEIGHT

          public static final int TR_TILE_HEIGHT

      The height of the tiles. See `getParam(int)`.
      See Also:
        Constant Field Values

    - #### TR_TILE_BORDER

          public static final int TR_TILE_BORDER

      The width of the border around the tiles. See `getParam(int)`.
      See Also:
        Constant Field Values

    - #### TR_TILE_X_OFFSET

          public static final int TR_TILE_X_OFFSET

      The tiles x-offset. See `getParam(int)`.
      See Also:
        Constant Field Values

    - #### TR_TILE_Y_OFFSET

          public static final int TR_TILE_Y_OFFSET

      The tiles y-offset. See `getParam(int)`.
      See Also:
        Constant Field Values

    - #### TR_ROWS

          public static final int TR_ROWS

      The number of rows of tiles. See `getParam(int)`.
      See Also:
        Constant Field Values

    - #### TR_COLUMNS

          public static final int TR_COLUMNS

      The number of columns of tiles. See `getParam(int)`.
      See Also:
        Constant Field Values

    - #### TR_CURRENT_TILE_NUM

          public static final int TR_CURRENT_TILE_NUM

      The current tile number. Has value -1 if `eot()`. See `getParam(int)`.
      See Also:
        Constant Field Values

    - #### TR_CURRENT_ROW

          public static final int TR_CURRENT_ROW

      The current row number. See `getParam(int)`.
      See Also:
        Constant Field Values

    - #### TR_CURRENT_COLUMN

          public static final int TR_CURRENT_COLUMN

      The current column number. See `getParam(int)`.
      See Also:
        Constant Field Values

    - #### TR_ROW_ORDER

          public static final int TR_ROW_ORDER

      The order that the rows are traversed. See `getParam(int)`.
      See Also:
        Constant Field Values

    - #### TR_TOP_TO_BOTTOM

          public static final int TR_TOP_TO_BOTTOM

      Indicates we are traversing rows from the top to the bottom. See `getParam(int)`.
      See Also:
        Constant Field Values

    - #### TR_BOTTOM_TO_TOP

          public static final int TR_BOTTOM_TO_TOP

      Indicates we are traversing rows from the bottom to the top (default). See `getParam(int)`.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### TileRenderer

          public TileRenderer()

      Creates a new TileRenderer object

  - ### Method Detail

    - #### setImageSize

          public final void setImageSize(int width,
                          int height)

      Sets the desired size of the final image

      Implementation `reset()` internal states.

      Overrides:
        `setImageSize` in class `TileRendererBase`
      Parameters:
        `width` - The width of the final image
        `height` - The height of the final image

    - #### clipImageSize

          public final void clipImageSize(int width,
                           int height)

      Clips the image-size this tile-renderer iterates through, which can be retrieved via `getClippedImageSize()`.

      Original image-size stored in this tile-renderer is unmodified.

      Implementation `reset()` internal states.

      Parameters:
        `width` - The image-clipping.width
        `height` - The image-clipping.height
      See Also:
        `getClippedImageSize()`

    - #### getClippedImageSize

          public final DimensionImmutable getClippedImageSize()

      Returns the clipped image-size.

      If a image-size is clipped via `clipImageSize(int, int)`, method returns:

      - `min( image-clipping, image-size )`, otherwise
      - `image-size`

      The clipping width and height can be retrieved via `TR_IMAGE_CLIPPING_WIDTH` `TR_IMAGE_CLIPPING_HEIGHT`.

    - #### setTileSize

          public final void setTileSize(int width,
                         int height,
                         int border)

      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 )

      Implementation `reset()` internal states.

      Parameters:
        `width` - The width of the tiles. Must not be larger than the GL context
        `height` - The height of the tiles. Must not be larger than the GL context
        `border` - The width of the borders on each tile. This is needed to avoid artifacts when rendering lines or points with thickness > 1.

    - #### setTileOffset

          public void setTileOffset(int xoff,
                           int yoff)

      Sets an xy offset for the resulting tiles `x-pos` and `y-pos`.
      See Also:
        `TR_TILE_X_OFFSET`, `TR_TILE_Y_OFFSET`

    - #### reset

          public final void reset()

      Method resets implementation's internal state to start of tiling as required for `TileRendererBase.beginTile(GL)` if `end of tiling` has been reached.

      Implementation is a nop where `end of tiling` is never reached.

      Reset internal states of `TileRenderer` are:
      - `TR_ROWS`
      - `TR_COLUMNS`
      - `TR_CURRENT_COLUMN`
      - `TR_CURRENT_ROW`
      - `TR_CURRENT_TILE_NUM`
      - `TileRendererBase.TR_CURRENT_TILE_X_POS`
      - `TileRendererBase.TR_CURRENT_TILE_Y_POS`
      - `TileRendererBase.TR_CURRENT_TILE_WIDTH`
      - `TileRendererBase.TR_CURRENT_TILE_HEIGHT`
      Specified by:
        `reset` in class `TileRendererBase`

    - #### getParam

          public final int getParam(int pname)

      Description copied from class: `TileRendererBase`
      Gets the parameters of this TileRenderer object
      Specified by:
        `getParam` in class `TileRendererBase`
      Parameters:
        `pname` - The parameter name that is to be retrieved
      Returns:
        the value of the parameter

    - #### setRowOrder

          public final void setRowOrder(int order)

      Sets the order of row traversal, default is `TR_BOTTOM_TO_TOP`.
      Parameters:
        `order` - The row traversal order, must be either `TR_TOP_TO_BOTTOM` or `TR_BOTTOM_TO_TOP`.

    - #### isSetup

          public final boolean isSetup()

      Description copied from class: `TileRendererBase`
      Returns true if this instance is setup properly, i.e. `TileRendererBase.setImageSize(int, int)` .., and ready for `TileRendererBase.beginTile(GL)`. Otherwise returns false.
      Specified by:
        `isSetup` in class `TileRendererBase`

    - #### eot

          public final boolean eot()

      Returns true if end of tiling has been reached, otherwise false.

      end of tiling criteria is implementation specific and may never be reached.

      User needs to `TileRendererBase.reset()` tiling after reaching end of tiling before calling `TileRendererBase.beginTile(GL)` again.

      end of tiling is reached w/ `TileRenderer`, if at least one of the following is true:

      - all tiles have been rendered, i.e. `TR_CURRENT_TILE_NUM` is -1
      - no tiles to render, i.e. `TR_COLUMNS` or `TR_ROWS` is 0
      Specified by:
        `eot` in class `TileRendererBase`

    - #### beginTile

          public final void beginTile(GL gl)
                               throws IllegalStateException,
                                      GLException

      Begins rendering a tile.

      This method modifies the viewport, see below. User shall reset the viewport when finishing all tile rendering, i.e. after very last call of `TileRendererBase.endTile(GL)`!

      The PMV Matrix must be reshaped after this call using:

      - Current Viewport
        - x 0
        - y 0
        - `current tile's width`
        - `current tile's height`
      - `current tile's x-pos`
      - `current tile's y-pos`
      - `final image width`
      - `final image height`

      Use shall render the scene afterwards, concluded with a call to this renderer `TileRendererBase.endTile(GL)`.

      User has to comply with the GL profile requirement.

      If `end of tiling` has been reached, user needs to `TileRendererBase.reset()` tiling before calling this method.

      Specified by:
        `beginTile` in class `TileRendererBase`
      Parameters:
        `gl` - The gl context
      Throws:
        `IllegalStateException` - if `image-size` has not been set or `end-of-tiling` has been reached.
        `GLException` - if `image buffer` is used but `gl` instance is < `GL2ES3`
      See Also:
        `TileRendererBase.isSetup()`, `TileRendererBase.eot()`, `TileRendererBase.reset()`

    - #### endTile

          public void endTile(GL gl)
                       throws IllegalStateException,
                              GLException

      Description copied from class: `TileRendererBase`
      Must be called after rendering the scene, see `TileRendererBase.beginTile(GL)`.

      Please consider `TileRendererBase.reqPreSwapBuffers(GLCapabilitiesImmutable)` to determine whether you need to perform `swap-buffers` before or after calling this method!

      User has to comply with the GL profile requirement.

      Specified by:
        `endTile` in class `TileRendererBase`
      Parameters:
        `gl` - the gl context
      Throws:
        `IllegalStateException` - if beginTile(gl) has not been called
        `GLException` - if `image buffer` is used but `gl` instance is < `GL2ES3`

Copyright 2010 JogAmp Community.