javax.media.ding3d.utils.universe
Class ConfiguredUniverse

java.lang.Object
  javax.media.ding3d.VirtualUniverse
      javax.media.ding3d.utils.universe.SimpleUniverse
          javax.media.ding3d.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

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[] 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

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 javax.media.ding3d.utils.universe.SimpleUniverse

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

Methods inherited from class javax.media.ding3d.VirtualUniverse

addGraphStructureChangeListener, addRenderingErrorListener, addShaderErrorListener, getAllLocales, getDing3dThreadPriority, getProperties, numLocales, removeAllLocales, removeGraphStructureChangeListener, removeLocale, removeRenderingErrorListener, removeShaderErrorListener, setDing3dThreadPriority

Methods inherited from class java.lang.Object

equals, 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 Ding3d.configURL property as a URL string. For example, the following command line would specify that the config file is taken from the file "Ding3dconfig" in the current directory:

java -DDing3d.configURL=file:Ding3dconfig ...

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 Ding3d.configURL property as a URL string. For example, the following command line would specify that the config file is taken from the file "Ding3dconfig" in the current directory:

java -DDing3d.configURL=file:Ding3dconfig ...

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