com.jogamp.opengl.util

## Class TileRendererBase

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

- Direct Known Subclasses:
    RandomTileRenderer, TileRenderer

      public abstract class TileRendererBase
      extends Object

  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 `GL` and `GL2ES3`, abstracted to suit `TileRenderer` and `RandomTileRenderer`.

  ##### PMV Matrix Considerations

  The PMV matrix needs to be reshaped in user code after calling `beginTile(GL)`, See `beginTile(GL)`.

  If `attaching to` an `GLAutoDrawable`, the `TileRendererBase.TileRendererListener.reshapeTile(TileRendererBase, int, int, int, int, int, int)` method is being called after `beginTile(GL)` for each rendered tile. It's implementation shall reshape the PMV matrix according to `beginTile(GL)`.

  ##### GL Profile Requirement

  Note that `image buffer` can only be used in conjunction w/ a `GL` instance ≥ `GL2ES3` passed to `beginTile(GL)` and `endTile(GL)`.
  This is due to setting up the `pack row length` for an `image width` != tile-width, which usually is the case.
  Hence a `GLException` is thrown in both methods, if using an `image buffer` and passing a `GL` instance < `GL2ES3`.

  Further more, reading back of MSAA buffers is only supported since `GL2ES3` since it requires to set the `read-buffer`.

  Author:
    ryanm, sgothel

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `TileRendererBase.TileRendererListener` Listener for tile renderer events, intended to extend `GLEventListener` implementations, enabling tile rendering via `attachAutoDrawable(GLAutoDrawable)`.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `TR_CURRENT_TILE_HEIGHT` The height of the current tile.
    `static int` | `TR_CURRENT_TILE_WIDTH` The width of the current tile.
    `static int` | `TR_CURRENT_TILE_X_POS` The x-pos of the current tile.
    `static int` | `TR_CURRENT_TILE_Y_POS` The y-pos of the current tile.
    `static int` | `TR_IMAGE_HEIGHT` The height of the final image.
    `static int` | `TR_IMAGE_WIDTH` The width of the final image.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `attachAutoDrawable(GLAutoDrawable glad)` Attaches the given `GLAutoDrawable` to this tile renderer.
    `abstract void` | `beginTile(GL gl)` Begins rendering a tile.
    `void` | `detachAutoDrawable()` Detaches the given `GLAutoDrawable` from this tile renderer.
    `void` | `display()` Rendering one tile, by simply calling `GLAutoDrawable.display()`.
    `abstract void` | `endTile(GL gl)` Must be called after rendering the scene, see `beginTile(GL)`.
    `abstract boolean` | `eot()` Returns true if end of tiling has been reached, otherwise false.
    `GLAutoDrawable` | `getAttachedDrawable()` Returns a previously `attached` `GLAutoDrawable`, `null` if none is attached.
    `GLPixelBuffer` | `getImageBuffer()`
    `DimensionImmutable` | `getImageSize()`
    `abstract int` | `getParam(int pname)` Gets the parameters of this TileRenderer object
    `GLPixelBuffer` | `getTileBuffer()`
    `abstract boolean` | `isSetup()` Returns true if this instance is setup properly, i.e.
    `boolean` | `reqPreSwapBuffers(GLCapabilitiesImmutable chosenCaps)` Determines whether the chosen `GLCapabilitiesImmutable` requires a pre-`swap-buffers` before accessing the results, i.e.
    `abstract void` | `reset()` Method resets implementation's internal state to start of tiling as required for `beginTile(GL)` if `end of tiling` has been reached.
    `void` | `setGLEventListener(GLEventListener preTile, GLEventListener postTile)` Set `GLEventListener` for pre- and post operations when used w/ `attachAutoDrawable(GLAutoDrawable)` for each `GLEventListener` callback.
    `void` | `setImageBuffer(GLPixelBuffer buffer)` Sets the buffer in which to store the final image
    `void` | `setImageSize(int width, int height)` Sets the desired size of the final image
    `void` | `setTileBuffer(GLPixelBuffer buffer)` Specify a buffer the tiles to be copied to.
    `String` | `toString()`
    `StringBuilder` | `toString(StringBuilder sb)`

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

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

- - ### Field Detail

    - #### TR_IMAGE_WIDTH

          public static final int TR_IMAGE_WIDTH

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

    - #### TR_IMAGE_HEIGHT

          public static final int TR_IMAGE_HEIGHT

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

    - #### TR_CURRENT_TILE_X_POS

          public static final int TR_CURRENT_TILE_X_POS

      The x-pos of the current tile. See `getParam(int)`.
      See Also:
        Constant Field Values

    - #### TR_CURRENT_TILE_Y_POS

          public static final int TR_CURRENT_TILE_Y_POS

      The y-pos of the current tile. See `getParam(int)`.
      See Also:
        Constant Field Values

    - #### TR_CURRENT_TILE_WIDTH

          public static final int TR_CURRENT_TILE_WIDTH

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

    - #### TR_CURRENT_TILE_HEIGHT

          public static final int TR_CURRENT_TILE_HEIGHT

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

  - ### Method Detail

    - #### toString

          public StringBuilder toString(StringBuilder sb)

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### getParam

          public abstract int getParam(int pname)
                                throws IllegalArgumentException

      Gets the parameters of this TileRenderer object
      Parameters:
        `pname` - The parameter name that is to be retrieved
      Returns:
        the value of the parameter
      Throws:
        `IllegalArgumentException` - if `pname` is not handled

    - #### setTileBuffer

          public final void setTileBuffer(GLPixelBuffer buffer)

      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.
      Parameters:
        `buffer` - The buffer itself. Must be large enough to contain a random tile

    - #### getTileBuffer

          public final GLPixelBuffer getTileBuffer()

      See Also:
        `setTileBuffer(GLPixelBuffer)`

    - #### setImageSize

          public void setImageSize(int width,
                          int height)

      Sets the desired size of the final image
      Parameters:
        `width` - The width of the final image
        `height` - The height of the final image

    - #### getImageSize

          public final DimensionImmutable getImageSize()

      See Also:
        `setImageSize(int, int)`

    - #### setImageBuffer

          public final void setImageBuffer(GLPixelBuffer buffer)

      Sets the buffer in which to store the final image
      Parameters:
        `buffer` - the buffer itself, must be large enough to hold the final image

    - #### getImageBuffer

          public final GLPixelBuffer getImageBuffer()

      See Also:
        `setImageBuffer(GLPixelBuffer)`

    - #### isSetup

          public abstract boolean isSetup()

      Returns true if this instance is setup properly, i.e. `setImageSize(int, int)` .., and ready for `beginTile(GL)`. Otherwise returns false.

    - #### eot

          public abstract 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 `reset()` tiling after reaching end of tiling before calling `beginTile(GL)` again.

    - #### reset

          public abstract void reset()

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

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

    - #### beginTile

          public abstract 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 `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 `endTile(GL)`.

      User has to comply with the GL profile requirement.

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

      Parameters:
        `gl` - The gl context
      Throws:
        `IllegalStateException` - if `image-size` is undefined, an `implementation related setup` has not be performed or has been reached. See implementing classes.
        `GLException` - if `image buffer` is used but `gl` instance is < `GL2ES3`
      See Also:
        `isSetup()`, `eot()`, `reset()`

    - #### endTile

          public abstract void endTile(GL gl)
                                throws IllegalStateException,
                                       GLException

      Must be called after rendering the scene, see `beginTile(GL)`.

      Please consider `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.

      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`

    - #### reqPreSwapBuffers

          public final boolean reqPreSwapBuffers(GLCapabilitiesImmutable chosenCaps)

      Determines whether the chosen `GLCapabilitiesImmutable` requires a pre-`swap-buffers` before accessing the results, i.e. before `endTile(GL)`.

      See `GLDrawableUtil.swapBuffersBeforeRead(GLCapabilitiesImmutable)`.

    - #### attachAutoDrawable

          public final void attachAutoDrawable(GLAutoDrawable glad)
                                        throws IllegalStateException

      Attaches the given `GLAutoDrawable` to this tile renderer.

      The `GLAutoDrawable`'s original `GLEventListener` are moved to this tile renderer.

      `GLEventListeners` not implementing `TileRendererBase.TileRendererListener` are ignored while tile rendering.

      The `GLAutoDrawable`'s `auto-swap mode` is cached and set to `false`, since `swapBuffers()` maybe issued before `endTile(GL)`, see `reqPreSwapBuffers(GLCapabilitiesImmutable)`.

      This tile renderer's internal `GLEventListener` is then added to the attached `GLAutoDrawable` to handle the tile rendering, replacing the original `GLEventListener`.
      It's `display` implementations issues:

      - Optional `pre-glel`.`display(..)`
      - `beginTile(GL)`
      - for all original `TileRendererBase.TileRendererListener`:
        - `reshapeTile(tileX, tileY, tileWidth, tileHeight, imageWidth, imageHeight)`
        - `display(autoDrawable)`
      - if ( `pre-swap` ) { `swapBuffers()` }
      - `endTile(GL)`
      - if ( !`pre-swap` ) { `swapBuffers()` }
      - Optional `post-glel`.`display(..)`

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

      Call `detachAutoDrawable()` to remove the attached `GLAutoDrawable` from this tile renderer and to restore it's original `GLEventListener`.

      Parameters:
        `glad` - the `GLAutoDrawable` to attach.
      Throws:
        `IllegalStateException` - if an `GLAutoDrawable` is already attached
      See Also:
        `getAttachedDrawable()`, `detachAutoDrawable()`

    - #### getAttachedDrawable

          public final GLAutoDrawable getAttachedDrawable()

      Returns a previously `attached` `GLAutoDrawable`, `null` if none is attached.

      If called from `TileRendererBase.TileRendererListener.addTileRendererNotify(TileRendererBase)` or `TileRendererBase.TileRendererListener.removeTileRendererNotify(TileRendererBase)`, method returns the just attached or soon to be detached `GLAutoDrawable`.

      See Also:
        `attachAutoDrawable(GLAutoDrawable)`, `detachAutoDrawable()`

    - #### detachAutoDrawable

          public final void detachAutoDrawable()

      Detaches the given `GLAutoDrawable` from this tile renderer.
      See Also:
        `attachAutoDrawable(GLAutoDrawable)`, `getAttachedDrawable()`

    - #### setGLEventListener

          public final void setGLEventListener(GLEventListener preTile,
                                GLEventListener postTile)

      Set `GLEventListener` for pre- and post operations when used w/ `attachAutoDrawable(GLAutoDrawable)` for each `GLEventListener` callback.
      Parameters:
        `preTile` - the pre operations
        `postTile` - the post operations

    - #### display

          public final void display()
                             throws IllegalStateException

      Rendering one tile, by simply calling `GLAutoDrawable.display()`.
      Throws:
        `IllegalStateException` - if no `GLAutoDrawable` is `attached` or imageSize is not set

Copyright 2010 JogAmp Community.