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 Description ConfiguredUniverse()
Equivalent toSimpleUniverse()
.ConfiguredUniverse(int transformCount)
Equivalent toSimpleUniverse(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(ViewingPlatform viewingPlatform, Viewer viewer)
Equivalent toSimpleUniverse(ViewingPlatform, Viewer)
.ConfiguredUniverse(ViewingPlatform viewingPlatform, Viewer viewer, LocaleFactory localeFactory)
Equivalent toSimpleUniverse(ViewingPlatform, Viewer, LocalFactory)
.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(Canvas3D canvas)
Equivalent toSimpleUniverse(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 toSimpleUniverse(Canvas3D, int)
.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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)
CallsetVisible()
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
-
-
-
-
Constructor Detail
-
ConfiguredUniverse
public ConfiguredUniverse()
Equivalent toSimpleUniverse()
. Creates a Locale, a single ViewingPlatform, and a Viewer object.- See Also:
SimpleUniverse()
,Locale
,Viewer
,ViewingPlatform
-
ConfiguredUniverse
public ConfiguredUniverse(int transformCount)
Equivalent toSimpleUniverse(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(int)
,Locale
,Viewer
,ViewingPlatform
,MultiTransformGroup
-
ConfiguredUniverse
public ConfiguredUniverse(Canvas3D canvas)
Equivalent toSimpleUniverse(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(Canvas3D)
,Locale
,Viewer
,ViewingPlatform
-
ConfiguredUniverse
public ConfiguredUniverse(Canvas3D canvas, int transformCount)
Equivalent toSimpleUniverse(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 utilitytransformCount
- the number of transforms in the MultiTransformGroup object to be created- See Also:
SimpleUniverse(Canvas3D, int)
,Locale
,Viewer
,ViewingPlatform
,MultiTransformGroup
-
ConfiguredUniverse
public ConfiguredUniverse(ViewingPlatform viewingPlatform, Viewer viewer)
Equivalent toSimpleUniverse(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 graphviewer
- the viewer object to use to create the view side of the scene graph- See Also:
SimpleUniverse(ViewingPlatform, Viewer)
,ViewingPlatform
,Viewer
-
ConfiguredUniverse
public ConfiguredUniverse(ViewingPlatform viewingPlatform, Viewer viewer, LocaleFactory localeFactory)
Equivalent toSimpleUniverse(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 graphviewer
- the viewer object to use to create the view side of the scene graphlocaleFactory
- the factory object used to create the Locale- See Also:
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 utilitytransformCount
- 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 utilitytransformCount
- the number of transforms in the MultiTransformGroup object to be createdlocaleFactory
- 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 transformstransformCount
- 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 thesetVisible
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 transformstransformCount
- the number of transforms in the MultiTransformGroup object to be createdsetVisible
- if true, callssetVisible(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 transformslocaleFactory
- 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 thesetVisible
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 ViewingPlatformlocaleFactory
- the factory object used to create the LocalesetVisible
- if true, callssetVisible(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 thesetVisible
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 transformslocaleFactory
- the factory object used to create the Localeorigin
- the origin used to set the origin of the Locale object; if this object is null, then 0.0 is usedtransformCount
- the number of transforms in the MultiTransformGroup object to be createdsetVisible
- if true, callssetVisible(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 toConfiguredUniverse(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 itsinitialize
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 nulllocaleFactory
- the factory object used to create the Locale, or nullorigin
- 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
- 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.
-
-
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)
CallsetVisible()
on all AWT components created by this ConfiguredUniverse instance.- Parameters:
visible
- boolean to be passed to thesetVisible()
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 callingConfigContainer.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 callingConfigContainer.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 togetConfigContainer().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 togetConfigContainer().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 classSimpleUniverse
- Since:
- Java 3D 1.3.1
-
-