path: root/src/javax/media/j3d/SceneGraphPath.java

/*
 * Copyright 1997-2008 Sun Microsystems, Inc.  All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Sun designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Sun in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
 * CA 95054 USA or visit www.sun.com if you need additional information or
 * have any questions.
 *
 */

package javax.media.j3d;

import javax.vecmath.Point3d;
import javax.vecmath.Point4d;

/**
 * A SceneGraphPath object represents the path from a Locale to a
 * terminal node in the scene graph.  This path consists of a Locale, a
 * terminal node, and an array of internal nodes that are in the path
 * from the Locale to the terminal node.  The terminal node may be
 * either a Leaf node or a Group node.  A valid SceneGraphPath must
 * uniquely identify a specific instance of the terminal node.  For
 * nodes that are not under a SharedGroup, the minimal SceneGraphPath
 * consists of the Locale and the terminal node itself.  For nodes that
 * are under a SharedGroup, the minimal SceneGraphPath consists of the
 * Locale, the terminal node, and a list of all Link nodes in the path
 * from the Locale to the terminal node.  A SceneGraphPath may optionally
 * contain other interior nodes that are in the path.
 * A SceneGraphPath is verified for correctness and uniqueness when
 * it is sent as an argument to other methods of Java 3D.
 * <p>
 * In the array of internal nodes, the node at index 0 is the node
 * closest to the Locale.  The indices increase along the path to the
 * terminal node, with the node at index length-1 being the node closest
 * to the terminal node.  The array of nodes does not contain either the
 * Locale (which is not a node) or the terminal node.
 * <p>
 * When a SceneGraphPath is returned from the picking or collision
 * methods of Java 3D, it will also contain the value of the
 * LocalToVworld transform of the terminal node that was in effect at
 * the time the pick or collision occurred.
 * Note that ENABLE_PICK_REPORTING and ENABLE_COLLISION_REPORTING are
 * disabled by default.  This means that the picking and collision
 * methods will return the minimal SceneGraphPath by default.
 *
 * @see Node#ENABLE_PICK_REPORTING
 * @see Node#ENABLE_COLLISION_REPORTING
 * @see BranchGroup#pickAll
 * @see BranchGroup#pickAllSorted
 * @see BranchGroup#pickClosest
 * @see BranchGroup#pickAny
 */

public class SceneGraphPath {

    Locale root = null;
    Node[] interior = null;
    Node item = null;
    Transform3D transform = new Transform3D();

    // Intersect Point for item when picked
    Point3d intersectPoint = new Point3d();

    double pickDistance;                    // distance to pick location

    /**
     * Constructs a SceneGraphPath object with default parameters.
     * The default values are as follows:
     * <ul>
     * root : null<br>
     * object : null<br>
     * list of (interior) nodes : null<br>
     * transform : identity<br>
     * </ul>
     */
    public SceneGraphPath() {
	// Just use defaults
    }

    /**
     * Constructs a new SceneGraphPath object.
     * @param root the Locale object of this path
     * @param object the terminal node of this path
     */
    public SceneGraphPath(Locale root, Node  object) {

        this.item = object;
	this.root = root;
    }

    /**
     * Constructs a new SceneGraphPath object.
     * @param root the Locale object of this path
     * @param nodes an array of node objects in the path from
     * the Locale to the terminal node
     * @param object the terminal node of this path
     */
    public SceneGraphPath(Locale root, Node nodes[], Node  object) {

        this.item = object;
	this.root = root;
	this.interior = new Node[nodes.length];
	for (int i = 0; i < nodes.length; i++)
	    this.interior[i] = nodes[i];
    }


    /**
     * Constructs a new SceneGraphPath object
     * @param sgp  the SceneGraphPath to copy from
     */
    SceneGraphPath(SceneGraphPath sgp) {
	set(sgp);
    }

    /**
     * Sets this path's values to that of the specified path.
     * @param newPath the SceneGraphPath to copy
     */
    public final void set(SceneGraphPath newPath) {
	this.root = newPath.root;
	this.item = newPath.item;
	this.transform.set(newPath.transform);
	if(newPath.interior != null && newPath.interior.length > 0) {
	    interior = new Node[newPath.interior.length];
	    for (int i = 0; i < interior.length; i++)
		this.interior[i] = newPath.interior[i];
	}
	else
	    interior = null;
    }

    /**
     * Sets this path's Locale to the specified Locale.
     * @param newLocale The new Locale
     */
    public final void setLocale(Locale newLocale) {
	root = newLocale;
    }

    /**
     * Sets this path's terminal node to the specified node object.
     * @param object the new terminal node
     */
    public final void setObject(Node  object) {
	    this.item = object;
    }

    /**
     * Sets this path's node objects to the specified node objects.
     * @param nodes an array of node objects in the path from
     * the Locale to the terminal node
     */
    public final void setNodes(Node nodes[]) {

	if(nodes != null && nodes.length > 0) {
	    interior = new Node[nodes.length];
	    for (int i = 0; i < nodes.length; i++)
		this.interior[i] = nodes[i];
	}
	else
	    interior = null;
    }

    /**
     * Replaces the node at the specified index with newNode.
     * @param index the index of the node to replace
     * @param newNode the new node
     * @exception NullPointerException if the node array pointer is null.
     *
     */
    public final void setNode(int index, Node newNode) {
      if(interior == null)
	throw new NullPointerException(J3dI18N.getString("SceneGraphPath0"));

      interior[index] = newNode;
    }

    /**
     * Sets the transform component of this SceneGraphPath to the value of
     * the passed transform.
     * @param trans the transform to be copied. trans should be the
     * localToVworld matrix of this SceneGraphPath object.
     */
     public final void setTransform(Transform3D trans) {
	 transform.set(trans);
     }

    /**
      *  Returns a copy of the transform associated with this SceneGraphPath;
      *  returns null if there is no transform associated.
      *  If this SceneGraphPath was returned by a Java 3D picking or
      *  collision method, the local coordinate to virtual world
      *  coordinate transform for this scene graph object at the
      *  time of the pick or collision is recorded.
      *  @return the local to VWorld transform
      */
    public final Transform3D getTransform() {
	return new Transform3D(transform);
    }

    /**
     * Retrieves the path's Locale
     * @return this path's Locale
     */
    public final Locale getLocale() {
	return this.root;
    }

    /**
     * Retrieves the path's terminal node object.
     * @return the terminal node
     */
    public final Node getObject() {
	return this.item;
    }

    /**
     * Retrieves the number of nodes in this path.  The number of nodes
     * does not include the Locale or the terminal node object itself.
     * @return a count of the number of nodes in this path
     */
    public final int nodeCount() {
        if(interior == null)
	  return 0;
	return interior.length;
    }

    /**
     * Retrieves the node at the specified index.
     * @param index the index specifying which node to retrieve
     * @return the specified node
     */
    public final Node getNode(int index) {
      if(interior == null)
	throw new
          ArrayIndexOutOfBoundsException(J3dI18N.getString("SceneGraphPath1"));
	return interior[index];
    }

    /**
     * Returns true if all of the data members of path testPath are
     * equal to the corresponding data members in this SceneGraphPath and
     * if the values of the transforms is equal.
     * @param testPath the path we will compare this object's path against.
     * @return  true or false
     */
    public boolean equals(SceneGraphPath testPath) {
	boolean result = true;
        try {

	  if(testPath == null || root != testPath.root || item != testPath.item)
	    return false;

	  result = transform.equals(testPath.transform);

	  if(result == false)
	    return false;

	  if(interior == null || testPath.interior == null) {
	    if(interior != testPath.interior)
	      return false;
	    else
	      result = (root == testPath.root && item == testPath.item);

	  } else  {
	    if (interior.length == testPath.interior.length) {
	      for (int i = 0; i < interior.length; i++)
		if (interior[i] !=  testPath.interior[i]) {
		    return false;
		}
	    }
	    else
		return false;
	  }

        }
        catch (NullPointerException e2) {return false;}

        return result;
    }

    /**
     * Returns true if the Object o1 is of type SceneGraphPath and all of the
     * data members of o1 are equal to the corresponding data members in
     * this SceneGraphPath  and if the values of the transforms is equal.
     * @param o1 the object we will compare this SceneGraphPath's path against.
     * @return  true or false
     */
    @Override
    public boolean equals(Object o1) {
	boolean result = true;

        try {
	   SceneGraphPath testPath = (SceneGraphPath)o1;
           if(testPath == null || root != testPath.root || item != testPath.item)
	     return false;

	   result = transform.equals(testPath.transform);

	   if(result == false)
	     return false;

	   if(interior == null || testPath.interior == null) {
             if(interior != testPath.interior)
	       return false;
             else
	       result = (root == testPath.root && item == testPath.item);

           } else  {
	     if (interior.length == testPath.interior.length) {
	       for (int i = 0; i < interior.length; i++)
		 if (interior[i] !=  testPath.interior[i]) {
		     return false;
		 }
	     }
	     else
		 return false;
           }

 	   return result;
        }
        catch (NullPointerException e2) {return false;}
        catch (ClassCastException   e1) {return false;}
    }


    /**
     * Returns a hash number based on the data values in this
     * object. Two different SceneGraphPath objects with identical data
     * values (ie, returns true for trans.equals(SceneGraphPath) ) will
     * return the same hash number.  Two Paths with different data members
     * may return the same hash value, although this is not likely.
     * @return the integer hash value
     */
    @Override
    public int hashCode() {
       HashKey key = new HashKey(250);
       // NOTE: Needed to add interior != null because this method is called
       // by object.toString() when interior is null.
       if(interior != null && item != null) {
             for(int i=0; i<interior.length; i++) {
                 key.append(LinkRetained.plus).append( item.toString() );
             }
       }
       return( key.hashCode() + transform.hashCode() );
    }

   /**
     * Determines whether two SceneGraphPath objects represent the same
     * path in the scene graph; either object might include a different
     * subset of internal nodes; only the internal link nodes, the Locale,
     * and the Node itself are compared.  The paths are not validated for
     * correctness or uniqueness.
     * @param testPath  the SceneGraphPath to be compared to this SceneGraphPath
     * @return true or false
     */
    public final boolean isSamePath(SceneGraphPath testPath) {
         int count=0, i;

         if(testPath == null || testPath.item != this.item || root != testPath.root)
             return false;

         if(interior != null && testPath.interior != null) {
                for(i=0 ; i<interior.length ; i++)  {
                     if(interior[i] instanceof Link)  {
                         // found Link in this, now check for matching in testPath
                         while(count < testPath.interior.length) {
                             if(testPath.interior[count] instanceof Link) {
                                  if(testPath.interior[count] != interior[i]) {
				      return false;
                                  }
                                  count++;
                                  break;
                             }
                             count++;
                             // if true, this had an extra Link
                             if(count == testPath.interior.length)
				 return false;
                         }
                     }
                }
                // make sure testPath doesn't have any extra Links
                while(count < testPath.interior.length) {
                    if(testPath.interior[count] instanceof Link)
			return false;
                    count++;
                }
         } else if(interior != testPath.interior)  // ==> they are not both null
	          return false;

         return true;
    }

    /**
     * Returns a string representation of this object;
     * the string contains the class names of all Nodes in the SceneGraphPath,
     * the toString() method of any associated user data provided by
     * SceneGraphObject.getUserData(), and also prints out the transform,
     * if it is not null.
     *  @return String representation of this object
     */
    @Override
    public String toString() {

	StringBuffer str = new StringBuffer();
	Object obj;

	if(root == null && interior == null && item == null)
	    return (super.toString());

	if(root != null)
	    str.append(root + " : ");

	if(interior != null) {
	    for(int i=0; i<interior.length; i++) {

		str.append( interior[i].getClass().getName());
		obj = interior[i].getUserData();
		if(obj == null)
		    str.append(" : ");
		else
		    str.append(", " + obj + " : ");
	    }
	}

	if(item != null) {
	    //	       str.append( item + ", "+ item.getUserData() + "--"+intersectPoint );
	    str.append( item.getClass().getName() );
	    obj = item.getUserData();
	    if(obj != null)
		str.append(", " + obj);

	    try {
		if (item.getClass().getName().equals("javax.media.j3d.Shape3D"))
		    str.append( ((Shape3D)item).getGeometry() );
	    }
	    catch( CapabilityNotSetException e) {}
	}

	str.append("\n" + "LocalToVworld Transform:\n" + transform);

	return new String(str);
    }

    /**
     * Determine if this SceneGraphPath is unique and valid
     * The graph don't have to be live for this checking.
     * Set Locale when it is null.
     * Only the essential link node which led to the Locale
     * is validated.
     */
    boolean validate() {
	NodeRetained node = (NodeRetained) item.retained;

	Locale locale = node.locale;

	if (root != null) {
	    if (item.isLive()) {
		if (locale != root) {
		    return false;
		}
	    }
	} else {
	    root = locale;
	}

	int idx =  (interior == null ? 0: interior.length);

	do {
	    if (node instanceof SharedGroupRetained) {
		if (interior == null)
		    return false;
		while (--idx > 0) {
		    if (((SharedGroupRetained)node).parents.contains(interior[idx].retained)) {
			break;
		    }
		}
		if (idx < 0) {
		    return false;
		}
		node = (NodeRetained) interior[idx].retained;
	    } else {
		node = node.parent;
	    }
	} while (node != null);

	return true;
    }


    // return key of this path or null is not in SharedGroup
    void getHashKey(HashKey key) {
	if (interior != null) {
	    key.reset();
	    key.append(root.nodeId);
	    for(int i=0; i<interior.length; i++) {
		Node node = interior[i];

		if (!node.isLive()) {
		    throw new RuntimeException(J3dI18N.getString("SceneGraphPath3"));
		}

		NodeRetained nodeR = (NodeRetained) node.retained;
		if (nodeR.nodeType == NodeRetained.LINK) {
		    key.append("+").append(nodeR.nodeId);
		}
	    }
	}
    }

    /**
     * Determines whether this SceneGraphPath is unique and valid.  The
     * verification determines that all of the nodes are live, that the
     * specified path is unique, that the correct Locale is specified, and
     * that there is a Node specified.
     */
    boolean validate(HashKey key) {

	int i;

	// verify that there is at least a Locale and Node specified
	if( root == null )
	    throw new IllegalArgumentException(J3dI18N.getString("SceneGraphPath2"));

	if( item == null )
	    throw new IllegalArgumentException(J3dI18N.getString("SceneGraphPath10"));

	// verify liveness
	if( !item.isLive() )
	    throw new IllegalArgumentException(J3dI18N.getString("SceneGraphPath3"));

	try {
	    getHashKey(key);
	} catch (RuntimeException ex) {
	    throw new IllegalArgumentException(ex.getMessage());
	}

	// The rest of the code verifies uniqueness; it traverses the retained
	// hierarchy of the scene graph.  This could be problematic later in
	// when certain compile mode optimizations are added. */

	NodeRetained bottomNR, currentNR, nextNR=null;
	Node currentNode;
	int count = 0;

	// Need to traverse the retained hierarchy on a live scene graph
	//  from bottom to top
	//
	// bottomNR = last verified node; as nodes are verified, bottomNR
	//            moves up the scen graph
	// nextNR = Next node that the user has specified after bottomNR
	// currentNR = current node; is changing as it covers all the
	//             nodes from bottomNR to nextNR

	// If the parent of a NodeRetained is null, we know that the parent
	// is either a BranchGroupRetained at the top of a scene graph or
	// it is a SharedGroupRetained, potentially with multiple parents.

	bottomNR = (NodeRetained)(item.retained);

	if(interior != null) {
	    for(i=interior.length-1; i >=0  ; i--) {
		nextNR = (NodeRetained)(interior[i].retained);
		currentNR = bottomNR.parent;
		if(currentNR == null  &&  bottomNR instanceof SharedGroupRetained) {
		    if(((SharedGroupRetained)(bottomNR)).parents.contains(nextNR) )
			currentNR = nextNR;
		    else
			throw new IllegalArgumentException(J3dI18N.getString("SceneGraphPath5"));

		}

		while(currentNR != nextNR) {
		    if(currentNR == null) {
			throw new IllegalArgumentException(J3dI18N.getString("SceneGraphPath11"));
		    }

		    if(currentNR instanceof SharedGroupRetained) {
			if(((SharedGroupRetained)
			    (currentNR)).parents.contains(nextNR) )
			    currentNR = nextNR;
			else
			    throw new IllegalArgumentException(J3dI18N.getString("SceneGraphPath5"));

		    } else {
			currentNR = currentNR.parent;
		    }
		}
		bottomNR = currentNR;
	    }
	}

	//  Now go from bottomNR to Locale
	currentNR = bottomNR.parent;
	if(currentNR == null && bottomNR instanceof SharedGroupRetained) {
	    throw new IllegalArgumentException(J3dI18N.getString("SceneGraphPath5"));
	}

	while(currentNR != null) {
	    if(currentNR instanceof LinkRetained) {
		throw new IllegalArgumentException(J3dI18N.getString("SceneGraphPath5"));
	    }

	    bottomNR = currentNR;
	    currentNR = currentNR.parent;
	    if(currentNR == null && bottomNR instanceof SharedGroupRetained) {
		throw new IllegalArgumentException(J3dI18N.getString("SceneGraphPath5"));
	    }
	}

	// get the real BranchGroup from the BranchGroupRetained
	currentNode = (Node)(bottomNR.source);
	// now bottomNR should be a BranchGroup -- should try an assert here
	if(!root.branchGroups.contains(currentNode)) {
	    throw new IllegalArgumentException(J3dI18N.getString("SceneGraphPath9"));
	}

	return true;
    }

    /**
     * Returns the distance from the intersectPoint for item and
     * origin.
     */
    double getDistanceFrom( Point3d origin ) {
	return intersectPoint.distance(origin);
    }

    /**
     * Returns the distance of the pick
     */
    double getDistance() {
	return pickDistance;
    }

    final void setIntersectPoint( Point3d point ) {
	intersectPoint.set(point);
    }

    final void setIntersectPointDis( Point4d pickLocation ) {
	//	System.err.println( "setIntersectPointDis pickLocation= "+pickLocation);
	intersectPoint.x = pickLocation.x;
	intersectPoint.y = pickLocation.y;
	intersectPoint.z = pickLocation.z;
	pickDistance = pickLocation.w;
    }

    final Point3d getIntersectPoint() {
	return intersectPoint;
    }
}