Java Doc for Sound.java in  » 6.0-JDK-Modules » java-3d » javax » media » j3d » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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 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 a 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, 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 allow 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 spatialization 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 acts 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 met for a sound to be ready to be played.

Mute Sound

When the mute state is set true, a playing sound is made to play silently.

Pause Sound

When the pause state is set true, a playing sound is paused.

Setting the enable flag to true during construction acts 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 met 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, the 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 become 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 node's 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 eight 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. Furthermore, say the first sound needs three channels to play, the second sound needs four channels, the third sound needs three channels and the fourth sound needs only one channel. The first and second sounds can be started because they require seven of the eight available channels. The third sound can not be audibly started because it requires three channels and only one is still available. Consequently, the third sound starts playing 'silently.' The fourth sound can and will be started since it only requires one channel. The third sound will be made audible when three channels become available (i.e., when the first or second sound finishes playing).

Sounds given the same priority are ordered 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 the AudioDevice class.

Duration

Each sound has a length of time in milliseconds 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:

1) enabled/started
2) activated
3) not muted
4) not paused

While these conditions are meet, the sound is potentially audible and the method isPlaying() will return a status of true.

isPlaying returns false but isPlayingSilently returns true if a sound:

1) is enabled before it is activated; it is begun playing silently.
2) is enabled then deactivated while playing; it continues playing silently
3) is enabled while it mute state is true

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

See Also:   AudioDevice

sound data: null
initial gain: 1.0
loop: 0
release flag: false
continuous flag: false
enable flag: false
scheduling bounds : null
scheduling bounding leaf : null
priority: 1.0
rate scale factor: 1.0
mute state: false
pause state: false

Parameters:
  originalNode - the original node to duplicate.
Parameters:
  forceDuplicate - when set to true, causes theduplicateOnCloneTree flag to be ignored. Whenfalse, the value of each node'sduplicateOnCloneTree variable determines whetherNodeComponent data is duplicated or copied.
exception:
  RestrictedAccessException - if this object is part of a liveor compiled scenegraph.
See Also:   Node.duplicateNode
See Also:   Node.cloneTree
See Also:   NodeComponent.setDuplicateOnCloneTree

NOTE: Applications should not call this method directly. It should only be called by the cloneTree method.
Parameters:
  referenceTable - a NodeReferenceTableObject that contains thegetNewObjectReference method needed to search fornew object instances.
See Also:   NodeReferenceTable
See Also:   Node.cloneTree
See Also:   DanglingReferenceException