org.j3d.aviatrix3d
Interface NodeUpdateHandler

All Known Implementing Classes:

MultiThreadRenderManager, SingleThreadRenderManager

public interface NodeUpdateHandler

Abstract representation of a piece of code that wants to manage the node update process internally to the scene graph.

This interface is never directly called by user-land code. It's used to abstract the process of maintaining a node as part of the scene graph, and the implementation of the management system behind it. The management system is responsible for coordinating and marshalling the user code into correct timing for feeding directly to the rendering pipeline and beyond. As such, it is responsible for preventing user updates at inappropriate times, and also keeping track of what has been requested to update.

Methods here provide both timing information, and ways of registering objects for further processing. When a node implementation needs to know if it is acceptable to make or allow certain changes, then these methods can be queried to provide the appropriate guidance.

Version:

$Revision: 1.19 $

Author:

Justin Couch

Method Summary

void	activeSoundLayerChanged(InternalLayerUpdateListener intL) Notify the handler that you are now going to be the active layer for sound rendering.
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.
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 bounding information of the node is permitted currently.
boolean	isDataWritePermitted(java.lang.Object src) Check to see if writing to the data information of the node is permitted currently.
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-rendering.
void	requestDeletion(DeletableRenderable deletable) Notification that the passed in renderable is wishing to mark itself ready for deletion processing.
void	rescindDeletionRequest(DeletableRenderable deletable) Woops, we were in error, so please rescind that deletion request.
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.

Method Detail

isBoundsWritePermitted

boolean isBoundsWritePermitted(java.lang.Object src)

Check to see if writing to the bounding information of the node is permitted currently.

Parameters:

src - The object that is requesting the check

Returns:

true if the end user can write, false if not

isDataWritePermitted

boolean isDataWritePermitted(java.lang.Object src)

Check to see if writing to the data information of the node is permitted currently.

Parameters:

src - The object that is requesting the check

Returns:

true if the end user can write, false if not

isPickingPermitted

boolean isPickingPermitted()

Check to see if picking is permitted currently.

Returns:

true if the end user can pick, false if not

notifyUpdateRequired

void notifyUpdateRequired()

Feedback to the internals that a data object has changed and it requires re-rendering. This should only be called by classes that can effect the rendering 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.

boundsChanged

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.

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

activeSoundLayerChanged

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.

Parameters:

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

Throws:

InvalidListenerSetTimingException

dataChanged

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.

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

getPickingManager

PickingManager getPickingManager()

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

Returns:

the current instance of the picking system

shaderRequiresInit

void shaderRequiresInit(ShaderSourceRenderable shader,
                        boolean updateResponse)

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

Parameters:

shader - The shader instance to queue

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

shaderRequiresLogInfo

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.

Parameters:

shader - The shader instance to queue

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

requestDeletion

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.

Parameters:

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

rescindDeletionRequest

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.

Parameters:

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