org.j3d.aviatrix3d.management
Class DisplayCollection

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

Direct Known Subclasses:

SingleDisplayCollection

public abstract class DisplayCollection
extends java.lang.Object

A marker interface that represents a class capable of managing a single set of layers and the pipeline(s) needed to render them.

The collection groups together a set of layers that are to appear on a surface and the pipelines needed to render them. The idea is to allow a single rendering manager manage one or more scenegraphs and all of the rendering infrastructure needed, yet keep all the updates synchronised. A typical example of this would a MDI application that has multiple windows each with their own set of layers and viewpoints onto a single shared scene graph. This differs from the single window with layers creating separate viewports that are constrained to that window.

Implementation Notes

This class contains a number of protected methods. These are called by the RenderManager implementation at different times in the rendering cycle with appropriate information. These are methods that should not be called by the normal user, so they have been made protected to allow package-only access to them, yet remain seeable by implementors of this class outside of this package.

Changing the layers and pipelines are subject to the same timing restrictions as the rest of the scene graph. Layers may only be changed during the dataChanged() callbacks.

Version:

$Revision: 1.3 $

Author:

Justin Couch

Field Summary

protected static java.lang.String	ACTIVE_RENDERING_MSG Message when trying to call any of the set or render methods while the class is currently processing the pipeline.
protected DeletableRenderable[]	deletionList Queue for holding deleted textures
protected boolean	enabled Current enabled state
protected org.j3d.util.ErrorReporter	errorReporter Error reporter used to send out messages
protected static java.lang.String	LAYER_SET_SIZE_ERR Message when the setLayers() call doesn't have an array big enough
protected static java.lang.String	LAYER_TIMING_MSG Message when attempting to set layers at the wrong time
protected int	numDeletables The number of items to delete this frame
protected int	numShaderInit The number of shader init requestors
protected int	numShaderLog The number of shader log requestors
protected ShaderSourceRenderable[]	shaderInitList The shader renderables that need to be initialised
protected ShaderSourceRenderable[]	shaderLogList The shader renderables that want log information
protected boolean	terminate Flag that the runtime thread should be terminated at next chance
protected boolean	writeEnabled Flag controlling layer change timing

Constructor Summary

protected

DisplayCollection() Initialise the basic structures of this collection.

Method Summary

abstract void	addPipeline(RenderPipeline pipe) Add a pipeline to be rendered to the manager.
abstract boolean	displayOnly() Cause the surface to redraw the next frame only, with no processing of the pipeline.
protected void	enableLayerChange(boolean state) Notification that the timing model permits changing the layers now.
abstract void	getLayers(Layer[] layers) Fetch the current layers that are set.
abstract void	halt() Force a halt of the current processing.
boolean	isDisposed() Check to see if this pipeline is now inoperable.
boolean	isEnabled() Get the current render state of the manager.
abstract int	numLayers() Get the number of layers that are currently set.
abstract boolean	process() Force a single render of all pipelines now contained in this collection now.
protected void	queueDeletedObjects(DeletableRenderable[] deleted, int num) Queue up a objects for deletion with the next rendering pass.
protected void	queueShaderObjects(ShaderSourceRenderable[] initList, int numInit, ShaderSourceRenderable[] logList, int numLog) Queue up shader objects that need some pre-processing done.
abstract void	removePipeline(RenderPipeline pipe) Remove an already registered pipeline from the manager.
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.
abstract void	setLayers(Layer[] layers, int numLayers) Set the set of layers for this manager.
protected abstract void	setUpdateHandler(NodeUpdateHandler handler) Set the update handler that controls synchronisations of write/read process to the scene graph.
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

Field Detail

LAYER_SET_SIZE_ERR

protected static final java.lang.String LAYER_SET_SIZE_ERR

Message when the setLayers() call doesn't have an array big enough

See Also:

Constant Field Values

LAYER_TIMING_MSG

protected static final java.lang.String LAYER_TIMING_MSG

Message when attempting to set layers at the wrong time

See Also:

Constant Field Values

ACTIVE_RENDERING_MSG

protected static final java.lang.String ACTIVE_RENDERING_MSG

Message when trying to call any of the set or render methods while the class is currently processing the pipeline.

See Also:

Constant Field Values

shaderInitList

protected ShaderSourceRenderable[] shaderInitList

The shader renderables that need to be initialised

shaderLogList

protected ShaderSourceRenderable[] shaderLogList

The shader renderables that want log information

deletionList

protected DeletableRenderable[] deletionList

Queue for holding deleted textures

numShaderInit

protected int numShaderInit

The number of shader init requestors

numShaderLog

protected int numShaderLog

The number of shader log requestors

numDeletables

protected int numDeletables

The number of items to delete this frame

enabled

protected boolean enabled

Current enabled state

terminate

protected boolean terminate

Flag that the runtime thread should be terminated at next chance

errorReporter

protected org.j3d.util.ErrorReporter errorReporter

Error reporter used to send out messages

writeEnabled

protected boolean writeEnabled

Flag controlling layer change timing

Constructor Detail

DisplayCollection

protected DisplayCollection()

Initialise the basic structures of this collection.

Method Detail

process

public abstract boolean process()

Force a single render of all pipelines now contained in this collection now. Blocks until all rendering is complete (based on the definition of the implementing class).

In general, it is inadvisable that method be called by end users as it is normally managed by the RenderManager.

The return value indicates success or failure in the ability to render this frame. Typically it will indicate failure if the underlying surface has been disposed of, either directly through the calling of the method on this interface, or through an internal check mechanism. If failure is indicated, then check to see if the surface has been disposed of and discontinue rendering if it has.

Returns:

true if the drawing succeeded, or false if not

displayOnly

public abstract boolean displayOnly()

Cause the surface to redraw the next frame only, with no processing of the pipeline. This is typically an optimisation step when nothing has changed in user land, so there's no processing that needs to be done. Skip the processing and tell the drawable surface to render again what it already has set from the previous frame.

The return value indicates success or failure in the ability to render this frame. Typically it will indicate failure if the underlying surface has been disposed of, either directly through the calling of the method on this interface, or through an internal check mechanism. If failure is indicated, then check to see if the surface has been disposed of and discontinue rendering if it has.

Returns:

true if the drawing succeeded, or false if not

halt

public abstract void halt()

Force a halt of the current processing. Any processing in progress should exit immediately. Used to abort the current scene processing due to application shutdown or complete scene replacement.

setLayers

public abstract void setLayers(Layer[] layers,
                               int numLayers)
                        throws java.lang.IllegalArgumentException,
                               InvalidWriteTimingException

Set the set of layers for this manager. Setting a value of null will remove the currently set of layers. If this is set while a current scene is set, then the scene will be cleared. Layers are presented in depth order - layers[0] is rendered before layers[1] etc.

If this render manager is currently running, this method can only be called during the main update

Parameters:

layers - The collection of layers, in order, to render

numLayers - The number of valid layers to use

Throws:

java.lang.IllegalArgumentException - The length of the layers array is less than numLayers

InvalidWriteTimingException - The method was called with the system enabled and not during the app observer callback

numLayers

public abstract int numLayers()

Get the number of layers that are currently set. If no layers are set, or a scene is set, this will return zero.

Returns:

a value greater than or equal to zero

getLayers

public abstract void getLayers(Layer[] layers)

Fetch the current layers that are set. The values will be copied into the user-provided array. That array must be at least numLayers() in length. If not, this method does nothing (the provided array will be unchanged).

Parameters:

layers - An array to copy the values into

addPipeline

public abstract void addPipeline(RenderPipeline pipe)
                          throws java.lang.IllegalStateException

Add a pipeline to be rendered to the manager. A duplicate registration or null value is ignored.

Parameters:

pipe - The new pipe instance to be added

Throws:

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

removePipeline

public abstract void removePipeline(RenderPipeline pipe)
                             throws java.lang.IllegalStateException

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

Parameters:

pipe - The pipe instance to be removed

Throws:

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

setUpdateHandler

protected abstract void setUpdateHandler(NodeUpdateHandler handler)

Set the update handler that controls synchronisations of write/read process to the scene graph.

Parameters:

handler - The new handler instance to use

enableLayerChange

protected void enableLayerChange(boolean state)

Notification that the timing model permits changing the layers now.

Parameters:

state - true to enable layers to be changed, false to disable

queueDeletedObjects

protected void queueDeletedObjects(DeletableRenderable[] deleted,
                                   int num)

Queue up a objects for deletion with the next rendering pass. This is called once per rendering cycle with the values to be processed in the next pass. It will contain the complete list, so you can assume that the list size only needs to be set once. Local copies should be made of the array as it may be overwritten by the caller during the next cycle.

Parameters:

deleted - The items to be processed for deletion

num - The number of valid items in this array

queueShaderObjects

protected void queueShaderObjects(ShaderSourceRenderable[] initList,
                                  int numInit,
                                  ShaderSourceRenderable[] logList,
                                  int numLog)

Queue up shader objects that need some pre-processing done. This is called once per rendering cycle with the values to be processed in the next pass. It will contain the complete list, so you can assume that the list size only needs to be set once. Local copies should be made of the array as it may be overwritten by the caller during the next cycle.

Parameters:

initList - The items to be processed GLSL compilation

numInit - The number of valid items in the init array

logList - The items requesting shader log info

numLog - The number of valid items in the log array

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.

Parameters:

reporter - The instance to use or null

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.

Parameters:

state - True if to enable management

isEnabled

public boolean isEnabled()

Get the current render state of the manager.

Returns:

true if the manager is currently running

shutdown

public void shutdown()

Notification to shutdown the internals of the renderer because the application is about to exit. Normally this will be called by the containing RenderManager and should not need to be called by end users.

isDisposed

public boolean isDisposed()

Check to see if this pipeline is now inoperable. It may be inoperable for one of many reasons, such as the output device is terminated, user terminated or some abnormal internal condition.

Returns:

true if the collection is no longer operable