All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class javax.media.j3d.Sound

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

public abstract class Sound

extends Leaf

Sound Data

Associated with each Sound node is a Java Media Player container whi which includes audio data. This data can be cached or non-cached, and the non-cached data can be streaming or not. This method explicitly loads a sound if the implementation uses sound data caching, or it makes streaming data audible. While all supported types of MediaContainers can be associated with a non-spatialized Sound node, only specific types can be 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 (say for Java Media Player types that do not contain sound samples) 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.

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.

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 device driver device can handle, the sound node with the lowest priority ranking is deactivated. If a sound is deactivated (due to a sound with a higher priority being started) it is automatically re-activated when output 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.

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.

Playing Status

A sound source will not be heard unless it is both enabled/turned-on and activated. After a sound source has been enabled and thus has begun playing, the end of the sound could be reached before the sound is disabled, or the sound could be deactivated without being stopped. This method returns a flag denoting if the sound is actually playing and thus is potentially audible.

ALLOW_CONT_PLAY_READ

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

ALLOW_CONT_PLAY_WRITE

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

ALLOW_DURATION_READ

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

ALLOW_ENABLE_READ

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

ALLOW_ENABLE_WRITE

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

ALLOW_INITIAL_GAIN_READ

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

ALLOW_INITIAL_GAIN_WRITE

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

ALLOW_IS_PLAYING_READ

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

ALLOW_LOOP_READ

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

ALLOW_LOOP_WRITE

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

ALLOW_PRIORITY_READ

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

ALLOW_PRIORITY_WRITE

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

ALLOW_RELEASE_READ

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

ALLOW_RELEASE_WRITE

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

ALLOW_SCHEDULING_BOUNDS_READ

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

ALLOW_SCHEDULING_BOUNDS_WRITE

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

ALLOW_SOUND_DATA_READ

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

ALLOW_SOUND_DATA_WRITE

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

Sound()

Constructs & initializes a new Sound node using the following defaults:

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(MediaContainer, float)

Constructs and initializes a new Sound node object using the provided data and gain parameter values, and defaults for all other fields.

Sound(MediaContainer, float, int, boolean, boolean, boolean, Bounds, float)

Constructs and initializes a new Sound node using provided parameter values.

getContinuousEnable()

Retrieves sound's continuous play flag.

getDuration()

Get the Sound's duration

getEnable()

Retrieves sound's enabled flag.

getInitialGain()

Get the overall gain applied to the sound data associated with source.

getLoop()

Retrieves loop count for this sound

getPriority()

Retrieves sound's priority value.

getReleaseEnable()

Retrieves release flag for sound associated with sound.

getSchedulingBoundingLeaf()

Retrieves the Sound node's scheduling bounding leaf.

getSchedulingBounds()

Retrieves the Sound node's scheduling bounds.

getSoundData()

Retrieves description/data associated with this sound source.

isPlaying()

Retrieves sound's play status.

setContinuousEnable(boolean)

Enables or disables continuous play flag.

setEnable(boolean)

Enable or disable sound.

setInitialGain(float)

Set the overall gain scale factor applied to data associated with this source to increase or decrease its overall amplitude.

setLoop(int)

Sets a sound's loop count.

setPriority(float)

Set sound's priority value.

setReleaseEnable(boolean)

Enables or disables the release flag for the sound associated with this sound.

setSchedulingBoundingLeaf(BoundingLeaf)

Set the Sound's scheduling region to the specified bounding leaf.

setSchedulingBounds(Bounds)

Set the Sound's scheduling region to the specified bounds.

setSoundData(MediaContainer)

Sets fields that define the sound source data of this node.

 public static final int ALLOW_SOUND_DATA_READ

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

 public static final int ALLOW_SOUND_DATA_WRITE

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

 public static final int ALLOW_INITIAL_GAIN_READ

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

 public static final int ALLOW_INITIAL_GAIN_WRITE

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

 public static final int ALLOW_LOOP_READ

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

 public static final int ALLOW_LOOP_WRITE

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

 public static final int ALLOW_RELEASE_READ

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

 public static final int ALLOW_RELEASE_WRITE

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

 public static final int ALLOW_CONT_PLAY_READ

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

 public static final int ALLOW_CONT_PLAY_WRITE

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

 public static final int ALLOW_ENABLE_READ

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

 public static final int ALLOW_ENABLE_WRITE

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

 public static final int ALLOW_SCHEDULING_BOUNDS_READ

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

 public static final int ALLOW_SCHEDULING_BOUNDS_WRITE

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

 public static final int ALLOW_PRIORITY_READ

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

 public static final int ALLOW_PRIORITY_WRITE

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

 public static final int ALLOW_DURATION_READ

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

 public static final int ALLOW_IS_PLAYING_READ

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

 public Sound()

Constructs & initializes a new Sound node using the following defaults:

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

 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

 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

 public 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

 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

 public 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

 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

 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

 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

 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

 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

 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

 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

 public 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

 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

 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

 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

 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

 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

 public 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

 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

 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

 public final boolean isPlaying()

Retrieves sound's play status.

Returns:

flag denoting if sound is playing or not

Throws: CapabilityNotSetException

if appropriate capability is not set and this object is part of live or compiled scene graph

All Packages  Class Hierarchy  This Package  Previous  Next  Index