locale.java

JAVA3D矩陈的相关类

/*
 * $RCSfile: Locale.java,v $
 *
 * Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved.
 *
 * Use is subject to license terms.
 *
 * $Revision: 1.8 $
 * $Date: 2007/02/09 17:18:09 $
 * $State: Exp $
 */

package javax.media.j3d;

import javax.vecmath.*;
import java.util.Vector;
import java.util.Enumeration;
import java.util.ArrayList;

/**
 * A Locale object defines a high-resolution position within a
 * VirtualUniverse, and serves as a container for a collection of
 * BranchGroup-rooted subgraphs (branch graphs), at that position.
 * Objects within a Locale are defined using standard double-precision
 * coordinates, relative to the origin of the Locale.  This origin
 * defines the Virtual World coordinate system for that Locale.
 * <p>
 * A Locale object defines methods to set and get its high-resolution
 * coordinates, and methods to add, remove, and enumerate the branch
 * graphs.
 *
 * <p>
 * For more information, see the
 * <a href="doc-files/intro.html">Introduction to the Java 3D API</a> and
 * <a href="doc-files/VirtualUniverse.html">Scene Graph Superstructure</a>
 * documents.
 *
 * @see VirtualUniverse
 * @see HiResCoord
 * @see BranchGroup
 */

public class Locale extends Object {

    /**
     * The virtual universe that this Locale object is contained within.
     */
    VirtualUniverse universe;

    /**
     * The high resolution coordinate associated with this Locale object.
     */
    HiResCoord 	hiRes;

    /**
     * List of BranchGroup objects included in this Locale
     */
    Vector	branchGroups = new Vector();

    // locale's identifier
    String nodeId = null;

    /**
     * Constructs and initializes a new high resolution Locale object
     * located at (0, 0, 0).
     * @param universe the virtual universe that will contain this
     * Locale object
     */
    public Locale(VirtualUniverse universe) {
	this.universe = universe;
	this.universe.addLocale(this);
	this.hiRes = new HiResCoord();
        nodeId = universe.getNodeId();
    }

    /**
     * Constructs and initializes a new high resolution Locale object
     * from the parameters provided.
     * @param universe the virtual universe that will contain this
     * Locale object
     * @param x an eight element array specifying the x position
     * @param y an eight element array specifying the y position
     * @param z an eight element array specifying the z position
     */
    public Locale(VirtualUniverse universe, int[] x, int[] y, int[] z) {
	this.universe = universe;
	this.universe.addLocale(this);
	this.hiRes = new HiResCoord(x, y, z);
        nodeId = universe.getNodeId();
    }

    /**
     * Constructs and initializes a new high resolution Locale object
     * at the location specified by the HiResCoord argument.
     * @param universe the virtual universe that will contain this
     * Locale object
     * @param hiRes the HiRes coordinate to use in creating this Locale
     */
    public Locale(VirtualUniverse universe, HiResCoord hiRes) {
	this.universe = universe;
	this.universe.addLocale(this);
	this.hiRes = new HiResCoord(hiRes);
        nodeId = universe.getNodeId();
    }

    /**
     * Retrieves the virtual universe within which this Locale object
     * is contained.  A null reference indicates that this
     * Locale has been removed from its VirtualUniverse.
     * @return the virtual universe within which this Locale object
     * is contained.
     */
    public VirtualUniverse getVirtualUniverse() {
	return universe;
    }

    /**
     * Sets the HiRes coordinate of this Locale to the location
     * specified by the parameters provided.
     * @param x an eight element array specifying the x position
     * @param y an eight element array specifying the y position
     * @param z an eight element array specifying the z position
     */
    public void setHiRes(int[] x, int[] y, int[] z) { 
	this.hiRes.setHiResCoord(x, y, z);
    }

    /**
     * Sets the HiRes coordinate of this Locale
     * to the location specified by the HiRes argument.
     * @param hiRes the HiRes coordinate specifying this node's new location
     */
    public void setHiRes(HiResCoord hiRes) {
	this.hiRes.setHiResCoord(hiRes);
    }

    /**
     * Returns this node's HiResCoord.
     * @param hiRes a HiResCoord object that will receive the
     * HiRes coordinate of this Locale node
     */
    public void getHiRes(HiResCoord hiRes) {
	this.hiRes.getHiResCoord(hiRes);
    }

    /**
     * Add a new branch graph rooted at BranchGroup to 
     * the list of branch graphs.
     * @param branchGroup root of the branch graph to be added
     * @exception IllegalStateException if this Locale has been
     * removed from its VirtualUniverse.
     * @exception MultipleParentException if the specified BranchGroup node
     * is already live.
     */
    public void addBranchGraph(BranchGroup branchGroup){
	if (universe == null) {
	    throw new IllegalStateException(J3dI18N.getString("Locale4"));
	}

	// if the BranchGroup already has a parent, or has already been
	// added to a locale, throw MultipleParentException
        if ((((BranchGroupRetained)branchGroup.retained).parent != null) ||
	    (branchGroup.isLive())) {
	    throw new MultipleParentException(J3dI18N.getString("Locale0"));
        }

        universe.notifyStructureChangeListeners(true, this, branchGroup);
	universe.resetWaitMCFlag();
	synchronized (universe.sceneGraphLock) {
	    doAddBranchGraph(branchGroup);
	    universe.setLiveState.reset(this);
	}
	universe.waitForMC();
    }

    // The method that does the work once the lock is acquired.
    void doAddBranchGraph(BranchGroup branchGroup) {
	BranchGroupRetained bgr = (BranchGroupRetained)branchGroup.retained;
	J3dMessage createMessage;
	SetLiveState s = universe.setLiveState;

	// bgr.setLocale(this);

	// addElement needs to precede setLive or else any liveness checks
        // in the initialize() call of a user behavior (ie, calling collision
        // or picking constructor with a SceneGraphPath) will fail
        // when SceneGraphPath.validate() attempts to verify that
        // the proper Locale is associated with that SceneGraphPath
	bgr.attachedToLocale = true;
	branchGroups.addElement(branchGroup);
	s.reset(this);
	s.currentTransforms[0] = new Transform3D[2];
	s.currentTransforms[0][0] = new Transform3D();
	s.currentTransforms[0][1] = new Transform3D();
	s.currentTransformsIndex[0] = new int[2];
	s.currentTransformsIndex[0][0] = 0;
	s.currentTransformsIndex[0][1] = 0;
	
	s.localToVworld = s.currentTransforms;
	s.localToVworldIndex = s.currentTransformsIndex;

        s.branchGroupPaths = new ArrayList();
        s.branchGroupPaths.add(new BranchGroupRetained[0]);

        s.orderedPaths = new ArrayList(1);
        s.orderedPaths.add(new OrderedPath());

        s.switchStates = new ArrayList(1);
        s.switchStates.add(new SwitchState(false));

	bgr.setLive(s);

	createMessage = new J3dMessage();
	createMessage.threads = J3dThread.UPDATE_RENDER| J3dThread.UPDATE_RENDERING_ENVIRONMENT;
	createMessage.type = J3dMessage.ORDERED_GROUP_INSERTED;
	createMessage.universe = universe;
	createMessage.args[0] = s.ogList.toArray();
	createMessage.args[1] = s.ogChildIdList.toArray();
	createMessage.args[2] = s.ogOrderedIdList.toArray();
	createMessage.args[3] = s.ogCIOList.toArray();
	createMessage.args[4] = s.ogCIOTableList.toArray();
	
	VirtualUniverse.mc.processMessage(createMessage);

	createMessage = new J3dMessage();
	createMessage.threads = J3dThread.UPDATE_RENDERING_ENVIRONMENT;
	createMessage.type = J3dMessage.VIEWSPECIFICGROUP_INIT;
	createMessage.universe = universe;
	createMessage.args[0] = s.changedViewGroup;
	createMessage.args[1] = s.changedViewList;
	createMessage.args[2] = s.keyList;
	VirtualUniverse.mc.processMessage(createMessage);
	
	
	createMessage = new J3dMessage();
	createMessage.threads = s.notifyThreads;
        createMessage.type = J3dMessage.INSERT_NODES;
        createMessage.universe = universe;
        createMessage.args[0] = s.nodeList.toArray();
	createMessage.args[1] = null;
	createMessage.args[2] = null;
	if (s.viewScopedNodeList != null) {
	    createMessage.args[3] = s.viewScopedNodeList;
	    createMessage.args[4] = s.scopedNodesViewList;
	}
	VirtualUniverse.mc.processMessage(createMessage);

	int sz = s.behaviorNodes.size();
	for (int i=0; i< sz; i++) {
	    BehaviorRetained b;
	    b = (BehaviorRetained)s.behaviorNodes.get(i);
	    b.executeInitialize();
	}

	createMessage = new J3dMessage();
        createMessage.threads = J3dThread.UPDATE_BEHAVIOR;
        createMessage.type = J3dMessage.BEHAVIOR_ACTIVATE;
        createMessage.universe = universe;
        VirtualUniverse.mc.processMessage(createMessage);

	// Free up memory.
	s.reset(null);
    }

    /**
     * Removes a branch graph rooted at BranchGroup from 
     * the list of branch graphs.
     * @param branchGroup root of the branch graph to be removed
     * @exception IllegalStateException if this Locale has been
     * removed from its VirtualUniverse.
     * @exception CapabilityNotSetException if the ALLOW_DETACH capability is
     * not set in the specified BranchGroup node.
     */
    public void removeBranchGraph(BranchGroup branchGroup){
	if (universe == null) {
	    throw new IllegalStateException(J3dI18N.getString("Locale4"));
	}

	if (! branchGroup.getCapability(BranchGroup.ALLOW_DETACH)) {
	    throw new CapabilityNotSetException(J3dI18N.getString("Locale1"));
	}
	universe.resetWaitMCFlag();
	synchronized (universe.sceneGraphLock) {
	    doRemoveBranchGraph(branchGroup, null, 0);
	    universe.setLiveState.reset(this);
	}
	universe.waitForMC();
    }


    // Method to remove all branch graphs from this Locale and remove
    // this Locale from the VirtualUniverse
    void removeFromUniverse() {
	if (branchGroups.size() > 0) {
	    universe.resetWaitMCFlag();
	    synchronized (universe.sceneGraphLock) {
		// Make a copy of the branchGroups list so that we can safely
		// iterate over it.
		Object[] bg = branchGroups.toArray();
		for (int i = 0; i < bg.length; i++) {
		    doRemoveBranchGraph((BranchGroup)bg[i], null, 0);
		}
	    }
	    // Put after sceneGraphLock to prevent deadlock
	    universe.waitForMC();
	}

	// free nodeId
	if (nodeId != null) {
	    universe.nodeIdFreeList.addElement(nodeId);
	    nodeId = null;
	}

	// Set universe pointer to null, indicating that this Locale
	// has been removed from its universe
	universe = null;
    }


    // The method that does the work once the lock is acquired.
    void doRemoveBranchGraph(BranchGroup branchGroup, 
                                J3dMessage messages[], int startIndex) {

	BranchGroupRetained bgr = (BranchGroupRetained)branchGroup.retained;
	J3dMessage destroyMessage;

	if (!branchGroup.isLive())
	    return;
	bgr.attachedToLocale = false;
	branchGroups.removeElement(branchGroup);
	universe.setLiveState.reset(this);
	bgr.clearLive(universe.setLiveState);
	bgr.setParent(null);
	bgr.setLocale(null);

	if (messages == null) {
	    destroyMessage = new J3dMessage();
	} else {
	    destroyMessage = messages[startIndex++];
	}
	destroyMessage.threads = J3dThread.UPDATE_RENDER| J3dThread.UPDATE_RENDERING_ENVIRONMENT;
	destroyMessage.type = J3dMessage.ORDERED_GROUP_REMOVED;
	destroyMessage.universe = universe;
	destroyMessage.args[0] = universe.setLiveState.ogList.toArray();
	destroyMessage.args[1] = universe.setLiveState.ogChildIdList.toArray();
	destroyMessage.args[3] = universe.setLiveState.ogCIOList.toArray();
	destroyMessage.args[4] = universe.setLiveState.ogCIOTableList.toArray();

        // Issue 312: We need to send the REMOVE_NODES message to the
        // RenderingEnvironmentStructure before we send VIEWSPECIFICGROUP_CLEAR,
        // since the latter clears the list of views that is referred to by
        // scopedNodesViewList and used by removeNodes.
	if (messages == null) {
            VirtualUniverse.mc.processMessage(destroyMessage);
            destroyMessage = new J3dMessage();
        } else {
            destroyMessage = messages[startIndex++];
        }
        destroyMessage.threads = universe.setLiveState.notifyThreads;