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	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	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

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method	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 {@ link #eot()} 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

Class TileRendererBase

PMV Matrix Considerations

GL Profile Requirement

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

TR_IMAGE_WIDTH

TR_IMAGE_HEIGHT

TR_CURRENT_TILE_X_POS

TR_CURRENT_TILE_Y_POS

TR_CURRENT_TILE_WIDTH

TR_CURRENT_TILE_HEIGHT

Method Detail

toString

toString

getParam

setTileBuffer

getTileBuffer

setImageSize

getImageSize

setImageBuffer

getImageBuffer

isSetup

eot

reset

beginTile

endTile

reqPreSwapBuffers

attachAutoDrawable

getAttachedDrawable

detachAutoDrawable

setGLEventListener

display