Top Description Inners Fields Constructors Methods
com.jogamp.opengl.util

public abstract Class TileRendererBase

extends Object
Class Inheritance
Known Direct Subclasses
com.jogamp.opengl.util.RandomTileRenderer, com.jogamp.opengl.util.TileRenderer
Imports
com.jogamp.nativewindow.util.Dimension, .DimensionImmutable, com.jogamp.opengl.GL, .GL2ES3, .GLAutoDrawable, .GLCapabilitiesImmutable, .GLDrawable, .GLEventListener, .GLException, jogamp.opengl.Debug

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 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 and Inner Type Summary

Modifier and TypeClass and Description
public static interface
TileRendererBase.TileRendererListener

Listener for tile renderer events, intended to extend GLEventListener implementations, enabling tile rendering via TileRendererBase#attachAutoDrawable(GLAutoDrawable).

Field Summary

Modifier and TypeField and Description
protected boolean
protected int
protected int
protected int
protected int
pack-priv static final boolean
protected GLAutoDrawable
protected boolean
protected boolean
protected GLEventListener
protected GLEventListener
protected GLPixelBuffer
protected final Dimension
protected GLEventListener[]
protected boolean[]
protected final GLPixelStorageModes
protected GLPixelBuffer
private final GLEventListener
public static final int
TR_CURRENT_TILE_HEIGHT

The height of the current tile.

public static final int
TR_CURRENT_TILE_WIDTH

The width of the current tile.

public static final int
TR_CURRENT_TILE_X_POS

The x-pos of the current tile.

public static final int
TR_CURRENT_TILE_Y_POS

The y-pos of the current tile.

public static final int
TR_IMAGE_HEIGHT

The height of the final image.

public static final int
TR_IMAGE_WIDTH

The width of the final image.

Constructor Summary

AccessConstructor and Description
protected

Method Summary

Modifier and TypeMethod and Description
public final void
attachAutoDrawable(final GLAutoDrawable
the GLAutoDrawable to attach.
glad
)

Attaches the given GLAutoDrawable to this tile renderer.

public abstract void
beginTile(GL
The gl context
gl
)

Begins rendering a tile.

public final void
detachAutoDrawable()

Detaches the given GLAutoDrawable from this tile renderer.

public final void
display()

Rendering one tile, by simply calling GLAutoDrawable#display().

public abstract void
endTile(GL
the gl context
gl
)

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

public abstract boolean
eot()

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

public final GLAutoDrawable
getAttachedDrawable()

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

public final GLPixelBuffer
public final DimensionImmutable
public abstract int

Returns:

the value of the parameter
getParam
(int
The parameter name that is to be retrieved
pname
)

Gets the parameters of this TileRenderer object

public final GLPixelBuffer
private final String
hashStr(final Object o)

public abstract boolean
isSetup()

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

public final boolean
reqPreSwapBuffers(final GLCapabilitiesImmutable chosenCaps)

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

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.

public final void
setGLEventListener(final GLEventListener
the pre operations
preTile
,
final GLEventListener
the post operations
postTile
)

Set GLEventListener for pre- and post operations when used w/ attachAutoDrawable(GLAutoDrawable) for each GLEventListener callback.

public final void
setImageBuffer(final GLPixelBuffer
the buffer itself, must be large enough to hold the final image
buffer
)

Sets the buffer in which to store the final image

public void
setImageSize(final int
The width of the final image
width
,
final int
The height of the final image
height
)

Sets the desired size of the final image

public final void
setTileBuffer(final GLPixelBuffer
The buffer itself. Must be large enough to contain a random tile
buffer
)

Specify a buffer the tiles to be copied to.

protected StringBuilder
public StringBuilder
public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
pack-priv final void
validateGL(final GL gl)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

beginCalledback to summary
protected boolean beginCalled
currentTileHeightback to summary
protected int currentTileHeight
currentTileWidthback to summary
protected int currentTileWidth
currentTileXPosback to summary
protected int currentTileXPos
currentTileYPosback to summary
protected int currentTileYPos
DEBUGback to summary
pack-priv static final boolean DEBUG
gladback to summary
protected GLAutoDrawable glad
gladAutoSwapBufferModeback to summary
protected boolean gladAutoSwapBufferMode
gladRequiresPreSwapback to summary
protected boolean gladRequiresPreSwap
glEventListenerPostback to summary
protected GLEventListener glEventListenerPost
glEventListenerPreback to summary
protected GLEventListener glEventListenerPre
imageBufferback to summary
protected GLPixelBuffer imageBuffer
imageSizeback to summary
protected final Dimension imageSize
listenersback to summary
protected GLEventListener[] listeners
listenersInitback to summary
protected boolean[] listenersInit
psmback to summary
protected final GLPixelStorageModes psm
tileBufferback to summary
protected GLPixelBuffer tileBuffer
tiledGLELback to summary
private final GLEventListener tiledGLEL
TR_CURRENT_TILE_HEIGHTback to summary
public static final int TR_CURRENT_TILE_HEIGHT

The height of the current tile. See getParam(int).

TR_CURRENT_TILE_WIDTHback to summary
public static final int TR_CURRENT_TILE_WIDTH

The width of the current tile. See getParam(int).

TR_CURRENT_TILE_X_POSback to summary
public static final int TR_CURRENT_TILE_X_POS

The x-pos of the current tile. See getParam(int).

TR_CURRENT_TILE_Y_POSback to summary
public static final int TR_CURRENT_TILE_Y_POS

The y-pos of the current tile. See getParam(int).

TR_IMAGE_HEIGHTback to summary
public static final int TR_IMAGE_HEIGHT

The height of the final image. See getParam(int).

TR_IMAGE_WIDTHback to summary
public static final int TR_IMAGE_WIDTH

The width of the final image. See getParam(int).

Constructor Detail

TileRendererBaseback to summary
protected TileRendererBase()

Method Detail

attachAutoDrawableback to summary
public final void attachAutoDrawable(final 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 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:

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

the GLAutoDrawable to attach.

Exceptions
IllegalStateException:
if an GLAutoDrawable is already attached
See Also
getAttachedDrawable(), detachAutoDrawable()
beginTileback to summary
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:

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

The gl context

Exceptions
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()
detachAutoDrawableback to summary
public final void detachAutoDrawable()

Detaches the given GLAutoDrawable from this tile renderer.

See Also
attachAutoDrawable(GLAutoDrawable), getAttachedDrawable()
displayback to summary
public final void display() throws IllegalStateException

Rendering one tile, by simply calling GLAutoDrawable#display().

Exceptions
IllegalStateException:
if no GLAutoDrawable is attached or imageSize is not set
endTileback to summary
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:GL

the gl context

Exceptions
IllegalStateException:
if beginTile(gl) has not been called
GLException:
if image buffer is used but gl instance is < GL2ES3
eotback to summary
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.

getAttachedDrawableback to summary
public final GLAutoDrawable getAttachedDrawable()

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

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

See Also
attachAutoDrawable(GLAutoDrawable), detachAutoDrawable()
getImageBufferback to summary
public final GLPixelBuffer getImageBuffer()
See Also
setImageBuffer(GLPixelBuffer)
getImageSizeback to summary
public final DimensionImmutable getImageSize()
See Also
setImageSize(int, int)
getParamback to summary
public abstract int getParam(int pname) throws IllegalArgumentException

Gets the parameters of this TileRenderer object

Parameters
pname:int

The parameter name that is to be retrieved

Returns:int

the value of the parameter

Exceptions
IllegalArgumentException:
if pname is not handled
getTileBufferback to summary
public final GLPixelBuffer getTileBuffer()
See Also
setTileBuffer(GLPixelBuffer)
hashStrback to summary
private final String hashStr(final Object o)
isSetupback to summary
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.

reqPreSwapBuffersback to summary
public final boolean reqPreSwapBuffers(final 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).

resetback to summary
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.

setGLEventListenerback to summary
public final void setGLEventListener(final GLEventListener preTile, final GLEventListener postTile)

Set GLEventListener for pre- and post operations when used w/ attachAutoDrawable(GLAutoDrawable) for each GLEventListener callback.

Parameters
preTile:GLEventListener

the pre operations

postTile:GLEventListener

the post operations

setImageBufferback to summary
public final void setImageBuffer(final GLPixelBuffer buffer)

Sets the buffer in which to store the final image

Parameters
buffer:GLPixelBuffer

the buffer itself, must be large enough to hold the final image

setImageSizeback to summary
public void setImageSize(final int width, final int height)

Sets the desired size of the final image

Parameters
width:int

The width of the final image

height:int

The height of the final image

setTileBufferback to summary
public final void setTileBuffer(final 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:GLPixelBuffer

The buffer itself. Must be large enough to contain a random tile

tileDetailsback to summary
protected StringBuilder tileDetails(final StringBuilder sb)
toStringback to summary
public StringBuilder toString(final StringBuilder sb)
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object

Annotations
@Override
validateGLback to summary
pack-priv final void validateGL(final GL gl) throws GLException
com.jogamp.opengl.util back to summary

public Interface TileRendererBase.TileRendererListener


Listener for tile renderer events, intended to extend GLEventListener implementations, enabling tile rendering via TileRendererBase#attachAutoDrawable(GLAutoDrawable).

Method Summary

Modifier and TypeMethod and Description
public void
public void
public void
removeTileRendererNotify(TileRendererBase
the disassociated TileRendererBase
tr
)

The owning GLAutoDrawable is detached from the given TileRendererBase instance.

public void
reshapeTile(TileRendererBase
the issuing TileRendererBase
tr
,
int tileX, int tileY, int tileWidth, int tileHeight, int imageWidth, int imageHeight)

Called by the TileRendererBase during tile-rendering via an attached GLAutoDrawable's GLAutoDrawable#display() call for each tile before display(GLAutoDrawable).

public void
startTileRendering(TileRendererBase
the issuing TileRendererBase
tr
)

Called by the TileRendererBase during tile-rendering after TileRendererBase#beginTile(GL) and before reshapeTile(..).

Method Detail

addTileRendererNotifyback to summary
public void addTileRendererNotify(TileRendererBase tr)

The owning GLAutoDrawable is attached to the given TileRendererBase instance.

The GLContext of the TileRendererBase's attached GLAutoDrawable is not current.

Parameters
tr:TileRendererBase

the associated TileRendererBase

See Also
TileRendererBase#getAttachedDrawable()
endTileRenderingback to summary
public void endTileRendering(TileRendererBase tr)

Called by the TileRenderer during tile-rendering after TileRendererBase#endTile(GL) and GLAutoDrawable#swapBuffers().

If TileRendererBase is of type TileRenderer, method is called for the last tile of all tiles.
Otherwise, i.e. RandomTileRenderer, method is called for each particular tile.

The GLContext of the TileRenderer's attached GLAutoDrawable is current.

Parameters
tr:TileRendererBase

the issuing TileRendererBase

removeTileRendererNotifyback to summary
public void removeTileRendererNotify(TileRendererBase tr)

The owning GLAutoDrawable is detached from the given TileRendererBase instance.

The GLContext of the TileRendererBase's attached GLAutoDrawable is not current.

Parameters
tr:TileRendererBase

the disassociated TileRendererBase

See Also
TileRendererBase#getAttachedDrawable()
reshapeTileback to summary
public void reshapeTile(TileRendererBase tr, int tileX, int tileY, int tileWidth, int tileHeight, int imageWidth, int imageHeight)

Called by the TileRendererBase during tile-rendering via an attached GLAutoDrawable's GLAutoDrawable#display() call for each tile before display(GLAutoDrawable).

The PMV Matrix shall be reshaped according to the given

  • current tile-position
  • current tile-size
  • final image-size
The GL viewport is already set to origin 0/0 and the current tile-size.
See details in TileRendererBase#beginTile(GL).

The GLContext of the TileRendererBase's attached GLAutoDrawable is current.

Parameters
tr:TileRendererBase

the issuing TileRendererBase

tileX:int

the current tile's x-pos

tileY:int

the current tile's y-pos

tileWidth:int

the current tile's width

tileHeight:int

the current tile's height

imageWidth:int

the final image width

imageHeight:int

the final image height

See Also
TileRendererBase#getAttachedDrawable()
startTileRenderingback to summary
public void startTileRendering(TileRendererBase tr)

Called by the TileRendererBase during tile-rendering after TileRendererBase#beginTile(GL) and before reshapeTile(..).

If TileRendererBase is of type TileRenderer, method is called for the first tile of all tiles.
Otherwise, i.e. RandomTileRenderer, method is called for each particular tile.

The GLContext of the TileRenderer's attached GLAutoDrawable is current.

Parameters
tr:TileRendererBase

the issuing TileRendererBase