javax.media.j3d

## Class VirtualUniverse

- java.lang.Object
- - javax.media.j3d.VirtualUniverse

- Direct Known Subclasses:
    SimpleUniverse

      public class VirtualUniverse
      extends java.lang.Object

  A VirtualUniverse object is the top-level container for all scene graphs. A virtual universe consists of a set of Locale objects, each of which has a high-resolution position within the virtual universe. An application or applet may have more than one VirtualUniverse objects, but many applications will need only one. Virtual universes are separate entities in that no node object may exist in more than one virtual universe at any one time. Likewise, the objects in one virtual universe are not visible in, nor do they interact with objects in, any other virtual universe.

  A VirtualUniverse object defines methods to enumerate its Locale objects and to remove them from the virtual universe.

  For more information, see the Introduction to the Java 3D API and Scene Graph Superstructure documents.

  See Also:
    `Locale`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `VirtualUniverse()` Constructs a new VirtualUniverse.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addGraphStructureChangeListener(GraphStructureChangeListener listener)` Adds the specified GraphStructureChangeListener to the set of listeners that will be notified when the graph structure is changed on a live scene graph.
    `static void` | `addRenderingErrorListener(RenderingErrorListener listener)` Adds the specified RenderingErrorListener to the set of listeners that will be notified when a rendering error is detected.
    `void` | `addShaderErrorListener(ShaderErrorListener listener)` Adds the specified ShaderErrorListener to the set of listeners that will be notified when a programmable shader error is detected on a live scene graph.
    `java.util.Enumeration` | `getAllLocales()` Returns the enumeration object of all locales in this virtual universe.
    `static int` | `getJ3DThreadPriority()` Retrieves that priority of Java 3D's threads.
    `static java.util.Map` | `getProperties()` Returns a read-only Map object containing key-value pairs that define various global properties for Java 3D.
    `int` | `numLocales()` Returns the number of locales.
    `void` | `removeAllLocales()` Removes all Locales and their associates branch graphs from this universe.
    `void` | `removeGraphStructureChangeListener(GraphStructureChangeListener listener)` Removes the specified GraphStructureChangeListener from the set of listeners.
    `void` | `removeLocale(Locale locale)` Removes a Locale and its associates branch graphs from this universe.
    `static void` | `removeRenderingErrorListener(RenderingErrorListener listener)` Removes the specified RenderingErrorListener from the set of listeners.
    `void` | `removeShaderErrorListener(ShaderErrorListener listener)` Removes the specified ShaderErrorListener from the set of listeners.
    `static void` | `setJ3DThreadPriority(int priority)` Sets the priority of all Java 3D threads to the specified value.

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

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

- - ### Constructor Detail

    - #### VirtualUniverse

          public VirtualUniverse()

      Constructs a new VirtualUniverse.

  - ### Method Detail

    - #### removeLocale

          public void removeLocale(Locale locale)

      Removes a Locale and its associates branch graphs from this universe. All branch graphs within the specified Locale are detached, regardless of whether their ALLOW_DETACH capability bits are set. The Locale is then marked as being dead: no branch graphs may subsequently be attached.
      Parameters:
        `locale` - the Locale to be removed.
      Throws:
        `java.lang.IllegalArgumentException` - if the specified Locale is not attached to this VirtualUniverse.
      Since:
        Java 3D 1.2

    - #### removeAllLocales

          public void removeAllLocales()

      Removes all Locales and their associates branch graphs from this universe. All branch graphs within each Locale are detached, regardless of whether their ALLOW_DETACH capability bits are set. Each Locale is then marked as being dead: no branch graphs may subsequently be attached. This method should be called by applications and applets to allow Java 3D to cleanup its resources.
      Since:
        Java 3D 1.2

    - #### getAllLocales

          public java.util.Enumeration getAllLocales()

      Returns the enumeration object of all locales in this virtual universe.
      Returns:
        the enumeration object

    - #### numLocales

          public int numLocales()

      Returns the number of locales.
      Returns:
        the count of locales

    - #### setJ3DThreadPriority

          public static void setJ3DThreadPriority(int priority)

      Sets the priority of all Java 3D threads to the specified value. The default value is the priority of the thread that started Java 3D.
      Parameters:
        `priority` - the new thread priority
      Throws:
        `java.lang.IllegalArgumentException` - if the priority is not in the range MIN_PRIORITY to MAX_PRIORITY
        `java.lang.SecurityException` - if the priority is greater than that of the calling thread
      Since:
        Java 3D 1.2

    - #### getJ3DThreadPriority

          public static int getJ3DThreadPriority()

      Retrieves that priority of Java 3D's threads.
      Returns:
        the current priority of Java 3D's threads
      Since:
        Java 3D 1.2

    - #### getProperties

          public static final java.util.Map getProperties()

      Returns a read-only Map object containing key-value pairs that define various global properties for Java 3D. All of the keys are String objects. The values are key-specific, but most will be String objects.

      The set of global Java 3D properties always includes values for the following keys:

      Key (String) | Value Type
      `j3d.version` | String
      `j3d.vendor` | String
      `j3d.specification.version` | String
      `j3d.specification.vendor` | String
      `j3d.pipeline` | String
      `j3d.renderer` | String

      The descriptions of the values returned for each key are as follows:

      - `j3d.version`
        A String that defines the Java 3D implementation version. The portion of the implementation version string before the first space must adhere to one of the the following three formats (anything after the first space is an optional free-form addendum to the version):
        x.y.z
        x.y.z_p
        x.y.z-ssss
        where:
        x is the major version number
        y is the minor version number
        z is the sub-minor version number
        p is the patch revision number
        ssss is a string, identifying a non-release build (e.g., beta1, build47, rc1, etc.). It may only contain letters, numbers, periods, dashes, or underscores.

      - `j3d.vendor`
        String that specifies the Java 3D implementation vendor.

      - `j3d.specification.version`
        A String that defines the Java 3D specification version. This string must be of the following form:
        x.y
        where:
        x is the major version number
        y is the minor version number
        No other characters are allowed in the specification version string.

      - `j3d.specification.vendor`
        String that specifies the Java 3D specification vendor.

      - `j3d.pipeline`
        String that specifies the Java 3D rendering pipeline. This could be one of: "NATIVE_OGL", "NATIVE_D3D", or "JOGL". Others could be added in the future.

      - `j3d.renderer`
        String that specifies the underlying rendering library. This could be one of: "OpenGL" or "DirectX". Others could be added in the future.

      Returns:
        the global Java 3D properties
      Since:
        Java 3D 1.3

    - #### addGraphStructureChangeListener

          public void addGraphStructureChangeListener(GraphStructureChangeListener listener)

      Adds the specified GraphStructureChangeListener to the set of listeners that will be notified when the graph structure is changed on a live scene graph. If the specifed listener is null no action is taken and no exception is thrown.
      Parameters:
        `listener` - the listener to add to the set.
      Since:
        Java 3D 1.4

    - #### removeGraphStructureChangeListener

          public void removeGraphStructureChangeListener(GraphStructureChangeListener listener)

      Removes the specified GraphStructureChangeListener from the set of listeners. This method performs no function, nor does it throw an exception if the specified listener is not currently in the set or is null.
      Parameters:
        `listener` - the listener to remove from the set.
      Since:
        Java 3D 1.4

    - #### addShaderErrorListener

          public void addShaderErrorListener(ShaderErrorListener listener)

      Adds the specified ShaderErrorListener to the set of listeners that will be notified when a programmable shader error is detected on a live scene graph. If the specifed listener is null no action is taken and no exception is thrown. If a shader error occurs, the listeners will be called asynchronously from a separate notification thread. The Java 3D renderer and behavior scheduler will continue to run as if the error had not occurred, except that shading will be disabled for the objects in error. If applications desire to detach or modify the scene graph as a result of the error, they should use a behavior post if they want that change to be synchronous with the renderer.
      Parameters:
        `listener` - the listener to add to the set.
      Since:
        Java 3D 1.4

    - #### removeShaderErrorListener

          public void removeShaderErrorListener(ShaderErrorListener listener)

      Removes the specified ShaderErrorListener from the set of listeners. This method performs no function, nor does it throw an exception if the specified listener is not currently in the set or is null.
      Parameters:
        `listener` - the listener to remove from the set.
      Since:
        Java 3D 1.4

    - #### addRenderingErrorListener

          public static void addRenderingErrorListener(RenderingErrorListener listener)

      Adds the specified RenderingErrorListener to the set of listeners that will be notified when a rendering error is detected. If the specifed listener is null no action is taken and no exception is thrown. If a rendering error occurs, the listeners will be called asynchronously from a separate notification thread. If the set of listeners is empty, a default listener is notified. The default listener prints the error information to System.err and then calls System.exit().
      Parameters:
        `listener` - the listener to add to the set.
      Since:
        Java 3D 1.5

    - #### removeRenderingErrorListener

          public static void removeRenderingErrorListener(RenderingErrorListener listener)

      Removes the specified RenderingErrorListener from the set of listeners. This method performs no function, nor does it throw an exception if the specified listener is not currently in the set or is null.
      Parameters:
        `listener` - the listener to remove from the set.
      Since:
        Java 3D 1.5

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