node.java

JAVA3D矩陈的相关类

     *  this parameter is <code>false</code> a
     *  <code>DanglingReferenceException</code> is generated as
     *  soon as cloneTree detects this situation.
     *
     * @return a reference to the cloned scene graph.
     * @exception DanglingReferenceException When a dangling reference is
     *  discovered during the cloneTree operation.
     * @exception RestrictedAccessException if this object is part of live
     * or compiled scene graph
     * @exception SceneGraphCycleException if there is a cycle in the
     * scene graph
     * @see NodeComponent#setDuplicateOnCloneTree
     * @since Java 3D 1.2
     */
    public Node cloneTree(NodeReferenceTable referenceTable,
			  boolean forceDuplicate,
			  boolean allowDanglingReferences) {

	if (!isLiveOrCompiled()) {
	    // this will throw a SceneGraphCycleException if there is
	    // a cycle
	    checkForCycle();
	}
	
        referenceTable.set(allowDanglingReferences, new Hashtable());
        Node n = cloneTree(forceDuplicate, referenceTable.objectHashtable);

        // go through hash table looking for Leaf nodes.
        // call updateNodeReferences for each.
        Enumeration e = referenceTable.objectHashtable.elements();

        while (e.hasMoreElements()) {
            SceneGraphObject o =  (SceneGraphObject) e.nextElement();
	    o.updateNodeReferences(referenceTable);
        }
        return n;
    }

   /**
     * Duplicates all the nodes of the specified sub-graph.  For Group Nodes
     * the group node is duplicated via a call to <code>cloneNode</code> and
     * then <code>cloneTree</code> is called for each child node.  For
     * Leaf Nodes, component
     * data can either be duplicated or be made a reference to the original
     * data.  Leaf Node cloneTree behavior is determined by the
     * <code>duplicateOnCloneTree</code> flag found in every Leaf Node's
     * component data class and by the <code>forceDuplicate</code> paramter.
     *
     * @param forceDuplicate when set to <code>true</code>, causes the
     *  <code>duplicateOnCloneTree</code>
     *  flag to be ignored.  When <code>false</code>, the value of each node's
     *  <code>duplicateOnCloneTree</code> determines whether data is
     *  duplicated or copied.
     *
     * @param nodeHashtable a hashtable used to map orignal node references to
     *  their cloned counterpart.
     *
     * @return a reference to the cloned scene graph.
     *
     * @see NodeComponent#setDuplicateOnCloneTree
     */
    Node cloneTree(boolean forceDuplicate, Hashtable nodeHashtable) {
        Node l;
	this.nodeHashtable = nodeHashtable;
	try {
	    l = cloneNode(forceDuplicate);
	} catch (RuntimeException e) {
	    this.nodeHashtable = null;
	    throw e;
	}
	// must reset to null so that we can tell whether the call is from user 
	// or cloneTree
        this.nodeHashtable = null;  
	nodeHashtable.put(this, l);
	return l;
    }


    /**
     * Used to create a new instance of the node.  This routine is called
     * by <code>cloneTree</code> to duplicate the current node. 
     * <code>cloneNode</code> should be overridden by any user subclassed
     * objects.  All subclasses must have their <code>cloneNode</code>
     * method consist of the following lines:
     * <P><blockquote><pre>
     *     public Node cloneNode(boolean forceDuplicate) {
     *         UserSubClass usc = new UserSubClass();
     *         usc.duplicateNode(this, forceDuplicate);
     *         return usc;
     *     }
     * </pre></blockquote>
     * NOTE: Applications should <i>not</i> call this method directly.
     * It should only be called by the cloneTree method.
     *
     * @param forceDuplicate when set to <code>true</code>, causes the
     *  <code>duplicateOnCloneTree</code> flag to be ignored.  When
     *  <code>false</code>, the value of each node's
     *  <code>duplicateOnCloneTree</code> variable determines whether
     *  NodeComponent data is duplicated or copied.
     *
     * @exception RestrictedAccessException if this object is part of live
     * or compiled scene graph
     *
     * @see Node#cloneTree
     * @see Node#duplicateNode
     * @see NodeComponent#setDuplicateOnCloneTree
     */
    public Node cloneNode(boolean forceDuplicate) {
        throw new RuntimeException(J3dI18N.getString("Node12"));
    }


    /**
     * Copies all node information from <code>originalNode</code> into
     * the current node.  This method is called from the
     * <code>cloneNode</code> method which is, in turn, called by the
     * <code>cloneTree</code> method.
     * <P>
     * For any <code>NodeComponent</code> objects
     * contained by the object being duplicated, each <code>NodeComponent</code>
     * object's <code>duplicateOnCloneTree</code> value is used to determine
     * whether the <code>NodeComponent</code> should be duplicated in the new node
     * or if just a reference to the current node should be placed in the
     * new node.  This flag can be overridden by setting the
     * <code>forceDuplicate</code> parameter in the <code>cloneTree</code>
     * method to <code>true</code>.
     *
     * <br>
     * NOTE: Applications should <i>not</i> call this method directly.
     * It should only be called by the cloneNode method.
     *
     * @param originalNode the original node to duplicate.
     * @param forceDuplicate when set to <code>true</code>, causes the
     *  <code>duplicateOnCloneTree</code> flag to be ignored.  When
     *  <code>false</code>, the value of each node's
     *  <code>duplicateOnCloneTree</code> variable determines whether
     *  NodeComponent data is duplicated or copied.
     *
     * @see Group#cloneNode
     * @see Node#duplicateNode
     * @see Node#cloneTree
     * @see NodeComponent#setDuplicateOnCloneTree
     */
    public void duplicateNode(Node originalNode,
			      boolean forceDuplicate) {
        duplicateAttributes(originalNode, forceDuplicate);
    }

   /**
     * Copies all node information from <code>originalNode</code> into
     * the current node.  This method is called from subclass of
     * <code>duplicateNode</code> method which is, in turn, called by the
     * <code>cloneNode</code> method.
     * <P>
     * For any <i>NodeComponent</i> objects
     * contained by the object being duplicated, each <i>NodeComponent</i>
     * object's <code>duplicateOnCloneTree</code> value is used to determine
     * whether the <i>NodeComponent<i> should be duplicated in the new node
     * or if just a reference to the current node should be placed in the
     * new node.  This flag can be overridden by setting the
     * <code>forceDuplicate</code> parameter in the <code>cloneTree</code>
     * method to <code>true</code>.
     *
     *
     * @param originalNode the original node to duplicate.
     * @param forceDuplicate when set to <code>true</code>, causes the
     *  <code>duplicateOnCloneTree</code> flag to be ignored.  When
     *  <code>false</code>, the value of each node's
     *  <code>duplicateOnCloneTree</code> variable determines whether
     *  NodeComponent data is duplicated or copied.
     *
     * @see Group#cloneNode
     * @see Node#duplicateNode
     * @see Node#cloneTree
     * @see NodeComponent#setDuplicateOnCloneTree
     */
    final void checkDuplicateNode(Node originalNode,
				  boolean forceDuplicate) {
        if (originalNode.nodeHashtable != null) {
	    duplicateAttributes(originalNode, forceDuplicate);
	} else {
	    //  user call cloneNode() or duplicateNode() directly 
	    // instead of via cloneTree() 
	    originalNode.nodeHashtable = new Hashtable();
	    duplicateAttributes(originalNode, forceDuplicate);
	    originalNode.nodeHashtable = null;
	}
    }


    /**
     * Copies all Node information from
     * <code>originalNode</code> into
     * the current node.  This method is called from the
     * <code>cloneNode</code> method which is, in turn, called by the
     * <code>cloneTree</code> method.<P> 
     *
     * @param originalNode the original node to duplicate.
     * @param forceDuplicate when set to <code>true</code>, causes the
     *  <code>duplicateOnCloneTree</code> flag to be ignored.  When
     *  <code>false</code>, the value of each node's
     *  <code>duplicateOnCloneTree</code> variable determines whether
     *  NodeComponent data is duplicated or copied.
     *
     * @exception RestrictedAccessException if originalNode object is part of a live
     *  or compiled scenegraph.
     *
     * @see Node#duplicateNode
     * @see Node#cloneTree
     * @see NodeComponent#setDuplicateOnCloneTree
     */
    void duplicateAttributes(Node originalNode, boolean forceDuplicate) {

	if (originalNode.isLiveOrCompiled()) {
	    throw new RestrictedAccessException(J3dI18N.getString("Node13"));
	}
        super.duplicateSceneGraphObject(originalNode);
	NodeRetained attr = (NodeRetained) originalNode.retained;
	NodeRetained rt = (NodeRetained) retained;

	rt.setPickable(attr.getPickable());
	rt.setCollidable(attr.getCollidable());
    }


    /**
     * When set to <code>true</code> this <code>Node</code> can be Picked.
     * Setting to false indicates that this node and it's children
     * are ALL unpickable.
     *
     * @param pickable Indicates if this node should be pickable or not
     */
    public void setPickable( boolean pickable ) {
	if (isLiveOrCompiled())
	    if(!this.getCapability(ALLOW_PICKABLE_WRITE))
		throw new CapabilityNotSetException(J3dI18N.getString("Node14"));

	((NodeRetained)retained).setPickable(pickable);
    }

    /**
     * Returns true if this <code>Node</code> is pickable,
     * false if it is not pickable.
     */
    public boolean getPickable() {
	if (isLiveOrCompiled())
	    if(!this.getCapability(ALLOW_PICKABLE_READ))
		throw new CapabilityNotSetException(J3dI18N.getString("Node3"));

	return ((NodeRetained)retained).getPickable();
    }

    /**
     * checks for cycles in the scene graph
     */
    void checkForCycle() {
	if (visited) {
	    throw new SceneGraphCycleException(J3dI18N.getString("Node15"));
	}
	visited = true;
	Node parent = getParent();
	if (parent != null) {
	    parent.checkForCycle();
	}
	visited = false;
    }
	
}