org.j3d.aviatrix3d.management
Interface RenderManager

All Known Implementing Classes:

MultiThreadRenderManager, SingleThreadRenderManager

public interface RenderManager

A marker interface that represents a class capable of managing the complete management pipeline.

A manager is used to handle a system-specific management technique. The goal is to manage the contained pipeline(s) in a way that is most efficient to the hardware provided. Thus, it is expected there will be many different types of managers to suit the many hardware configurations available.

Example implementations of the pipeline manager would be one that handles all the pipelines with simultaneous threads, each pinned to a particular CPU/Graphics pipe that the machine has. Another implementation may hold all the pipelines for sequential evaluation piping the output from one into the input for another (eg for handling dynamic cubic environment maps).

Basic common methods are provided for all implementations to use. It is expected that implementations will add additional technique-specific extension methods to the basic features.

Controlling Rendering Updates

Almost all applications will wish to control the rate at which management occurs. Typically this is just so that the rest of the application and user's system remains interactive (the default setup is to use 100% CPU to run as fast as possible). Alternatively the application may have a very small rate of change, or wish to run in an offscreen-management mode (eg server-based for web-delivery to an end user).

The basic frame rate is controlled by the setMinimumFrameInterval(int) method. This provides the minimum time, in milliseconds, between sequential frame managements. If the management of a single frame takes longer than this time, then the next frame will begin as soon as possible. (Note, we do not currently provide any mechanism for guaranteeing a specific frame rate, only a maximum framerate). For example, setting a value of 20 will result in a maximum of 50 frames per second.

To return the system to an unregulated frame rate, after having set the value previously, call setMinimumFrameInterval() method with a value of 0.

If you wish to render on demand, then set the render manager to disabled it is disabled by default on construction). Then, whenever you need to repaint the surface, call the renderOnce() method.

Version:

$Revision: 1.4 $

Author:

Justin Couch

Method Summary

void	addDisplay(DisplayCollection collection) Add a dislay collection to be managed.
void	disableInternalShutdown() Disable the internal shutdown hook system.
int	getMinimumFrameInterval() Fetch the currently set duty cycle value.
PickingManager	getPickingManager() Get the picking handler instance that is registered with the system.
boolean	isEnabled() Get the current render state of the manager.
boolean	isHaltingOnError() Check to see the current halt on error state.
void	removeDisplay(DisplayCollection collection) Remove an already registered display collection from the manager.
void	renderOnce() Force a single render of all pipelines now.
void	requestFullSceneRender() Request that the manager perform a full scene render pass and update, ignoring any usual optimisations that it may take.
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	shutdown() Notification to shutdown the internals of the renderer because the application is about to exit.

Method Detail

setErrorReporter

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.

Parameters:

reporter - The instance to use or null

setHaltOnError

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.

Parameters:

state - true to enable halting, false to disable

isHaltingOnError

boolean isHaltingOnError()

Check to see the current halt on error state.

Returns:

true if the system halts on an error condition

See Also:

setHaltOnError(boolean)

setEnabled

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.

Parameters:

state - True if to enable management

isEnabled

boolean isEnabled()

Get the current render state of the manager.

Returns:

true if the manager is currently running

renderOnce

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. If this method is called, the application observer is not called beforehand. It assumes that you'll be making the scene graph updates yourself before calling this method.

Throws:

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

requestFullSceneRender

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.

setMinimumFrameInterval

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. This can be changed at any time.

Setting a value of zero will return the render to an un-regulated state where the code will attempt to render as fast as possible (ie guaranteed 100% CPU usage).

Parameters:

cycleTime - The minimum time in milliseconds between frames or zero

getMinimumFrameInterval

int getMinimumFrameInterval()

Fetch the currently set duty cycle value.

Returns:

The duty cycle time, in milliseconds

addDisplay

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

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

Parameters:

collection - The new collection instance to be added

Throws:

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

removeDisplay

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.

Parameters:

collection - The collection instance to be removed

Throws:

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

getPickingManager

PickingManager getPickingManager()

Get the picking handler instance that is registered with the system.

Returns:

the current instance of the picking system

setPickingManager

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

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

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.

Parameters:

obs - The observer instance to use

disableInternalShutdown

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.

shutdown

void shutdown()

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