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

Field Summary

Fields

Modifier and Type	Field and Description
(package private) int	activeViewCount
(package private) java.util.Vector	backgrounds
(package private) java.lang.Object	behaviorLock
(package private) BehaviorScheduler	behaviorScheduler
(package private) BehaviorStructure	behaviorStructure
(package private) java.util.Vector	clips
(package private) View	currentView
private static RenderingErrorListener	defaultRenderingErrorListener
private ShaderErrorListener	defaultShaderErrorListener
(package private) java.util.ArrayList	dirtyGeomList
(package private) boolean	enableComponent
(package private) boolean	enableFocus
(package private) boolean	enableKey
(package private) boolean	enableMouse
(package private) boolean	enableMouseMotion
(package private) boolean	enableMouseWheel
(package private) GeometryStructure	geometryStructure
(package private) boolean	inBehavior
(package private) boolean	isSceneGraphLock
(package private) java.util.Vector	listOfLocales
(package private) static MasterControl	mc
(package private) long	nodeIdCount
(package private) java.util.Vector	nodeIdFreeList
(package private) int	numNodes
private static J3dQueryProps	properties
(package private) View	regViewWaiting
(package private) RenderingEnvironmentStructure	renderingEnvironmentStructure
(package private) int	renderingEnvironmentStructureRefCount
private static java.util.HashSet<RenderingErrorListener>	renderingErrorListenerSet
(package private) static java.lang.ThreadGroup	rootThreadGroup
(package private) java.lang.Object	sceneGraphLock
(package private) SetLiveState	setLiveState
private java.util.HashSet<ShaderErrorListener>	shaderErrorListenerSet
(package private) java.util.Vector	sounds
(package private) java.util.Vector	soundscapes
(package private) SoundStructure	soundStructure
private java.util.HashSet<GraphStructureChangeListener>	structureChangeListenerSet
(package private) TransformStructure	transformStructure
(package private) View	unRegViewWaiting
(package private) ObjectUpdate[]	updateObjects
(package private) int	updateObjectsLen
(package private) int	viewIdCount
(package private) java.util.ArrayList	viewIdFreeList
(package private) java.lang.Object[]	viewPlatformList
(package private) java.util.ArrayList	viewPlatforms
(package private) boolean	vpChanged
private java.lang.Object	waitLock

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.
(package private) void	addLocale(Locale locale) Adds a locale at the end of list of locales
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.
(package private) void	addViewIdToFreeList(java.lang.Integer viewId) This returns a viewId to the freelist
(package private) void	addViewPlatform(ViewPlatformRetained vp)
(package private) void	checkForEnableEvents()
(package private) void	disableFocusEvents()
(package private) void	disableKeyEvents()
(package private) void	disableMouseEvents()
(package private) void	disableMouseMotionEvents()
(package private) void	disableMouseWheelEvents()
(package private) void	enableComponentEvents()
(package private) void	enableFocusEvents()
(package private) void	enableKeyEvents()
(package private) void	enableMouseEvents()
(package private) void	enableMouseMotionEvents()
(package private) void	enableMouseWheelEvents()
java.util.Enumeration	getAllLocales() Returns the enumeration object of all locales in this virtual universe.
(package private) View	getCurrentView() Returns the "current" view (the last view activated for this virtual universe.
static int	getJ3DThreadPriority() Retrieves that priority of Java 3D's threads.
(package private) java.lang.String	getNodeId() This returns the next available nodeId as a string.
static java.util.Map	getProperties() Returns a read-only Map object containing key-value pairs that define various global properties for Java 3D.
(package private) static java.lang.ThreadGroup	getRootThreadGroup() Method to return the root thread group.
(package private) java.lang.Integer	getViewId() This returns the next available viewId
(package private) java.lang.Object[]	getViewPlatformList()
(package private) void	initMCStructure()
(package private) boolean	isEmpty() return true if all Locales under it don't have branchGroup attach to it.
(package private) static void	loadLibraries() Initialize the native interface and anything else that needs to be initialized.
(package private) static void	notifyRenderingErrorListeners(RenderingError error) Notifies all listeners of a rendering error.
(package private) void	notifyShaderErrorListeners(ShaderError error) Notifies all listeners of a shader error.
(package private) void	notifyStructureChangeListeners(boolean add, java.lang.Object parent, BranchGroup child) Processes all live BranchGroup add and removes and notifies any registered listeners.
(package private) void	notifyStructureChangeListeners(java.lang.Object oldParent, java.lang.Object newParent, BranchGroup child) Processes all live BranchGroup moves and notifies any registered listeners.
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.
(package private) void	removeViewPlatform(ViewPlatformRetained vp)
(package private) void	resetWaitMCFlag()
(package private) void	setCurrentView(View view) Sets the "current" view (during view activation) for this virtual universe.
static void	setJ3DThreadPriority(int priority) Sets the priority of all Java 3D threads to the specified value.
(package private) void	waitForMC()

Methods inherited from class java.lang.Object

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

Field Detail

mc

static MasterControl mc

sceneGraphLock

java.lang.Object sceneGraphLock

behaviorLock

java.lang.Object behaviorLock

listOfLocales

java.util.Vector listOfLocales

viewPlatforms

java.util.ArrayList viewPlatforms

viewPlatformList

java.lang.Object[] viewPlatformList

vpChanged

boolean vpChanged

backgrounds

java.util.Vector backgrounds

clips

java.util.Vector clips

sounds

java.util.Vector sounds

soundscapes

java.util.Vector soundscapes

behaviorScheduler

BehaviorScheduler behaviorScheduler

geometryStructure

GeometryStructure geometryStructure

transformStructure

TransformStructure transformStructure

behaviorStructure

BehaviorStructure behaviorStructure

soundStructure

SoundStructure soundStructure

renderingEnvironmentStructure

RenderingEnvironmentStructure renderingEnvironmentStructure

renderingEnvironmentStructureRefCount

int renderingEnvironmentStructureRefCount

nodeIdCount

long nodeIdCount

viewIdCount

int viewIdCount

nodeIdFreeList

java.util.Vector nodeIdFreeList

viewIdFreeList

java.util.ArrayList viewIdFreeList

numNodes

int numNodes

setLiveState

SetLiveState setLiveState

updateObjects

ObjectUpdate[] updateObjects

updateObjectsLen

int updateObjectsLen

dirtyGeomList

java.util.ArrayList dirtyGeomList

currentView

View currentView

inBehavior

boolean inBehavior

enableComponent

boolean enableComponent

enableFocus

boolean enableFocus

enableKey

boolean enableKey

enableMouse

boolean enableMouse

enableMouseMotion

boolean enableMouseMotion

enableMouseWheel

boolean enableMouseWheel

activeViewCount

int activeViewCount

rootThreadGroup

static java.lang.ThreadGroup rootThreadGroup

properties

private static J3dQueryProps properties

regViewWaiting

View regViewWaiting

unRegViewWaiting

View unRegViewWaiting

isSceneGraphLock

boolean isSceneGraphLock

waitLock

private java.lang.Object waitLock

structureChangeListenerSet

private java.util.HashSet<GraphStructureChangeListener> structureChangeListenerSet

shaderErrorListenerSet

private java.util.HashSet<ShaderErrorListener> shaderErrorListenerSet

defaultShaderErrorListener

private ShaderErrorListener defaultShaderErrorListener

renderingErrorListenerSet

private static java.util.HashSet<RenderingErrorListener> renderingErrorListenerSet

defaultRenderingErrorListener

private static RenderingErrorListener defaultRenderingErrorListener

Constructor Detail

VirtualUniverse

public VirtualUniverse()

Constructs a new VirtualUniverse.

Method Detail

initMCStructure

void initMCStructure()

loadLibraries

static void loadLibraries()

Initialize the native interface and anything else that needs to be initialized.

addLocale

void addLocale(Locale locale)

Adds a locale at the end of list of locales

Parameters:

locale - the locale to be added

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

getNodeId

java.lang.String getNodeId()

This returns the next available nodeId as a string.

getViewId

java.lang.Integer getViewId()

This returns the next available viewId

addViewIdToFreeList

void addViewIdToFreeList(java.lang.Integer viewId)

This returns a viewId to the freelist

addViewPlatform

void addViewPlatform(ViewPlatformRetained vp)

removeViewPlatform

void removeViewPlatform(ViewPlatformRetained vp)

getViewPlatformList

java.lang.Object[] getViewPlatformList()

checkForEnableEvents

void checkForEnableEvents()

enableComponentEvents

void enableComponentEvents()

disableFocusEvents

void disableFocusEvents()

enableFocusEvents

void enableFocusEvents()

disableKeyEvents

void disableKeyEvents()

enableKeyEvents

void enableKeyEvents()

disableMouseEvents

void disableMouseEvents()

enableMouseEvents

void enableMouseEvents()

disableMouseMotionEvents

void disableMouseMotionEvents()

enableMouseMotionEvents

void enableMouseMotionEvents()

disableMouseWheelEvents

void disableMouseWheelEvents()

enableMouseWheelEvents

void enableMouseWheelEvents()

setCurrentView

final void setCurrentView(View view)

Sets the "current" view (during view activation) for this virtual universe.

Parameters:

last - activated view

getCurrentView

final View getCurrentView()

Returns the "current" view (the last view activated for this virtual universe.

Returns:

last activated view

getRootThreadGroup

static java.lang.ThreadGroup getRootThreadGroup()

Method to return the root thread group. This must be called from within a doPrivileged block.

isEmpty

boolean isEmpty()

return true if all Locales under it don't have branchGroup attach to it.

resetWaitMCFlag

void resetWaitMCFlag()

waitForMC

void waitForMC()

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

notifyStructureChangeListeners

void notifyStructureChangeListeners(boolean add,
                                  java.lang.Object parent,
                                  BranchGroup child)

Processes all live BranchGroup add and removes and notifies any registered listeners. Used for add and remove

notifyStructureChangeListeners

void notifyStructureChangeListeners(java.lang.Object oldParent,
                                  java.lang.Object newParent,
                                  BranchGroup child)

Processes all live BranchGroup moves and notifies any registered listeners. Used for moveTo

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

notifyShaderErrorListeners

void notifyShaderErrorListeners(ShaderError error)

Notifies all listeners of a shader error. If no listeners exist, a default listener is notified.

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

notifyRenderingErrorListeners

static void notifyRenderingErrorListeners(RenderingError error)

Notifies all listeners of a rendering error. If no listeners exist, a default listener is notified.