configureduniverse.java

JAVA3D矩陈的相关类

/*
 * $RCSfile: ConfiguredUniverse.java,v $
 *
 * Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * - Redistribution of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 *
 * - Redistribution in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in
 *   the documentation and/or other materials provided with the
 *   distribution.
 *
 * Neither the name of Sun Microsystems, Inc. or the names of
 * contributors may be used to endorse or promote products derived
 * from this software without specific prior written permission.
 *
 * This software is provided "AS IS," without a warranty of any
 * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
 * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY
 * EXCLUDED. SUN MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL
 * NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF
 * USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS
 * DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR
 * ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
 * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
 * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR
 * INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGES.
 *
 * You acknowledge that this software is not designed, licensed or
 * intended for use in the design, construction, operation or
 * maintenance of any nuclear facility.
 *
 * $Revision: 1.6 $
 * $Date: 2007/02/09 17:20:44 $
 * $State: Exp $
 */

package com.sun.j3d.utils.universe;

import java.net.URL;
import java.net.MalformedURLException;
import java.util.Collection;
import java.util.Iterator;
import java.util.Map;
import javax.media.j3d.*;

/**
 * This utility class creates all the necessary objects on the view side of
 * the scene graph.  Specifically, it creates a Locale, one or more
 * ViewingPlatforms, and at least one Viewer object.<p>
 *
 * ConfiguredUniverse can set up a viewing environment based upon the contents
 * of a configuration file.  This allows an application to run without change
 * across a broad range of viewing configurations, such as windows on
 * conventional desktops, stereo-enabled views, full screen immersive displays
 * on single or multiple screens, or virtual reality installations including
 * cave and head-mounted displays incorporating 6 degree of freedom sensor
 * devices.<p>
 *
 * A configuration file may create InputDevice, Sensor, and
 * ViewPlatformBehavior instances as well as Viewers and ViewingPlatforms.  At
 * least one Viewer must be provided by the configuration.  If a
 * ViewingPlatform is not provided, a default one will be created and the
 * Viewer will be attached to it.<p>
 *
 * A configuration file may be specified directly by passing a URL to a
 * ConfiguredUniverse constructor.  Alternatively, a ConfigContainer may be
 * created from a configuration file first, and then passed to an appropriate
 * ConfiguredUniverse constructor.  The latter technique allows Java system
 * properties that affect Java 3D to be specified in the configuration file,
 * as long as no references to a VirtualUniverse are made before creating the
 * container.<p>
 *
 * If a configuration file or container is not provided, then
 * ConfiguredUniverse creates a default viewing environment in the same way as
 * SimpleUniverse.  If one or more Canvas3D objects are provided, it will use
 * them instead of creating new ones.  All of the constructors provided by
 * SimpleUniverse are also available here.<p>
 * 
 * The syntax and description of the configuration file may be found
 * <A href="doc-files/config-syntax.html">here.</a> Example config files can
 * be found <A href="doc-files/config-examples.html">here.</a>
 *
 * @see Locale
 * @see Viewer
 * @see ViewingPlatform
 * @see ConfigContainer
 * @see <a href="doc-files/config-syntax.html">
 *      The Java 3D Configuration File</a>
 * @see <a href="doc-files/config-examples.html">
 *      Example Configuration Files</a>
 *
 * @since Java 3D 1.3
 */
public class ConfiguredUniverse extends SimpleUniverse {

    /**
     * The configuration instance for this universe.
     */
    private ConfigContainer configContainer = null;

    /**
     * Equivalent to <code>SimpleUniverse()</code>.  Creates a
     * Locale, a single ViewingPlatform, and a Viewer object.
     *
     * @see SimpleUniverse#SimpleUniverse()
     * @see Locale
     * @see Viewer
     * @see ViewingPlatform
     */
    public ConfiguredUniverse() {
	super();
    }

    /**
     * Equivalent to <code>SimpleUniverse(int)</code>.
     * Creates a Locale, a single ViewingPlatform with the specified number of
     * transforms, and a Viewer object.
     *
     * @param transformCount the number of transforms in the
     *  MultiTransformGroup object to be created
     *
     * @see SimpleUniverse#SimpleUniverse(int)
     * @see Locale
     * @see Viewer
     * @see ViewingPlatform
     * @see MultiTransformGroup
     */
    public ConfiguredUniverse(int transformCount) {
	super(transformCount);
    }

    /**
     * Equivalent to <code>SimpleUniverse(Canvas3D)</code>.
     * Creates a Locale, a single ViewingPlatform, and a Viewer object using
     * the given Canvas3D instance.
     *
     * @param canvas the canvas to associate with the Viewer object;
     *  passing in null will cause this parameter to be ignored and a canvas 
     *  to be created by the utility
     *
     * @see SimpleUniverse#SimpleUniverse(Canvas3D)
     * @see Locale
     * @see Viewer
     * @see ViewingPlatform
     */
    public ConfiguredUniverse(Canvas3D canvas) {
	super(canvas);
    }

    /**
     * Equivalent to <code>SimpleUniverse(Canvas3D, int)</code>.
     * Creates a Locale, a single ViewingPlatform with the specified number of
     * transforms, and a Viewer object with the given Canvas3D.
     *
     * @param canvas the canvas to associate with the Viewer object;
     *  passing in null will cause this parameter to be ignored and a canvas 
     *  to be created by the utility
     * @param transformCount the number of transforms in the
     *  MultiTransformGroup object to be created
     *
     * @see SimpleUniverse#SimpleUniverse(Canvas3D, int)
     * @see Locale
     * @see Viewer
     * @see ViewingPlatform
     * @see MultiTransformGroup
     */
    public ConfiguredUniverse(Canvas3D canvas, int transformCount) {
	super(canvas, transformCount);
    }

    /**
     * Equivalent to <code>SimpleUniverse(ViewingPlatform, Viewer)</code>.
     * Creates the view side of the scene graph with the given ViewingPlatform
     * and Viewer.
     *
     * @param viewingPlatform the viewingPlatform to use to create
     *  the view side of the scene graph
     * @param viewer the viewer object to use to create
     *  the view side of the scene graph
     *
     * @see SimpleUniverse#SimpleUniverse(ViewingPlatform, Viewer)
     * @see ViewingPlatform
     * @see Viewer
     */
    public ConfiguredUniverse(ViewingPlatform viewingPlatform, Viewer viewer) {
        super(viewingPlatform, viewer, null);
    }

    /**
     * Equivalent to <code>SimpleUniverse(ViewingPlatform, Viewer,
     * LocalFactory)</code>.  Creates the view side of the scene graph with
     * the given ViewingPlatform, Viewer, and Locale created by the specified
     * LocaleFactory.
     *
     * @param viewingPlatform the viewingPlatform to use to create
     *  the view side of the scene graph
     * @param viewer the viewer object to use to create
     *  the view side of the scene graph
     * @param localeFactory the factory object used to create the Locale
     *
     * @see SimpleUniverse#SimpleUniverse(ViewingPlatform, Viewer,
     *  LocaleFactory)
     * @see ViewingPlatform
     * @see Viewer
     * @see LocaleFactory
     */
    public ConfiguredUniverse(ViewingPlatform viewingPlatform, Viewer viewer,
			      LocaleFactory localeFactory ) {
        super(viewingPlatform, viewer, localeFactory);
    }

    /**
     * Creates a Locale, a single ViewingPlatform, and a Viewer object from
     * the given array of Canvas3D instances.  
     *
     * @param canvases the canvases to associate with the Viewer object;
     *  passing in null will cause this parameter to be ignored and a canvas 
     *  to be created by the utility
     *
     * @see Locale
     * @see Viewer
     * @see ViewingPlatform
     */
    public ConfiguredUniverse(Canvas3D[] canvases) {
        this(1, canvases, null, null, null, true);
    }

    /**
     * Creates a Locale, a single ViewingPlatform with the specified number of
     * transforms, and a Viewer object using the given array of Canvas3D
     * instances.  
     *
     * @param canvases the canvases to associate with the Viewer object;
     *  passing in null will cause this parameter to be ignored and a canvas 
     *  to be created by the utility
     * @param transformCount the number of transforms in the
     *  MultiTransformGroup object to be created
     *
     * @see Locale
     * @see Viewer
     * @see ViewingPlatform
     * @see MultiTransformGroup
     */
    public ConfiguredUniverse(Canvas3D[] canvases, int transformCount) {
	this(transformCount, canvases, null, null, null, true);
    }

    /**
     * Creates a Locale, a single ViewingPlatform with the specified number of
     * transforms, and a Viewer object using the given array of Canvas3D
     * instances.  
     *
     * @param canvases the canvases to associate with the Viewer object;
     *  passing in null will cause this parameter to be ignored and a canvas 
     *  to be created by the utility
     * @param transformCount the number of transforms in the