edu.umd.cs.jazz
Class ZSceneGraphObject

java.lang.Object
  |
  +--edu.umd.cs.jazz.ZSceneGraphObject

All Implemented Interfaces:

java.io.Serializable, ZSerializable

Direct Known Subclasses:

ZNode, ZVisualComponent

public abstract class ZSceneGraphObject

extends java.lang.Object

implements ZSerializable, java.io.Serializable

ZSceneGraphObject is the base class for all objects in the Jazz scenegraph. It provides support for the basic shared methods between all nodes and visual components.

Coordinate Systems
Application developers must understand the basic coordinate systems used in Jazz. The basic coordinate system has its origin at the upper-left. The X-axis increases positively to the right, and the Y-axis increase positively down.

Because certain node types define transforms which define a new relative coordinate system, it is important to realize that typically, objects are not placed in "global" coordinates. Rather, every object is defined in their own "local" coordinate system. The relationship of the local coordinate system to the global coordinate system is determined by the series of transforms between that object, and the root of the scenegraph.

All Jazz operations occur in local coordinates. For instance, coordinates and rectangles object receiving those parameters. In addition, objects cache their bounds within in their local coordinates. This is efficient because it means that if an object changes itself, none of its ancestors need to be notified in any way.

See Also:

ZNode, ZVisualComponent, Serialized Form

Field Summary

protected ZBounds	bounds The bounds occupied by this object in its own local coordinate system.
protected static ZObjectReferenceTable	objRefTable The single instance of the object reference table used for cloning scenegraph trees.
static boolean	volatileBounds_DEFAULT

Constructor Summary

protected

ZSceneGraphObject() Constructs an empty scenegraph object.

Method Summary

protected void	computeBounds() Recomputes and caches the bounds for this node.
java.lang.String	dump() Generate a string that represents this object for debugging.
void	duplicateObject(ZSceneGraphObject refObj) Copies all object information from the reference object into the current object.
ZBounds	getBounds() Return a copy of the bounds of the subtree rooted at this node in local coordinates.
boolean	getVolatileBounds() Determines if this node is volatile.
void	repaint() Repaint causes the portions of the surfaces that this object appears in to be marked as needing painting, and queues events to cause those areas to be painted.
void	reshape() Reshape causes the portion of the surface that this object appears in before the bounds are changed to be marked as needing painting, and queues events to cause those areas to be painted.
void	setState(java.lang.String fieldType, java.lang.String fieldName, java.lang.Object fieldValue) Set some state of this object as it gets read back in.
void	setVolatileBounds(boolean v) Specifies whether or not this node is volatile.
protected void	updateBounds() Internal method that causes this node and all of its ancestors to recompute their bounds.
void	updateObjectReferences(ZObjectReferenceTable objRefTable) Manage dangling references when scenegraph objects are cloned.
protected void	updateVolatility() Internal method to compute and cache the volatility of a node, to recursively call the parents to compute volatility.
void	writeObject(ZObjectOutputStream out) Write out all of this object's state.
void	writeObjectRecurse(ZObjectOutputStream out) Specify which objects this object references in order to write out the scenegraph properly

Methods inherited from class java.lang.Object

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

Field Detail

volatileBounds_DEFAULT

public static final boolean volatileBounds_DEFAULT

objRefTable

protected static ZObjectReferenceTable objRefTable

The single instance of the object reference table used for cloning scenegraph trees.

bounds

protected ZBounds bounds

The bounds occupied by this object in its own local coordinate system. These bounds are not affected by this node's parents. These bounds represent any content that this node contains (including any elements stored by subtypes).

Constructor Detail

ZSceneGraphObject

protected ZSceneGraphObject()

Constructs an empty scenegraph object.

Most objects will want to store their bounds, and so we allocate bounds here. However, if a particular object is implemented by computing its bounds every time it is asked instead of allocating it, then it can free up the bounds allocated here.

Method Detail

duplicateObject

public void duplicateObject(ZSceneGraphObject refObj)

Copies all object information from the reference object into the current object. This method is called from the clone method. All ZSceneGraphObjects objects contained by the object being duplicated are duplicated, except parents which are set to null. This results in the sub-tree rooted at this object being duplicated.

Parameters:

refObj - The reference object to copy

getBounds

public ZBounds getBounds()

Return a copy of the bounds of the subtree rooted at this node in local coordinates. If a valid cached value is available, this method returns it. If a valid cache is not available (i.e. the object is volatile) then the bounds are recomputed, cached and then returned to the caller.

Returns:

The bounds of the subtree rooted at this in local coordinates.

computeBounds

protected void computeBounds()

Recomputes and caches the bounds for this node. Generally this method is called by reshape when the bounds have changed, and it should rarely directly elsewhere.

repaint

public void repaint()

Repaint causes the portions of the surfaces that this object appears in to be marked as needing painting, and queues events to cause those areas to be painted. The painting does not actually occur until those events are handled. If this object is visible in multiple places because more than one camera can see this object, then all of those places are marked as needing painting.

Scenegraph objects should call repaint when their internal state has changed and they need to be redrawn on the screen.

Important note : Scenegraph objects should call reshape() instead of repaint() if the internal state change effects the bounds of the shape in any way (e.g. changing penwidth, selection, transform, adding points to a line, etc.)

See Also:

reshape()

reshape

public void reshape()

Reshape causes the portion of the surface that this object appears in before the bounds are changed to be marked as needing painting, and queues events to cause those areas to be painted. Then, the bounds are updated, and finally, the portion of the screen corresponding to the newly computed bounds are marked for repainting. If this object is visible in multiple places because more than one camera can see this object, then all of those places are marked as needing painting.

Scenegraph objects should call reshape when their internal state has changed in such a way that their bounds have changed.

Important note : Scenegraph objects should call repaint() instead of reshape() if the bounds of the shape have not changed.

See Also:

repaint()

updateBounds

protected void updateBounds()

Internal method that causes this node and all of its ancestors to recompute their bounds.

getVolatileBounds

public final boolean getVolatileBounds()

Determines if this node is volatile. A node is considered to be volatile if it is specifically set to be volatile with setVolatileBounds(boolean). All parents of this node are also volatile when this is volatile.

Volatile objects are those objects that change regularly, such as an object that is animated, or one whose rendering depends on its context.

Returns:

true if this node is volatile

See Also:

setVolatileBounds(boolean)

setVolatileBounds

public void setVolatileBounds(boolean v)

Specifies whether or not this node is volatile. All parents of this node are also volatile when this is volatile.

Parameters:

v - the new specification of whether this node is volatile.

See Also:

getVolatileBounds()

updateVolatility

protected void updateVolatility()

Internal method to compute and cache the volatility of a node, to recursively call the parents to compute volatility. All parents of this node are also volatile when this is volatile.

See Also:

setVolatileBounds(boolean), getVolatileBounds()

updateObjectReferences

public void updateObjectReferences(ZObjectReferenceTable objRefTable)

Manage dangling references when scenegraph objects are cloned. This gets called after a sub-graph of the scenegraph has been cloned, and it is this method's responsibility to update any internal references to the original portions of the scenegraph. Subtypes that define new references should override this method to manage their references.

Parameters:

objRefTable - The table that maintains the relationships between cloned objects.

dump

public java.lang.String dump()

Generate a string that represents this object for debugging.

Returns:

the string that represents this object for debugging

See Also:

ZDebug.dump(edu.umd.cs.jazz.ZNode)

writeObject

public void writeObject(ZObjectOutputStream out)
                 throws java.io.IOException

Write out all of this object's state.

Specified by:

writeObject in interface ZSerializable

Parameters:

out - The stream that this object writes into

writeObjectRecurse

public void writeObjectRecurse(ZObjectOutputStream out)
                        throws java.io.IOException

Specify which objects this object references in order to write out the scenegraph properly

Specified by:

writeObjectRecurse in interface ZSerializable

Parameters:

out - The stream that this object writes into

setState

public void setState(java.lang.String fieldType,
                     java.lang.String fieldName,
                     java.lang.Object fieldValue)

Set some state of this object as it gets read back in. After the object is created with its default no-arg constructor, this method will be called on the object once for each bit of state that was written out through calls to ZObjectOutputStream.writeState() within the writeObject method.

Specified by:

setState in interface ZSerializable

Parameters:

fieldType - The fully qualified type of the field

fieldName - The name of the field

fieldValue - The value of the field