com.sun.j3d.utils.universe

## Class ConfiguredUniverse

- java.lang.Object
- - javax.media.j3d.VirtualUniverse
  - - com.sun.j3d.utils.universe.SimpleUniverse
    - - com.sun.j3d.utils.universe.ConfiguredUniverse

-     public class ConfiguredUniverse
      extends SimpleUniverse

  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.

  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.

  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.

  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.

  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.

  The syntax and description of the configuration file may be found here. Example config files can be found here.

  Since:
    Java 3D 1.3
  See Also:
    `Locale`, `Viewer`, `ViewingPlatform`, `ConfigContainer`, The Java 3D Configuration File, Example Configuration Files

- - ### Field Summary

    - ### Fields inherited from class com.sun.j3d.utils.universe.SimpleUniverse

      `locale, viewer`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ConfiguredUniverse()` Equivalent to `SimpleUniverse()`.
    `ConfiguredUniverse(Canvas3D canvas)` Equivalent to `SimpleUniverse(Canvas3D)`.
    `ConfiguredUniverse(Canvas3D[] canvases)` Creates a Locale, a single ViewingPlatform, and a Viewer object from the given array of Canvas3D instances.
    `ConfiguredUniverse(Canvas3D[] canvases, int transformCount)` Creates a Locale, a single ViewingPlatform with the specified number of transforms, and a Viewer object using the given array of Canvas3D instances.
    `ConfiguredUniverse(Canvas3D[] canvases, int transformCount, LocaleFactory localeFactory)` Creates a Locale, a single ViewingPlatform with the specified number of transforms, and a Viewer object using the given array of Canvas3D instances.
    `ConfiguredUniverse(Canvas3D canvas, int transformCount)` Equivalent to `SimpleUniverse(Canvas3D, int)`.
    `ConfiguredUniverse(ConfigContainer userConfig)` Retrieves view-side scenegraph components from the given container to create a universe with one Locale, one or more ViewingPlatforms, and at least one Viewer object.
    `ConfiguredUniverse(ConfigContainer userConfig, LocaleFactory localeFactory, HiResCoord origin)` Retrieves view-side scenegraph components from the given container to create a universe with one Locale created from the specified LocaleFactory and origin, one or more ViewingPlatforms, and at least one Viewer object.
    `ConfiguredUniverse(int transformCount)` Equivalent to `SimpleUniverse(int)`.
    `ConfiguredUniverse(java.net.URL userConfig)` Reads the configuration specified by the given URL to create a Locale, one or more ViewingPlatforms, and at least one Viewer object.
    `ConfiguredUniverse(java.net.URL userConfig, int transformCount)` Reads the configuration specified by the given URL to create a Locale, one or more ViewingPlatforms with the specified number of transforms, and at least one Viewer object.
    `ConfiguredUniverse(java.net.URL userConfig, int transformCount, boolean setVisible)` Reads the configuration specified by the given URL to create a Locale, one or more ViewingPlatforms with the specified number of transforms, and at least one Viewer object with optional visibility.
    `ConfiguredUniverse(java.net.URL userConfig, LocaleFactory localeFactory)` Reads the configuration specified by the given URL to create a Locale using the given LocaleFactory, one or more ViewingPlatforms, and at least one Viewer object.
    `ConfiguredUniverse(java.net.URL userConfig, LocaleFactory localeFactory, boolean setVisible)` Reads the configuration specified by the given URL to create a Locale using the given LocaleFactory, one or more ViewingPlatforms, and at least one Viewer object with optional visibility.
    `ConfiguredUniverse(java.net.URL userConfig, LocaleFactory localeFactory, HiResCoord origin, int transformCount, boolean setVisible)` Reads the configuration specified by the given URL to create a Locale using the specified LocaleFactory with the given origin, one or more ViewingPlatforms with the specified number of transforms, and at least one Viewer object with optional visibility.
    `ConfiguredUniverse(ViewingPlatform viewingPlatform, Viewer viewer)` Equivalent to `SimpleUniverse(ViewingPlatform, Viewer)`.
    `ConfiguredUniverse(ViewingPlatform viewingPlatform, Viewer viewer, LocaleFactory localeFactory)` Equivalent to `SimpleUniverse(ViewingPlatform, Viewer, LocalFactory)`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `cleanup()` Cleanup memory references used by ConfiguredUniverse.
    `ConfigContainer` | `getConfigContainer()` Returns a container holding all the objects defined by the configuration file used to create the ConfiguredUniverse.
    `static java.net.URL` | `getConfigURL()` Returns the config file URL based on system properties.
    `static java.net.URL` | `getConfigURL(java.lang.String defaultURLString)` Returns the config file URL based on system properties.
    `java.util.Map` | `getNamedBehaviors()` Returns all named ViewPlatformBehaviors defined by the configuration file used to create the ConfiguredUniverse, if any.
    `java.util.Map` | `getNamedSensors()` Returns all named Sensors defined by the configuration file used to create the ConfiguredUniverse, if any.
    `Viewer` | `getViewer(int index)` Returns the Viewer object specified by the given index.
    `Viewer[]` | `getViewers()` Returns all of the Viewer objects associated with this scene graph.
    `void` | `setVisible(boolean visible)` Call `setVisible()` on all AWT components created by this ConfiguredUniverse instance.

    - ### Methods inherited from class com.sun.j3d.utils.universe.SimpleUniverse

      `addBranchGraph, getCanvas, getCanvas, getLocale, getPreferredConfiguration, getViewer, getViewingPlatform`

    - ### Methods inherited from class javax.media.j3d.VirtualUniverse

      `addGraphStructureChangeListener, addRenderingErrorListener, addShaderErrorListener, getAllLocales, getJ3DThreadPriority, getProperties, numLocales, removeAllLocales, removeGraphStructureChangeListener, removeLocale, removeRenderingErrorListener, removeShaderErrorListener, setJ3DThreadPriority`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### ConfiguredUniverse

          public ConfiguredUniverse()

      Equivalent to `SimpleUniverse()`. Creates a Locale, a single ViewingPlatform, and a Viewer object.
      See Also:
        `SimpleUniverse.SimpleUniverse()`, `Locale`, `Viewer`, `ViewingPlatform`

    - #### ConfiguredUniverse

          public ConfiguredUniverse(int transformCount)

      Equivalent to `SimpleUniverse(int)`. Creates a Locale, a single ViewingPlatform with the specified number of transforms, and a Viewer object.
      Parameters:
        `transformCount` - the number of transforms in the MultiTransformGroup object to be created
      See Also:
        `SimpleUniverse.SimpleUniverse(int)`, `Locale`, `Viewer`, `ViewingPlatform`, `MultiTransformGroup`

    - #### ConfiguredUniverse

          public ConfiguredUniverse(Canvas3D canvas)

      Equivalent to `SimpleUniverse(Canvas3D)`. Creates a Locale, a single ViewingPlatform, and a Viewer object using the given Canvas3D instance.
      Parameters:
        `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 Also:
        `SimpleUniverse.SimpleUniverse(Canvas3D)`, `Locale`, `Viewer`, `ViewingPlatform`

    - #### ConfiguredUniverse

          public ConfiguredUniverse(Canvas3D canvas,
                            int transformCount)

      Equivalent to `SimpleUniverse(Canvas3D, int)`. Creates a Locale, a single ViewingPlatform with the specified number of transforms, and a Viewer object with the given Canvas3D.
      Parameters:
        `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
        `transformCount` - the number of transforms in the MultiTransformGroup object to be created
      See Also:
        `SimpleUniverse.SimpleUniverse(Canvas3D, int)`, `Locale`, `Viewer`, `ViewingPlatform`, `MultiTransformGroup`

    - #### ConfiguredUniverse

          public ConfiguredUniverse(ViewingPlatform viewingPlatform,
                            Viewer viewer)

      Equivalent to `SimpleUniverse(ViewingPlatform, Viewer)`. Creates the view side of the scene graph with the given ViewingPlatform and Viewer.
      Parameters:
        `viewingPlatform` - the viewingPlatform to use to create the view side of the scene graph
        `viewer` - the viewer object to use to create the view side of the scene graph
      See Also:
        `SimpleUniverse.SimpleUniverse(ViewingPlatform, Viewer)`, `ViewingPlatform`, `Viewer`

    - #### ConfiguredUniverse

          public ConfiguredUniverse(ViewingPlatform viewingPlatform,
                            Viewer viewer,
                            LocaleFactory localeFactory)

      Equivalent to `SimpleUniverse(ViewingPlatform, Viewer, LocalFactory)`. Creates the view side of the scene graph with the given ViewingPlatform, Viewer, and Locale created by the specified LocaleFactory.
      Parameters:
        `viewingPlatform` - the viewingPlatform to use to create the view side of the scene graph
        `viewer` - the viewer object to use to create the view side of the scene graph
        `localeFactory` - the factory object used to create the Locale
      See Also:
        `SimpleUniverse.SimpleUniverse(ViewingPlatform, Viewer, LocaleFactory)`, `ViewingPlatform`, `Viewer`, `LocaleFactory`

    - #### ConfiguredUniverse

          public ConfiguredUniverse(Canvas3D[] canvases)

      Creates a Locale, a single ViewingPlatform, and a Viewer object from the given array of Canvas3D instances.
      Parameters:
        `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 Also:
        `Locale`, `Viewer`, `ViewingPlatform`

    - #### ConfiguredUniverse

          public ConfiguredUniverse(Canvas3D[] canvases,
                            int transformCount)

      Creates a Locale, a single ViewingPlatform with the specified number of transforms, and a Viewer object using the given array of Canvas3D instances.
      Parameters:
        `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
        `transformCount` - the number of transforms in the MultiTransformGroup object to be created
      See Also:
        `Locale`, `Viewer`, `ViewingPlatform`, `MultiTransformGroup`

    - #### ConfiguredUniverse

          public ConfiguredUniverse(Canvas3D[] canvases,
                            int transformCount,
                            LocaleFactory localeFactory)

      Creates a Locale, a single ViewingPlatform with the specified number of transforms, and a Viewer object using the given array of Canvas3D instances.
      Parameters:
        `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
        `transformCount` - the number of transforms in the MultiTransformGroup object to be created
        `localeFactory` - the factory object used to create the Locale
      Since:
        Java 3D 1.5.1
      See Also:
        `Locale`, `Viewer`, `ViewingPlatform`, `MultiTransformGroup`

    - #### ConfiguredUniverse

          public ConfiguredUniverse(java.net.URL userConfig)

      Reads the configuration specified by the given URL to create a Locale, one or more ViewingPlatforms, and at least one Viewer object. The configuration file may also create InputDevice, Sensor, and ViewPlatformBehavior instances.
      Parameters:
        `userConfig` - the URL to the user's configuration file; passing in null creates a default Viewer and ViewingPlatform
      See Also:
        `Locale`, `Viewer`, `ViewingPlatform`

    - #### ConfiguredUniverse

          public ConfiguredUniverse(java.net.URL userConfig,
                            int transformCount)

      Reads the configuration specified by the given URL to create a Locale, one or more ViewingPlatforms with the specified number of transforms, and at least one Viewer object. The configuration file may also create InputDevice, Sensor, and ViewPlatformBehavior instances.
      Parameters:
        `userConfig` - the URL to the user's configuration file; passing in null creates a default Viewer and ViewingPlatform with the specified number of transforms
        `transformCount` - the number of transforms in the MultiTransformGroup objects to be created
      See Also:
        `Locale`, `Viewer`, `ViewingPlatform`, `MultiTransformGroup`

    - #### ConfiguredUniverse

          public ConfiguredUniverse(java.net.URL userConfig,
                            int transformCount,
                            boolean setVisible)

      Reads the configuration specified by the given URL to create a Locale, one or more ViewingPlatforms with the specified number of transforms, and at least one Viewer object with optional visibility. AWT components used by the Viewers will remain invisible unless the `setVisible` flag is true. The configuration file may also create InputDevice, Sensor, and ViewPlatformBehavior instances.
      Parameters:
        `userConfig` - the URL to the user's configuration file; passing in null creates a default Viewer with the specified visibility and a ViewingPlatform with the specified number of transforms
        `transformCount` - the number of transforms in the MultiTransformGroup object to be created
        `setVisible` - if true, calls `setVisible(true)` on all created window components; otherwise, they remain invisible
      See Also:
        `Locale`, `Viewer`, `ViewingPlatform`, `MultiTransformGroup`

    - #### ConfiguredUniverse

          public ConfiguredUniverse(java.net.URL userConfig,
                            LocaleFactory localeFactory)

      Reads the configuration specified by the given URL to create a Locale using the given LocaleFactory, one or more ViewingPlatforms, and at least one Viewer object. The configuration file may also create InputDevice, Sensor, and ViewPlatformBehavior instances.
      Parameters:
        `userConfig` - the URL to the user's configuration file; passing in null creates a default Viewer and ViewingPlatform with the specified number of transforms
        `localeFactory` - the factory object used to create the Locale
      See Also:
        `Locale`, `Viewer`, `ViewingPlatform`

    - #### ConfiguredUniverse

          public ConfiguredUniverse(java.net.URL userConfig,
                            LocaleFactory localeFactory,
                            boolean setVisible)

      Reads the configuration specified by the given URL to create a Locale using the given LocaleFactory, one or more ViewingPlatforms, and at least one Viewer object with optional visibility. The configuration file may also create InputDevice, Sensor, and ViewPlatformBehavior instances. Window components used by the Viewers will remain invisible unless the `setVisible` flag is true.
      Parameters:
        `userConfig` - the URL to the user's configuration file; passing in null creates a default Viewer with the specified visibility and a default ViewingPlatform
        `localeFactory` - the factory object used to create the Locale
        `setVisible` - if true, calls `setVisible(true)` on all created window components; otherwise, they remain invisible
      See Also:
        `Locale`, `Viewer`, `ViewingPlatform`

    - #### ConfiguredUniverse

          public ConfiguredUniverse(java.net.URL userConfig,
                            LocaleFactory localeFactory,
                            HiResCoord origin,
                            int transformCount,
                            boolean setVisible)

      Reads the configuration specified by the given URL to create a Locale using the specified LocaleFactory with the given origin, one or more ViewingPlatforms with the specified number of transforms, and at least one Viewer object with optional visibility. Window components used by the Viewers will remain invisible unless the `setVisible` flag is true. The configuration file may also create InputDevice, Sensor, and ViewPlatformBehavior instances.
      Parameters:
        `userConfig` - the URL to the user's configuration file; passing in null creates a default Viewer with the specified visibility and a ViewingPlatform with the specified number of transforms
        `localeFactory` - the factory object used to create the Locale
        `origin` - the origin used to set the origin of the Locale object; if this object is null, then 0.0 is used
        `transformCount` - the number of transforms in the MultiTransformGroup object to be created
        `setVisible` - if true, calls `setVisible(true)` on all created window components; otherwise, they remain invisible
      See Also:
        `Locale`, `Viewer`, `ViewingPlatform`, `MultiTransformGroup`

    - #### ConfiguredUniverse

          public ConfiguredUniverse(ConfigContainer userConfig)

      Retrieves view-side scenegraph components from the given container to create a universe with one Locale, one or more ViewingPlatforms, and at least one Viewer object. Equivalent to `ConfiguredUniverse(ConfigContainer, null, null)`.
      Parameters:
        `userConfig` - container holding viewing configuration components; must not be null
      Since:
        Java 3D 1.3.1
      See Also:
        `ConfiguredUniverse(ConfigContainer, LocaleFactory, HiResCoord)`, `Locale`, `Viewer`, `ViewingPlatform`

    - #### ConfiguredUniverse

          public ConfiguredUniverse(ConfigContainer userConfig,
                            LocaleFactory localeFactory,
                            HiResCoord origin)

      Retrieves view-side scenegraph components from the given container to create a universe with one Locale created from the specified LocaleFactory and origin, one or more ViewingPlatforms, and at least one Viewer object. The container may also provide InputDevice, Sensor, and ViewPlatformBehavior instances which will be incorporated into the universe if they are referenced by any of the Viewer or ViewingPlatform instances.

      This constructor and `ConfiguredUniverse(ConfigContainer)` both accept ConfigContainer references directly and are the preferred interfaces for constructing universes from configuration files. They differ from the constructors that accept URL objects in the following ways:

      - A Viewer will be attached to a default ViewingPlatform only if no ViewingPlatforms are provided in the ConfigContainer. If one or more ViewingPlatforms are provided by the ConfigContainer, then Viewers must be attached to them explicitly in the configuration.

      - ViewPlatformBehaviors will be attached to their specified ViewingPlatforms before ConfiguredUniverse can set a reference to itself in the ViewingPlatform. This means that a behavior can't get a reference to the universe at the time its `setViewingPlatform` method is called; it must wait until its `initialize` method is called.

      - All Java properties used by Java 3D may be set in the beginning of the configuration file as long as there is no reference to a VirtualUniverse prior to creating the ConfigContainer. Note however, that some Java 3D utilities and objects such as Transform3D can cause static references to VirtualUniverse and trigger the evaluation of Java properties before they are set by ConfigContainer.

      Parameters:
        `userConfig` - container holding viewing configuration components; must not be null
        `localeFactory` - the factory object used to create the Locale, or null
        `origin` - the origin used to set the origin of the Locale object; if this object is null, then 0.0 is used
      Since:
        Java 3D 1.3.1
      See Also:
        `Locale`, `Viewer`, `ViewingPlatform`

  - ### Method Detail

    - #### getViewer

          public Viewer getViewer(int index)

      Returns the Viewer object specified by the given index.
      Parameters:
        `index` - The index of which Viewer object to return.
      Returns:
        The Viewer object specified by the given index.

    - #### getViewers

          public Viewer[] getViewers()

      Returns all of the Viewer objects associated with this scene graph.
      Returns:
        The Viewer objects associated with this scene graph.

    - #### setVisible

          public void setVisible(boolean visible)

      Call `setVisible()` on all AWT components created by this ConfiguredUniverse instance.

      Parameters:
        `visible` - boolean to be passed to the `setVisible()` calls on the window components created by this ConfiguredUniverse instance

    - #### getConfigURL

          public static java.net.URL getConfigURL()

      Returns the config file URL based on system properties. This is equivalent to calling `ConfigContainer.getConfigURL()`. The current implementation of this method parses the j3d.configURL property as a URL string. For example, the following command line would specify that the config file is taken from the file "j3dconfig" in the current directory:
      `java -Dj3d.configURL=file:j3dconfig ...`
      Returns:
        the URL of the config file; null is returned if no valid URL is defined by the system properties

    - #### getConfigURL

          public static java.net.URL getConfigURL(java.lang.String defaultURLString)

      Returns the config file URL based on system properties. This is the same as calling `ConfigContainer.getConfigURL(String)`. The current implementation of this method parses the j3d.configURL property as a URL string. For example, the following command line would specify that the config file is taken from the file "j3dconfig" in the current directory:
      `java -Dj3d.configURL=file:j3dconfig ...`
      Parameters:
        `defaultURLString` - the default string used to construct the URL if the appropriate system properties are not defined
      Returns:
        the URL of the config file; null is returned if no valid URL is defined either by the system properties or the default URL string

    - #### getNamedSensors

          public java.util.Map getNamedSensors()

      Returns all named Sensors defined by the configuration file used to create the ConfiguredUniverse, if any. Equivalent to `getConfigContainer().getNamedSensors()`.

      With the sole exception of the Sensor assigned to the head tracker, none of the Sensors defined in the configuration file are placed into the Sensor array maintained by PhysicalEnvironment. The head tracker Sensor is the only one read by the Java 3D core and must generate reads with a full 6 degrees of freedom (3D position and 3D orientation).

      Other Sensors need not generate reads with a full 6 degrees of freedom, although their reads must be expressed using Transform3D. Some joysticks may provide only 2D relative X and Y axis movement; dials, levers, and sliders are 1D devices, and some devices may combine dials and levers to generate 3D positional data.

      The index names to identify left / right / dominant / non-dominant hand Sensors in the PhysicalEnvironement Sensor array are not adequate to distinguish these differences, so this method allows applications to look up Sensors based on the names bound to them in the configuration file. There are no set rules on naming. Applications that use Sensors may set up conventions for generic devices such as "mouse6D" or "joystick2D" or specific product names.

      Returns:
        read-only Map which maps Sensor names to the associated Sensors, or null if no Sensors have been named

    - #### getNamedBehaviors

          public java.util.Map getNamedBehaviors()

      Returns all named ViewPlatformBehaviors defined by the configuration file used to create the ConfiguredUniverse, if any. Equivalent to `getConfigContainer().getNamedViewPlatformBehaviors()`.

      Returns:
        read-only Map which maps behavior names to the associated ViewPlatformBehavior instances, or null if none have been named.
      Since:
        Java 3D 1.3.1

    - #### getConfigContainer

          public ConfigContainer getConfigContainer()

      Returns a container holding all the objects defined by the configuration file used to create the ConfiguredUniverse.
      Returns:
        the container
      Since:
        Java 3D 1.3.1

    - #### cleanup

          public void cleanup()

      Cleanup memory references used by ConfiguredUniverse.
      Overrides:
        `cleanup` in class `SimpleUniverse`
      Since:
        Java 3D 1.3.1

Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.