com.sun.j3d.utils.universe
Class ConfiguredUniverse

java.lang.Object
  extended by javax.media.j3d.VirtualUniverse
      extended by com.sun.j3d.utils.universe.SimpleUniverse
          extended by 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
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 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
 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
getAllLocales, getJ3DThreadPriority, getProperties, numLocales, removeAllLocales, removeLocale, 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(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:

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:

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:

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