|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--javax.media.j3d.SceneGraphObject | +--javax.media.j3d.Node | +--javax.media.j3d.Leaf | +--javax.media.j3d.Sound
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
Initial Gain
Loop
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
Continuous Flag
Enable Sound
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
Scheduling Bounding Leaf
Prioritize Sound
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
Number of Channels used on Audio Device to Play Sound
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
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_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,
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 |
public static final int ALLOW_SOUND_DATA_READ
public static final int ALLOW_SOUND_DATA_WRITE
public static final int ALLOW_INITIAL_GAIN_READ
public static final int ALLOW_INITIAL_GAIN_WRITE
public static final int ALLOW_LOOP_READ
public static final int ALLOW_LOOP_WRITE
public static final int ALLOW_RELEASE_READ
public static final int ALLOW_RELEASE_WRITE
public static final int ALLOW_CONT_PLAY_READ
public static final int ALLOW_CONT_PLAY_WRITE
public static final int ALLOW_ENABLE_READ
public static final int ALLOW_ENABLE_WRITE
public static final int ALLOW_SCHEDULING_BOUNDS_READ
public static final int ALLOW_SCHEDULING_BOUNDS_WRITE
public static final int ALLOW_PRIORITY_READ
public static final int ALLOW_PRIORITY_WRITE
public static final int ALLOW_DURATION_READ
public static final int ALLOW_IS_READY_READ
public static final int ALLOW_IS_PLAYING_READ
public static final int ALLOW_CHANNELS_USED_READ
public static final float NO_FILTER
public static final int DURATION_UNKNOWN
public static final int INFINITE_LOOPS
Constructor Detail |
public Sound()
public Sound(MediaContainer soundData, float initialGain)
soundData
- description of JMF source data used by this sound sourceinitialGain
- overall amplitude scale factor applied to sound sourcepublic Sound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority)
soundData
- description of JMF source data used by this sound sourceinitialGain
- overall amplitude scale factor applied to sound sourceloopCount
- number of times sound is looped when playedrelease
- flag denoting sound is to be played to end when stoppedcontinuous
- denotes that sound silently plays when disabledenable
- sound switched on/offregion
- scheduling boundspriority
- defines playback priority if too many sounds startedMethod Detail |
public void setSoundData(MediaContainer soundData)
soundData
- description of JMF source data used by this sound sourcepublic MediaContainer getSoundData()
soundData
- description of JMF source data used by this sound sourcepublic void setInitialGain(float amplitude)
amplitude
- (gain) scale factorpublic float getInitialGain()
public void setLoop(int loopCount)
loopCount
- number of times sound is looped during playpublic int getLoop()
public void setReleaseEnable(boolean state)
state
- release flagpublic boolean getReleaseEnable()
public void setContinuousEnable(boolean state)
state
- denotes if deactivated sound silently continues playingpublic boolean getContinuousEnable()
public void setEnable(boolean state)
state
- enable (on/off) flag denotes if active sound is heardpublic boolean getEnable()
public void setSchedulingBounds(Bounds region)
region
- the bounds that contains the Sound's new scheduling
region.public Bounds getSchedulingBounds()
public void setSchedulingBoundingLeaf(BoundingLeaf region)
region
- the bounding leaf node used to specify the Sound
node's new scheduling region.public BoundingLeaf getSchedulingBoundingLeaf()
public void setPriority(float priority)
priority
- value used to order sound's importance for playback.public float getPriority()
public long getDuration()
public boolean isReady()
public boolean isPlaying()
public boolean isPlayingSilently()
public int getNumberOfChannelsUsed()
public void updateNodeReferences(NodeReferenceTable referenceTable)
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.
NOTE: Applications should not call this method directly. It should only be called by the cloneTree method.
referenceTable
- a NodeReferenceTableObject that contains the
getNewObjectReference
method needed to search for
new object instances.NodeReferenceTable
,
Node.cloneTree()
,
DanglingReferenceException
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |