edu.umd.cs.jazz
Class ZSceneGraphObject

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

All Implemented Interfaces:

java.lang.Cloneable, java.io.Serializable, ZSerializable

Direct Known Subclasses:

ZNode, ZVisualComponent

public abstract class ZSceneGraphObject

extends java.lang.Object

implements ZSerializable, java.io.Serializable, java.lang.Cloneable

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 of rectangles are specified in local coordinates. In addition, objects maintain a bounding box which is stored in local coordinates.

See the Jazz Tutorial for a more complete description of the scene graph.

Warning: Serialized and ZSerialized objects of this class will not be compatible with future Jazz releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Jazz. A future release of Jazz will provide support for long term persistence.

See Also:

ZNode, ZVisualComponent, Serialized Form

Field Summary

protected ZBounds	bounds The bounding rectangle occupied by this object in its own local coordinate system.
protected boolean	volatileBounds True if this node is specifically set to have volatile bounds
static boolean	volatileBounds_DEFAULT

Constructor Summary

protected

ZSceneGraphObject() Constructs an empty scenegraph object.

Method Summary

java.lang.Object	clone() Clones this scene graph object and all its children and returns the newly cloned sub-tree.
protected void	computeBounds() Recomputes and caches the bounds for this node.
java.lang.String	dump() Generate a string that represents this object for debugging.
protected java.lang.Object	duplicateObject() Creates a copy of this scene graph object and all its children.
ZBounds	getBounds() Return a copy of the bounds of the subtree rooted at this node in local coordinates.
protected ZBounds	getBoundsReference() Internal method to return the original 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.
protected void	setBounds(ZBounds newBounds) Internal method to specify the bounds of this object.
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.
protected void	updateObjectReferences(ZObjectReferenceTable objRefTable) Updates references to scene graph nodes after a clone operation.
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

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

Field Detail

volatileBounds_DEFAULT

public static final boolean volatileBounds_DEFAULT

bounds

protected ZBounds bounds

The bounding rectangle occupied by this object in its own local coordinate system. Conceptually, the bounding rectangle is defined as the minimum rectangle that would surround all of the geometry drawn by the node and its children. The bounding rectangle's coordinates are in the node's local coordinates. That is, they are independant of any viewing transforms, or of transforms performed by parents of the node.

volatileBounds

protected boolean volatileBounds

True if this node is specifically set to have volatile bounds

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

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.

If the object is a context-sensitive object, then it may compute the bounds based on the current render context.

Returns:

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

See Also:

ZRoot.getCurrentRenderContext()

getBoundsReference

protected ZBounds getBoundsReference()

Internal method to return the original 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.

setBounds

protected void setBounds(ZBounds newBounds)

Internal method to specify the bounds of this object.

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 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.

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

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()

duplicateObject

protected java.lang.Object duplicateObject()

Creates a copy of this scene graph object and all its children.

ZSceneGraphObject.duplicateObject() calls Object.clone() on this object, and returns the newly cloned object. This results in a shallow copy of the object.

Subclasses override this method to modify the cloning behavior for nodes in the scene graph. Typically, subclasses first invoke super.duplicateObject() to get the default cloning behavior, and then take additional actions after this. In particular, ZGroup.duplicateObject() first invokes super.duplicateObject(), and then calls duplicateObject() on all of the children in the group, so that the whole tree beneath the group is cloned. Applications do not call duplicateObject directly. Instead, ZSceneGraphObject.clone() is used clone a scene graph object.

updateObjectReferences

protected void updateObjectReferences(ZObjectReferenceTable objRefTable)

Updates references to scene graph nodes after a clone operation.

This method is invoked on cloned objects after the clone operation has been completed. The objRefTable parameter is a table mapping from the original uncloned objects to their newly cloned versions. Subclasses override this method to update any internal references they have to scene graph nodes. For example, ZNode's updateObjectReferences does:

	    super.updateObjectReferences(objRefTable);

	    // Set parent to point to the newly cloned parent, or to 
	    // null if the parent object was not cloned.
      parent = (ZNode)objRefTable.getNewObjectReference(parent);
 

Parameters:

objRefTable - Table mapping from uncloned objects to their cloned versions.

clone

public java.lang.Object clone()

Clones this scene graph object and all its children and returns the newly cloned sub-tree. Applications must then add the sub-tree to the scene graph for it to become visible.

Overrides:

clone in class java.lang.Object

Returns:

A cloned copy of this object.

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