org.j3d.aviatrix3d.management
Class MultiThreadRenderManager

java.lang.Object
  org.j3d.aviatrix3d.management.MultiThreadRenderManager

All Implemented Interfaces:

java.lang.Runnable, RenderManager, NodeUpdateHandler

public class MultiThreadRenderManager
extends java.lang.Object
implements java.lang.Runnable, NodeUpdateHandler, RenderManager

Implementation of the RenderManager that uses separate threads for each of the pipelines that it is managing, allowing it to run multiple output surfaces simultaneously (eg Powerwall, CAVE etc).

By default the manager does not start of enabled. An explicit enable call will be needed to kick the management process off.

Change List processing will process bounds changed items before data changed.

Version:

$Revision: 1.10 $

Author:

Justin Couch

Constructor Summary

MultiThreadRenderManager()
Construct a new render manager with no pipelines or renderers registered.

MultiThreadRenderManager(int numDisplays)
Construct a new render manager with no pipelines or renderers registered, but with internal arrays setup for the given number of displays to be added.

Method Summary

void	activeSoundLayerChanged(InternalLayerUpdateListener intL) Notify the handler that you are now going to be the active layer for sound rendering.
void	addDisplay(DisplayCollection collection) Add a dislay collection to be managed.
boolean	boundsChanged(NodeUpdateListener l, java.lang.Object src, InternalNodeUpdateListener intL) Notify the handler that you have updates to the SG that might alter a node's bounds.
void	dataChanged(NodeUpdateListener l, java.lang.Object src) Notify the handler that you have updates to the SG that will not alter a node's bounds.
void	disableInternalShutdown() Disable the internal shutdown hook system.
void	frameFinished() Notification that the frame state has finished management.
int	getMinimumFrameInterval() Fetch the currently set duty cycle value.
PickingManager	getPickingManager() Get the picking handler so that we can do some picking operations.
boolean	isBoundsWritePermitted(java.lang.Object src) Check to see if writing to the node is permitted currently.
boolean	isDataWritePermitted(java.lang.Object src) Check to see if writing to the node is permitted currently.
boolean	isEnabled() Get the current render state of the manager.
boolean	isHaltingOnError() Check to see the current halt on error state.
boolean	isPickingPermitted() Check to see if picking is permitted currently.
void	notifyUpdateRequired() Feedback to the internals that a data object has changed and it requires re-management.
void	removeDisplay(DisplayCollection collection) Remove an already registered display collection from the manager.
void	renderOnce() Force a single render of all pipelines now.
void	requestDeletion(DeletableRenderable deletable) Notification that the passed in renderable is wishing to mark itself ready for deletion processing.
void	requestFullSceneRender() Request that the manager perform a full scene render pass and update, ignoring any usual optimisations that it may take.
void	rescindDeletionRequest(DeletableRenderable deletable) Woops, we were in error, so please rescind that deletion request.
void	run() Run method used to synchronise the internal management state and the external state of the canvas.
void	setApplicationObserver(ApplicationUpdateObserver obs) Register an observer that can be used to know when the application is safe to update the scene graph.
void	setEnabled(boolean state) Tell render to start or stop management.
void	setErrorReporter(org.j3d.util.ErrorReporter reporter) Register an error reporter with the engine so that any errors generated by the node's internals can be reported in a nice, pretty fashion.
void	setHaltOnError(boolean state) Set whether the manager should automatically halt management if an error or exception is detected during the user callback processing.
void	setMinimumFrameInterval(int cycleTime) Set the minimum duty cycle of the render manager.
void	setPickingManager(PickingManager mgr) Set the picking handler to use.
void	shaderRequiresInit(ShaderSourceRenderable shader, boolean updateResponse) The shader object passed requires an initialisation be performed.
void	shaderRequiresLogInfo(ShaderSourceRenderable shader, boolean updateResponse) The shader object passed requires updating the log info.
void	shutdown() Notification to shutdown the internals of the renderer because the application is about to exit.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MultiThreadRenderManager

public MultiThreadRenderManager()

Construct a new render manager with no pipelines or renderers registered. Starts by allocating space for 2 render pipes and 1 audio pipe to be handled.

MultiThreadRenderManager

public MultiThreadRenderManager(int numDisplays)

Construct a new render manager with no pipelines or renderers registered, but with internal arrays setup for the given number of displays to be added.

Parameters:

numDisplays - The initial number of displays to prepare

Method Detail

setErrorReporter

public void setErrorReporter(org.j3d.util.ErrorReporter reporter)

Register an error reporter with the engine so that any errors generated by the node's internals can be reported in a nice, pretty fashion. Setting a value of null will clear the currently set reporter. If one is already set, the new value replaces the old.

Specified by:

setErrorReporter in interface RenderManager

Parameters:

reporter - The instance to use or null

setHaltOnError

public void setHaltOnError(boolean state)

Set whether the manager should automatically halt management if an error or exception is detected during the user callback processing. If this is set to true (the default) then processing immediately halts and sets the state to disabled as soon as an error is detected. The management contexts are not disposed of. We just terminate the current management process if this is detected.

If the value is set to false, then the error is caught, but management continues on regardless.

In both states, the error that is caught is reported through the currently registered ErrorReporter instance as an error message.

Specified by:

setHaltOnError in interface RenderManager

Parameters:

state - true to enable halting, false to disable

isHaltingOnError

public boolean isHaltingOnError()

Check to see the current halt on error state.

Specified by:

isHaltingOnError in interface RenderManager

Returns:

true if the system halts on an error condition

See Also:

setHaltOnError(boolean)

setEnabled

public void setEnabled(boolean state)

Tell render to start or stop management. If currently running, it will wait until all the pipelines have completed their current cycle and will then halt.

Specified by:

setEnabled in interface RenderManager

Parameters:

state - True if to enable management

isEnabled

public boolean isEnabled()

Get the current render state of the manager.

Specified by:

isEnabled in interface RenderManager

Returns:

true if the manager is currently running

renderOnce

public void renderOnce()
                throws java.lang.IllegalStateException

Force a single render of all pipelines now. Ignores the enabled and cycle time settings to cause a single render at this point in time. If a render is currently in progress, an exception is generated

Specified by:

renderOnce in interface RenderManager

Throws:

java.lang.IllegalStateException - The system is currently management and should be disabled first.

requestFullSceneRender

public void requestFullSceneRender()

Request that the manager perform a full scene render pass and update, ignoring any usual optimisations that it may take. For performance reasons, a render manager may elect to not run or update some portions of the scene graph. This method requests that the next frame only should ignore those optimisations and process the full scene graph.

This method will work both in automated management and with the renderOnce() method.

Specified by:

requestFullSceneRender in interface RenderManager

setMinimumFrameInterval

public void setMinimumFrameInterval(int cycleTime)

Set the minimum duty cycle of the render manager. This is the type in milliseconds that should be the minimum between frames and can be used to throttle the management loop to a maximum frame rate should other systems require CPU time.

Specified by:

setMinimumFrameInterval in interface RenderManager

Parameters:

cycleTime - The minimum time in milliseconds between frames

getMinimumFrameInterval

public int getMinimumFrameInterval()

Fetch the currently set duty cycle value.

Specified by:

getMinimumFrameInterval in interface RenderManager

Returns:

The duty cycle time, in milliseconds

addDisplay

public void addDisplay(DisplayCollection collection)
                throws java.lang.IllegalStateException

Add a dislay collection to be managed. A duplicate registration or null value is ignored.

Specified by:

addDisplay in interface RenderManager

Parameters:

collection - The new collection instance to be added

Throws:

java.lang.IllegalStateException - The system is currently management and should be disabled first.

removeDisplay

public void removeDisplay(DisplayCollection collection)
                   throws java.lang.IllegalStateException

Remove an already registered display collection from the manager. A or null value or one that is not currently registered is ignored.

Specified by:

removeDisplay in interface RenderManager

Parameters:

collection - The collection instance to be removed

Throws:

java.lang.IllegalStateException - The system is currently management and should be disabled first.

setPickingManager

public void setPickingManager(PickingManager mgr)
                       throws java.lang.IllegalStateException

Set the picking handler to use. Overrides the default implementation that is used. If null is passed, the code reverts to the default implementation. This can only be set when the manager is not active

Specified by:

setPickingManager in interface RenderManager

Parameters:

mgr - The new pick manager instance to use, or null

Throws:

java.lang.IllegalStateException - The system is currently management and should be disabled first.

setApplicationObserver

public void setApplicationObserver(ApplicationUpdateObserver obs)

Register an observer that can be used to know when the application is safe to update the scene graph. A value of null will remove the currently set value.

Specified by:

setApplicationObserver in interface RenderManager

Parameters:

obs - The observer instance to use

disableInternalShutdown

public void disableInternalShutdown()

Disable the internal shutdown hook system. It will be up to the calling application to make sure the shutdown() method is called to turn off the OpenGL management system. If it does not, there is a good possibility of a crash of the system.

If the internal shutdown is disabled, then the shutdown callback of the ApplicationUpdateObserver will not be called.

Specified by:

disableInternalShutdown in interface RenderManager

shutdown

public void shutdown()

Notification to shutdown the internals of the renderer because the application is about to exit.

Specified by:

shutdown in interface RenderManager

run

public void run()

Run method used to synchronise the internal management state and the external state of the canvas. Should never be called directly.

Specified by:

run in interface java.lang.Runnable

frameFinished

public void frameFinished()

Notification that the frame state has finished management.

isDataWritePermitted

public boolean isDataWritePermitted(java.lang.Object src)

Check to see if writing to the node is permitted currently.

Specified by:

isDataWritePermitted in interface NodeUpdateHandler

Parameters:

src - The object that is requesting the check

Returns:

true if the end user can write, false if not

isBoundsWritePermitted

public boolean isBoundsWritePermitted(java.lang.Object src)

Check to see if writing to the node is permitted currently.

Specified by:

isBoundsWritePermitted in interface NodeUpdateHandler

Parameters:

src - The object that is requesting the check

Returns:

true if the end user can write, false if not

isPickingPermitted

public boolean isPickingPermitted()

Check to see if picking is permitted currently.

Specified by:

isPickingPermitted in interface NodeUpdateHandler

Returns:

true if the end user can pick, false if not

notifyUpdateRequired

public void notifyUpdateRequired()

Feedback to the internals that a data object has changed and it requires re-management. This should only be called by classes that can effect the management but don't normally use the data/bounds write listeners (ie changes are made during the app update portion of the scene graph). Typically this would be used for things like the ViewEnvironment changing the aspect ratio etc.

Specified by:

notifyUpdateRequired in interface NodeUpdateHandler

boundsChanged

public boolean boundsChanged(NodeUpdateListener l,
                             java.lang.Object src,
                             InternalNodeUpdateListener intL)
                      throws InvalidListenerSetTimingException

Notify the handler that you have updates to the SG that might alter a node's bounds.

Specified by:

boundsChanged in interface NodeUpdateHandler

Parameters:

l - The change requestor

src - The object that is passing this listener through.

intL - Internal listener for making callbacks at a later time to propogate the bounds changes.

Returns:

Was the notification accepted. Duplicates will return false.

Throws:

InvalidListenerSetTimingException - If called when the node called during one of the bounds/data changed callbacks

dataChanged

public void dataChanged(NodeUpdateListener l,
                        java.lang.Object src)
                 throws InvalidListenerSetTimingException

Notify the handler that you have updates to the SG that will not alter a node's bounds.

Specified by:

dataChanged in interface NodeUpdateHandler

Parameters:

l - The change requestor

src - The object that is passing this listener through.

Throws:

InvalidListenerSetTimingException - If called when the node called during one of the bounds/data changed callbacks

activeSoundLayerChanged

public void activeSoundLayerChanged(InternalLayerUpdateListener intL)
                             throws InvalidListenerSetTimingException

Notify the handler that you are now going to be the active layer for sound rendering. Note that updating the active sound node means that the other sound node is disabled. This will be called on the data change callback normally. The source object will be an instance of either Layer or ViewportLayer, depending on the circumstances.

Specified by:

activeSoundLayerChanged in interface NodeUpdateHandler

Parameters:

intL - Internal listener for making callbacks at a later time to propogate when the target is no longer the active listener.

Throws:

InvalidListenerSetTimingException

shaderRequiresInit

public void shaderRequiresInit(ShaderSourceRenderable shader,
                               boolean updateResponse)

The shader object passed requires an initialisation be performed. Queue the shader up for processing now.

Specified by:

shaderRequiresInit in interface NodeUpdateHandler

Parameters:

shader - The shader instance to queue

updateResponse - true if this is being made as a response to a node's setUpdateHandler() method

shaderRequiresLogInfo

public void shaderRequiresLogInfo(ShaderSourceRenderable shader,
                                  boolean updateResponse)

The shader object passed requires updating the log info. Queue the shader up for processing now so that at the next oppourtunity it can call glGetLogInfoARB.

Specified by:

shaderRequiresLogInfo in interface NodeUpdateHandler

Parameters:

shader - The shader instance to queue

updateResponse - true if this is being made as a response to a node's setUpdateHandler() method

requestDeletion

public void requestDeletion(DeletableRenderable deletable)

Notification that the passed in renderable is wishing to mark itself ready for deletion processing. For example, this could be because a texture has had its contents replaced and needs to free up the old texture object ID. The reasons why this object is now marked for deletion are not defined - that is the sole discretion of the calling code.

This renderable instance will begin the deletion processing as soon as the start of the next culling pass begins. Once it hits the output device, deletion requests are guaranteed to be the first item that is processed, before all other requests.

If the object is already in the queue, the request will be silently ignored.

Specified by:

requestDeletion in interface NodeUpdateHandler

Parameters:

deletable - The renderable that will handle the cleanup at the appropriate time

rescindDeletionRequest

public void rescindDeletionRequest(DeletableRenderable deletable)

Woops, we were in error, so please rescind that deletion request. For example, during the data update change processing a texture was reparented, first by deletion, then by addition to a new parent, this would ensure that we don't continuing attempting to delete the texture when we should not.

You can only rescind request that has happened in this frame as the delete requests are packaged up and sent off down the pipeline each frame, then forgotten about during the rendering process.

Rescinding a request for an object no-longer in the queue (eg multiple request, or just was never added in the first place), will be silently ignored.

Specified by:

rescindDeletionRequest in interface NodeUpdateHandler

Parameters:

deletable - The renderable that should be removed from the queue.

getPickingManager

public PickingManager getPickingManager()

Get the picking handler so that we can do some picking operations.

Specified by:

getPickingManager in interface RenderManager

Specified by:

getPickingManager in interface NodeUpdateHandler

Returns:

the current instance of the picking system