: Class Sound

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.media.j3d
Class Sound

    java.lang.Object
      |
      +--javax.media.j3d.SceneGraphObject
            |
            +--javax.media.j3d.Node
                  |
                  +--javax.media.j3d.Leaf
                        |
                        +--javax.media.j3d.Sound

Direct Known Subclasses:
  BackgroundSound, PointSound

public abstract class Sound
extends Leaf

Sound node is an abstract class that defines the properties common to all sound sources. A scene graph can contain multiple sounds. Associated with each sound source are: a reference to sound data, an amplitude scale factor, a release flag denoting that the sound associated with this node is to play to end when it is disabled, the number of times sound is to be repeated, the sound's state (on or off), a scheduling region, and flag denoting if the sound is to continue playing "silently" even while it is inactive. Whenever the listener is within a sound node's scheduling bounds this sound is potentially audible.

Sound Data

Associated with each Sound node is a MediaContainer which includes audio data and information about this data. This data can be cached (buffered) or non-cached (unbuffered or streaming). If an AudioDevice has been attached to the PhysicalEnvironment the sound data is made ready to begin playing. Certain functionality can not be applied to true streaming sound data: 1) querying the sound's duration (Sound.DURATION_UNKNOWN will be returned), 2) looping over a range of the streaming data; and 3) restart a previously played portion of the data; Depending on the implementation of the AudioDevice used, streamed, non- cached data may not be fully spatialized.

Initial Gain

This gain is a scale factor that is applied to the sound data associated with this sound source to increase or decrease its overall amplitude.

Loop

Data for non-streaming sound (such as a sound sample) can contain two loop points marking a section of the data that is to be looped specific number of times. Thus sound data can be divided into three segments: the attack (before the begin loop point), the sustain (between the begin and end loop points), and the release (after the end loop point). If there are no loop begin and end points defined as part of the sound data then the begin loop point is set at the beginning of the sound data, and the end loop point at the end of the sound data. If this is the case, looping the sound would mean repeating the whole sound. However, these allowing a portion in the middle of the sound to be looped.

A sound can be looped a specified number of times after it is activated before it is completed. The loop count value explicitly sets the number of times the sound is looped. Any non-negative number is a valid value. A value of zero denotes that the looped section is not repeated, but is played only once. A value of -1 denotes that the loop is repeated indefinitely.

Changing loop count of a sound after the sound has been started will not dynamically affect the loop count currently used by the sound playing. The new loop count will be used the next time the sound is enabled.

Release Flag

When a sound is disabled, its playback would normally stop immediately no matter what part of the sound data was currently being played. By setting the Release Flag to true for nodes with non-streaming sound data, the sound is allowed to play from its current position in the sound data to the end of the data (without repeats) thus playing the release portion of the sound before stopping.

Continuous Flag

For some applications, it's useful to turn a sound source "off" but to continue "silently" playing the sound so that when it is turned back "on" the sound picks up playing in the same location (over time) as it would have been if the sound had never been disabled (turned off). Setting the Continuous flag true causes the sound renderer to keep track of where (over time) the sound would be playing even when the sound is disabled.

Enable Sound

When enabled, the sound source is started playing and thus can potentially be heard, depending on its activation state, gain control parameters, continuation state, and spatiallization parameters. If the continuous state is true, even if the sound is not active, enabling the sound starts the sound silently "playing," so that when the sound is activated, the sound is (potentially) heard from somewhere in the middle of the sound data. Activation state can change from active to inactive any number of times without stopping or starting the sound. To re-start a sound at the beginning of its data, re-enable the sound by calling setEnable with true.

Setting the enable flag to true during construction will act as a request to start the sound playing "as soon as it can" be started. This could be close to immediately in limited cases, but several conditions, detailed below, must be meet for a sound to be ready to be played.

Scheduling Bounds

A Sound is scheduled for activation when its scheduling region intersects the ViewPlatform's activation volume. This is used when the scheduling bounding leaf is set to null.

Scheduling Bounding Leaf

When set to a value other than null, this scheduling bounding leaf region overrides the scheduling bounds object.

Prioritize Sound

Sound Priority is used to rank concurrently playing sounds in order of importance during playback. When more sounds are started than the AudioDevice can handle, the sound node with the lowest priority ranking is deactivated (but continues playing silently). If a sound is deactivated (due to a sound with a higher priority being started) it is automatically re-activated when resources becomes available (e.g., when a sound with a higher priority finishes playing), or when the ordering of sound nodes are changed due to a change in a sound nodes priority.

Sounds with a lower priority than sound that can not be played due to lack of channels will be played. For example, assume we have 8 channels available for playing sounds. After ordering four sounds, we begin playing them in order, checking if the number of channels required to play a given sound are actually available before the sound is played. Futhermore, say the first sound needs 3 channels to play, the second sound needs 4 channels, the third sound needs 3 channels and the fourth sound needs only 1 channel. The first and seconds sounds can be started because they require 7 of the 8 available channels. The third sound can not be audibly started because it requires 3 channels and only 1 is still available. Consequently, the third sound is starts playing 'silently'. The fourth sound can and will be started since it only requires 1 channel. The third sound will be made audible when 3 channels become available (ie, when the first or second sound finished playing).

Sound given the same priority are order randomly. If the application wants a specific ordering it must assign unique priorities to each sound.

Methods to determine what audio output resources are required for playing a Sound node on a particular AudioDevice and to determine the currently available audio output resources are described in AudioDevice class.

Duration

Each sound has a length of time in millisecond that it can run (including repeating loop section) if it plays to completion. If the sound media type is streaming, or if the sound is looped indefinitely, then a value of -1 (implying infinite length) is returned.

Number of Channels used on Audio Device to Play Sound

When a sound is started it could use more than one channel on the selected AudioDevice it is to be played on. The number of Audio Device channels currently used for a sound can be queried using getNumberOfChannelsUsed().

Preparing a Sound to be Played Sound data associated with a Sound node, either during construction (when the MediaContainer is passed into the constructor as a parameter) or by calling setSoundData(), it can be prepared to begin playing only after the following conditions are satisfied: 1) the Sound node has non-null sound data associated with it; 2) the Sound node is live; 3) there is an active View in the Universe; and 4) there is an initialized AudioDevice associated with the PhysicalEnvironment. Depending on the type of MediaContainer the sound data is and on the implementation of the AudioDevice used, sound data preparation could consist of opening, attaching, loading or copying into memory the associated sound data. The query method, isReady() returns true when the sound is fully preprocessed so that it is playable (audibly if active, silently if not active).

Playing Status

A sound source will not be heard unless it is both enabled/started and activated. While these conditions are meet, the sound is potentially audible and the method isPlaying() will return a status of true.

If a sound is enabled before it is activated it is begun playing silently. If a sound is enabled then deactived while playing it continues playing silently. In both of these cases isPlaying() returns false but the method isPlayingSilently() returns true.

When the sound finishes playing it sound data (including all loops) it is implicitly disabled.

Field Summary
`static int` | `ALLOW_CHANNELS_USED_READ` Specifies that this node allows access to its number of channels used by this sound.
`static int` | `ALLOW_CONT_PLAY_READ` Specifies that this node allows access to its object's continuous play information.
`static int` | `ALLOW_CONT_PLAY_WRITE` Specifies that this node allows writing to its object's continuous play information.
`static int` | `ALLOW_DURATION_READ` Specifies that this node allows access to its object's sound duration information.
`static int` | `ALLOW_ENABLE_READ` Specifies that this node allows access to its object's sound on information.
`static int` | `ALLOW_ENABLE_WRITE` Specifies that this node allows writing to its object's sound on information.
`static int` | `ALLOW_INITIAL_GAIN_READ` Specifies that this node allows access to its object's initial gain information.
`static int` | `ALLOW_INITIAL_GAIN_WRITE` Specifies that this node allows writing to its object's initial gain information.
`static int` | `ALLOW_IS_PLAYING_READ` Specifies that this node allows access to its object's sound audibly playing or playing silently status.
`static int` | `ALLOW_IS_READY_READ` Specifies that this node allows access to its object's sound status denoting if it is ready to be played 'immediately'.
`static int` | `ALLOW_LOOP_READ` Specifies that this node allows access to its object's loop information.
`static int` | `ALLOW_LOOP_WRITE` Specifies that this node allows writing to its object's loop information.
`static int` | `ALLOW_PRIORITY_READ` Specifies that this node allows read access to its priority order value.
`static int` | `ALLOW_PRIORITY_WRITE` Specifies that this node allows write access to its priority order value.
`static int` | `ALLOW_RELEASE_READ` Specifies that this node allows access to its object's release flag information.
`static int` | `ALLOW_RELEASE_WRITE` Specifies that this node allows writing to its object's release flag information.
`static int` | `ALLOW_SCHEDULING_BOUNDS_READ` Specifies that this node allows read access to its scheduling bounds information.
`static int` | `ALLOW_SCHEDULING_BOUNDS_WRITE` Specifies that this node allows write access to its scheduling bounds information.
`static int` | `ALLOW_SOUND_DATA_READ` Specifies that this node allows access to its object's sound data information.
`static int` | `ALLOW_SOUND_DATA_WRITE` Specifies that this node allows writing to its object's sound data information.
`static int` | `DURATION_UNKNOWN` Denotes that the sound's duration could not be calculated.
`static int` | `INFINITE_LOOPS` When used as a loop count sound will loop an infinite number of time until explicitly stopped (setEnabled(false)).
`static float` | `NO_FILTER` Denotes that there is no filter value associated with object's distance or angular attenuation array.

Fields inherited from class javax.media.j3d.Node
`ALLOW_AUTO_COMPUTE_BOUNDS_READ, ALLOW_AUTO_COMPUTE_BOUNDS_WRITE, ALLOW_BOUNDS_READ, ALLOW_BOUNDS_WRITE, ALLOW_COLLIDABLE_READ, ALLOW_COLLIDABLE_WRITE, ALLOW_LOCAL_TO_VWORLD_READ, ALLOW_PICK, ALLOW_PICKABLE_READ, ALLOW_PICKABLE_WRITE, ENABLE_COLLISION_REPORTING, ENABLE_PICK_REPORTING`

Constructor Summary
`Sound()` Constructs and initializes a new Sound node using default parameters.
`Sound(MediaContainer soundData, float initialGain)` Constructs and initializes a new Sound node object using the provided data and gain parameter values, and defaults for all other fields.
`Sound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority)` Constructs and initializes a new Sound node using provided parameter values.

Method Summary
`boolean` | `getContinuousEnable()` Retrieves sound's continuous play flag.
`long` | `getDuration()` Get the Sound's duration
`boolean` | `getEnable()` Retrieves sound's enabled flag.
`float` | `getInitialGain()` Get the overall gain applied to the sound data associated with source.
`int` | `getLoop()` Retrieves loop count for this sound
`int` | `getNumberOfChannelsUsed()` Retrieves number of channels (on executing audio device) that are being used this sound
`float` | `getPriority()` Retrieves sound's priority value.
`boolean` | `getReleaseEnable()` Retrieves release flag for sound associated with sound.
`BoundingLeaf` | `getSchedulingBoundingLeaf()` Retrieves the Sound node's scheduling bounding leaf.
`Bounds` | `getSchedulingBounds()` Retrieves the Sound node's scheduling bounds.
`MediaContainer` | `getSoundData()` Retrieves description/data associated with this sound source.
`boolean` | `isPlaying()` Retrieves sound's play status.
`boolean` | `isPlayingSilently()` Retrieves sound's silent status.
`boolean` | `isReady()` Retrieves sound's 'ready' status denoting that the sound is fully prepared for playing (audibly or silently) to begin.
`void` | `setContinuousEnable(boolean state)` Enables or disables continuous play flag.
`void` | `setEnable(boolean state)` Enable or disable sound.
`void` | `setInitialGain(float amplitude)` Set the overall gain scale factor applied to data associated with this source to increase or decrease its overall amplitude.
`void` | `setLoop(int loopCount)` Sets a sound's loop count.
`void` | `setPriority(float priority)` Set sound's priority value.
`void` | `setReleaseEnable(boolean state)` Enables or disables the release flag for the sound associated with this sound.
`void` | `setSchedulingBoundingLeaf(BoundingLeaf region)` Set the Sound's scheduling region to the specified bounding leaf.
`void` | `setSchedulingBounds(Bounds region)` Set the Sound's scheduling region to the specified bounds.
`void` | `setSoundData(MediaContainer soundData)` Sets fields that define the sound source data of this node.
`void` | `updateNodeReferences(NodeReferenceTable referenceTable)` Callback used to allow a node to check if any scene graph objects referenced by that node have been duplicated via a call to `cloneTree`.

Methods inherited from class javax.media.j3d.Node
`cloneNode, cloneTree, cloneTree, cloneTree, duplicateNode, getBounds, getBoundsAutoCompute, getCollidable, getLocalToVworld, getLocalToVworld, getParent, getPickable, setBounds, setBoundsAutoCompute, setCollidable, setPickable`

Methods inherited from class javax.media.j3d.SceneGraphObject
`clearCapability, duplicateSceneGraphObject, getCapability, getUserData, isCompiled, isLive, setCapability, setUserData`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### ALLOW_SOUND_DATA_READ

    public static final int ALLOW_SOUND_DATA_READ

  Specifies that this node allows access to its object's sound data information.

### ALLOW_SOUND_DATA_WRITE

    public static final int ALLOW_SOUND_DATA_WRITE

  Specifies that this node allows writing to its object's sound data information.

### ALLOW_INITIAL_GAIN_READ

    public static final int ALLOW_INITIAL_GAIN_READ

  Specifies that this node allows access to its object's initial gain information.

### ALLOW_INITIAL_GAIN_WRITE

    public static final int ALLOW_INITIAL_GAIN_WRITE

  Specifies that this node allows writing to its object's initial gain information.

### ALLOW_LOOP_READ

    public static final int ALLOW_LOOP_READ

  Specifies that this node allows access to its object's loop information.

### ALLOW_LOOP_WRITE

    public static final int ALLOW_LOOP_WRITE

  Specifies that this node allows writing to its object's loop information.

### ALLOW_RELEASE_READ

    public static final int ALLOW_RELEASE_READ

  Specifies that this node allows access to its object's release flag information.

### ALLOW_RELEASE_WRITE

    public static final int ALLOW_RELEASE_WRITE

  Specifies that this node allows writing to its object's release flag information.

### ALLOW_CONT_PLAY_READ

    public static final int ALLOW_CONT_PLAY_READ

  Specifies that this node allows access to its object's continuous play information.

### ALLOW_CONT_PLAY_WRITE

    public static final int ALLOW_CONT_PLAY_WRITE

  Specifies that this node allows writing to its object's continuous play information.

### ALLOW_ENABLE_READ

    public static final int ALLOW_ENABLE_READ

  Specifies that this node allows access to its object's sound on information.

### ALLOW_ENABLE_WRITE

    public static final int ALLOW_ENABLE_WRITE

  Specifies that this node allows writing to its object's sound on information.

### ALLOW_SCHEDULING_BOUNDS_READ

    public static final int ALLOW_SCHEDULING_BOUNDS_READ

  Specifies that this node allows read access to its scheduling bounds information.

### ALLOW_SCHEDULING_BOUNDS_WRITE

    public static final int ALLOW_SCHEDULING_BOUNDS_WRITE

  Specifies that this node allows write access to its scheduling bounds information.

### ALLOW_PRIORITY_READ

    public static final int ALLOW_PRIORITY_READ

  Specifies that this node allows read access to its priority order value.

### ALLOW_PRIORITY_WRITE

    public static final int ALLOW_PRIORITY_WRITE

  Specifies that this node allows write access to its priority order value.

### ALLOW_DURATION_READ

    public static final int ALLOW_DURATION_READ

  Specifies that this node allows access to its object's sound duration information.

### ALLOW_IS_READY_READ

    public static final int ALLOW_IS_READY_READ

  Specifies that this node allows access to its object's sound status denoting if it is ready to be played 'immediately'.

### ALLOW_IS_PLAYING_READ

    public static final int ALLOW_IS_PLAYING_READ

  Specifies that this node allows access to its object's sound audibly playing or playing silently status.

### ALLOW_CHANNELS_USED_READ

    public static final int ALLOW_CHANNELS_USED_READ

  Specifies that this node allows access to its number of channels used by this sound.

### NO_FILTER

    public static final float NO_FILTER

  Denotes that there is no filter value associated with object's distance or angular attenuation array.

### DURATION_UNKNOWN

    public static final int DURATION_UNKNOWN

  Denotes that the sound's duration could not be calculated. A fall back for getDuration of a non-cached sound.

### INFINITE_LOOPS

    public static final int INFINITE_LOOPS

  When used as a loop count sound will loop an infinite number of time until explicitly stopped (setEnabled(false)).

Constructor Detail

### Sound

    public Sound()

  Constructs and initializes a new Sound node using default parameters. The following defaults values are used:
  sound data: null
  initial gain: 1.0
  loop: 0
  release flag: false
  continuous flag: false
  on switch: false
  scheduling region: null (cannot be scheduled)
  priority: 1.0

### Sound

    public Sound(MediaContainer soundData,
                 float initialGain)

  Constructs and initializes a new Sound node object using the provided data and gain parameter values, and defaults for all other fields. This constructor implicitly loads the sound data associated with this node if the implementation uses sound caching.
  Parameters:
    `soundData` - description of JMF source data used by this sound source
    `initialGain` - overall amplitude scale factor applied to sound source

### Sound

    public Sound(MediaContainer soundData,
                 float initialGain,
                 int loopCount,
                 boolean release,
                 boolean continuous,
                 boolean enable,
                 Bounds region,
                 float priority)

  Constructs and initializes a new Sound node using provided parameter values.
  Parameters:
    `soundData` - description of JMF source data used by this sound source
    `initialGain` - overall amplitude scale factor applied to sound source
    `loopCount` - number of times sound is looped when played
    `release` - flag denoting sound is to be played to end when stopped
    `continuous` - denotes that sound silently plays when disabled
    `enable` - sound switched on/off
    `region` - scheduling bounds
    `priority` - defines playback priority if too many sounds started

Method Detail

### setSoundData

    public final void setSoundData(MediaContainer soundData)

  Sets fields that define the sound source data of this node.
  Parameters:
    `soundData` - description of JMF source data used by this sound source
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### getSoundData

    public final MediaContainer getSoundData()

  Retrieves description/data associated with this sound source.
  Parameters:
    `soundData` - description of JMF source data used by this sound source
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### setInitialGain

    public final void setInitialGain(float amplitude)

  Set the overall gain scale factor applied to data associated with this source to increase or decrease its overall amplitude.
  Parameters:
    `amplitude` - (gain) scale factor
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### getInitialGain

    public final float getInitialGain()

  Get the overall gain applied to the sound data associated with source.
  Returns:
    overall gain scale factor applied to sound source data.
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### setLoop

    public final void setLoop(int loopCount)

  Sets a sound's loop count.
  Parameters:
    `loopCount` - number of times sound is looped during play
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### getLoop

    public final int getLoop()

  Retrieves loop count for this sound
  Returns:
    loop count
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### setReleaseEnable

    public final void setReleaseEnable(boolean state)

  Enables or disables the release flag for the sound associated with this sound.
  Parameters:
    `state` - release flag
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### getReleaseEnable

    public final boolean getReleaseEnable()

  Retrieves release flag for sound associated with sound.
  Returns:
    sound's release flag
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### setContinuousEnable

    public final void setContinuousEnable(boolean state)

  Enables or disables continuous play flag.
  Parameters:
    `state` - denotes if deactivated sound silently continues playing
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### getContinuousEnable

    public final boolean getContinuousEnable()

  Retrieves sound's continuous play flag.
  Returns:
    flag denoting if deactivated sound silently continues playing
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### setEnable

    public final void setEnable(boolean state)

  Enable or disable sound.
  Parameters:
    `state` - enable (on/off) flag denotes if active sound is heard
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### getEnable

    public final boolean getEnable()

  Retrieves sound's enabled flag.
  Returns:
    sound enabled flag
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### setSchedulingBounds

    public final void setSchedulingBounds(Bounds region)

  Set the Sound's scheduling region to the specified bounds. This is used when the scheduling bounding leaf is set to null.
  Parameters:
    `region` - the bounds that contains the Sound's new scheduling region.
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### getSchedulingBounds

    public final Bounds getSchedulingBounds()

  Retrieves the Sound node's scheduling bounds.
  Returns:
    this Sound's scheduling bounds information
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### setSchedulingBoundingLeaf

    public final void setSchedulingBoundingLeaf(BoundingLeaf region)

  Set the Sound's scheduling region to the specified bounding leaf. When set to a value other than null, this overrides the scheduling bounds object.
  Parameters:
    `region` - the bounding leaf node used to specify the Sound node's new scheduling region.
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### getSchedulingBoundingLeaf

    public final BoundingLeaf getSchedulingBoundingLeaf()

  Retrieves the Sound node's scheduling bounding leaf.
  Returns:
    this Sound's scheduling bounding leaf information
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### setPriority

    public final void setPriority(float priority)

  Set sound's priority value.
  Parameters:
    `priority` - value used to order sound's importance for playback.
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### getPriority

    public final float getPriority()

  Retrieves sound's priority value.
  Returns:
    sound priority value
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### getDuration

    public final long getDuration()

  Get the Sound's duration
  Returns:
    this Sound's duration in milliseconds including repeated loops
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### isReady

    public final boolean isReady()

  Retrieves sound's 'ready' status denoting that the sound is fully prepared for playing (audibly or silently) to begin.
  Returns:
    flag denoting if sound is immediate playable or not
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### isPlaying

    public final boolean isPlaying()

  Retrieves sound's play status.
  Returns:
    flag denoting if sound is playing (potentially audible) or not
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### isPlayingSilently

    public final boolean isPlayingSilently()

  Retrieves sound's silent status.
  Returns:
    flag denoting if sound is silently playing (enabled but not active)
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### getNumberOfChannelsUsed

    public final int getNumberOfChannelsUsed()

  Retrieves number of channels (on executing audio device) that are being used this sound
  Returns:
    number of channels used by sound; returns 0 if not playing
  Throws:
    CapabilityNotSetException - if appropriate capability is not set and this object is part of live or compiled scene graph

### updateNodeReferences

    public void updateNodeReferences(NodeReferenceTable referenceTable)

  Callback used to allow a node to check if any scene graph objects referenced by that node have been duplicated via a call to `cloneTree`. This method is called by `cloneTree` after all nodes in the sub-graph have been duplicated. The cloned Leaf node's method will be called and the Leaf node can then look up any object references by using the `getNewObjectReference` method found in the `NodeReferenceTable` object. If a match is found, a reference to the corresponding object in the newly cloned sub-graph is returned. If no corresponding reference is found, either a DanglingReferenceException is thrown or a reference to the original object is returned depending on the value of the `allowDanglingReferences` parameter passed in the `cloneTree` call.
  Overrides:
    updateNodeReferences in class Leaf
  Parameters:
    `referenceTable` - a NodeReferenceTableObject that contains the `getNewObjectReference` method needed to search for new object instances.
  See Also:
    `NodeReferenceTable`, `Node.cloneTree()`, `DanglingReferenceException`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD