Class PointSound
- java.lang.Object
-
- javax.media.j3d.SceneGraphObject
-
- javax.media.j3d.Node
-
- javax.media.j3d.Leaf
-
- javax.media.j3d.Sound
-
- javax.media.j3d.PointSound
-
- Direct Known Subclasses:
ConeSound
public class PointSound extends Sound
The PointSound node (a sub-class of the Sound node) defines a spatially located sound source whose waves radiate uniformly in all directions from a given location in space. It has the same attributes as a Sound object with the addition of a location and the specification of distance-based gain attenuation for listener positions between an array of distances.A sound's amplitude is attenuated based on the distance between the listener and the sound source position. A piecewise linear curve (defined in terms of pairs of distance and gain scale factor) specifies the gain scale factor slope. The PointSound's location and attenuation distances are defined in the local coordinate system of the node.
Distance Gain Attenuation
-
Associated with distances from the listener to the sound source via an
array of (distance, gain-scale-factor) pairs. The gain scale factor
applied to the sound source is the linear interpolated gain value between
the distance value range that includes the current distance from
the listener to the sound source. If the distance from the listener to
the sound source is less than the first distance in the array, the first
gain scale factor is applied to the sound source. This creates a
spherical region around the listener within which all sound gain is
uniformly scaled by the first gain in the array. If the distance from
the listener to the sound source is greater than the last distance in
the array, the last gain scale factor is applied to the sound source.
Distance elements in this array of Point2f is a monotonically-increasing set of floating point numbers measured from the location of the sound source. Gain scale factors elements in this list of pairs can be any positive floating point numbers. While for most applications this list of gain scale factors will usually be monotonically-decreasing, they do not have to be. If this is not set, no distance gain attenuation is performed (equivalent to using a distance gain of 1.0 for all distances).
getDistanceGainLength method returns the length of the distance gain attenuation arrays. Arrays passed into getDistanceGain methods should all be at least this size.
There are two methods for getDistanceGain, one returning an array of points, the other returning separate arrays for each attenuation component.
-
-
Field Summary
Fields Modifier and Type Field Description static int
ALLOW_DISTANCE_GAIN_READ
Specifies that this node allows access to its object's distance gain attenuation information.static int
ALLOW_DISTANCE_GAIN_WRITE
Specifies that this node allows writing to its object's distance gain attenuation information.static int
ALLOW_POSITION_READ
Specifies that this node allows access to its object's position information.static int
ALLOW_POSITION_WRITE
Specifies that this node allows writing to its object's position information.-
Fields inherited from class javax.media.j3d.Sound
ALLOW_CHANNELS_USED_READ, ALLOW_CONT_PLAY_READ, ALLOW_CONT_PLAY_WRITE, ALLOW_DURATION_READ, ALLOW_ENABLE_READ, ALLOW_ENABLE_WRITE, ALLOW_INITIAL_GAIN_READ, ALLOW_INITIAL_GAIN_WRITE, ALLOW_IS_PLAYING_READ, ALLOW_IS_READY_READ, ALLOW_LOOP_READ, ALLOW_LOOP_WRITE, ALLOW_MUTE_READ, ALLOW_MUTE_WRITE, ALLOW_PAUSE_READ, ALLOW_PAUSE_WRITE, ALLOW_PRIORITY_READ, ALLOW_PRIORITY_WRITE, ALLOW_RATE_SCALE_FACTOR_READ, ALLOW_RATE_SCALE_FACTOR_WRITE, ALLOW_RELEASE_READ, ALLOW_RELEASE_WRITE, ALLOW_SCHEDULING_BOUNDS_READ, ALLOW_SCHEDULING_BOUNDS_WRITE, ALLOW_SOUND_DATA_READ, ALLOW_SOUND_DATA_WRITE, DURATION_UNKNOWN, INFINITE_LOOPS, NO_FILTER
-
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_LOCALE_READ, ALLOW_PARENT_READ, ALLOW_PICKABLE_READ, ALLOW_PICKABLE_WRITE, ENABLE_COLLISION_REPORTING, ENABLE_PICK_REPORTING
-
-
Constructor Summary
Constructors Constructor Description PointSound()
Constructs and initializes a new PointSound node using default parameters.PointSound(MediaContainer soundData, float initialGain, float posX, float posY, float posZ)
Constructs a PointSound node object using only the provided parameter values for sound data, sample gain, and position.PointSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, float posX, float posY, float posZ, float[] attenuationDistance, float[] attenuationGain)
Construct a PointSound object accepting individual float parameters for the elements of the position points, and accepting separate arrays for the distance and gain scale factors components of distance attenuation.PointSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, float posX, float posY, float posZ, javax.vecmath.Point2f[] distanceGain)
Construct a PointSound object accepting individual float parameters for the elements of the position point, and accepting an array of Point2f for the distance attenuation values where each pair in the array contains a distance and a gain scale factor.PointSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, javax.vecmath.Point3f position, float[] attenuationDistance, float[] attenuationGain)
Construct a PointSound object accepting points as input for the position.PointSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, javax.vecmath.Point3f position, javax.vecmath.Point2f[] distanceGain)
Construct a PointSound object accepting Point3f as input for the position and accepting an array of Point2f for the distance attenuation values where each pair in the array contains a distance and a gain scale factor.PointSound(MediaContainer soundData, float initialGain, javax.vecmath.Point3f position)
Constructs a PointSound node object using only the provided parameter values for sound data, sample gain, and position.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description Node
cloneNode(boolean forceDuplicate)
Creates a new instance of the node.void
duplicateNode(Node originalNode, boolean forceDuplicate)
Copies all node information fromoriginalNode
into the current node.void
getDistanceGain(float[] distance, float[] gain)
Gets this sound's distance gain attenuation values in separate arrays.void
getDistanceGain(javax.vecmath.Point2f[] attenuation)
Gets this sound's distance attenuation.int
getDistanceGainLength()
Get the length of this node's distance gain attenuation arrays.void
getPosition(javax.vecmath.Point3f position)
Retrieves this sound's direction and places it in the vector provided.void
setDistanceGain(float[] distance, float[] gain)
Sets this sound's distance gain attenuation as an array of Point2fs.void
setDistanceGain(javax.vecmath.Point2f[] attenuation)
Sets this sound's distance gain attenuation - where gain scale factor is applied to sound based on distance listener is from sound source.void
setPosition(float x, float y, float z)
Sets this sound's position from the three values provided.void
setPosition(javax.vecmath.Point3f position)
Sets this sound's location from the vector provided.-
Methods inherited from class javax.media.j3d.Sound
getContinuousEnable, getDuration, getEnable, getInitialGain, getLoop, getMute, getNumberOfChannelsUsed, getNumberOfChannelsUsed, getPause, getPriority, getRateScaleFactor, getReleaseEnable, getSchedulingBoundingLeaf, getSchedulingBounds, getSoundData, isPlaying, isPlaying, isPlayingSilently, isPlayingSilently, isReady, isReady, setContinuousEnable, setEnable, setInitialGain, setLoop, setMute, setPause, setPriority, setRateScaleFactor, setReleaseEnable, setSchedulingBoundingLeaf, setSchedulingBounds, setSoundData, updateNodeReferences
-
Methods inherited from class javax.media.j3d.Node
cloneTree, cloneTree, cloneTree, cloneTree, cloneTree, cloneTree, getBounds, getBoundsAutoCompute, getCollidable, getLocale, getLocalToVworld, getLocalToVworld, getParent, getPickable, setBounds, setBoundsAutoCompute, setCollidable, setPickable
-
Methods inherited from class javax.media.j3d.SceneGraphObject
clearCapability, clearCapabilityIsFrequent, duplicateSceneGraphObject, getCapability, getCapabilityIsFrequent, getName, getUserData, isCompiled, isLive, setCapability, setCapabilityIsFrequent, setName, setUserData, toString
-
-
-
-
Field Detail
-
ALLOW_POSITION_READ
public static final int ALLOW_POSITION_READ
Specifies that this node allows access to its object's position information.- See Also:
- Constant Field Values
-
ALLOW_POSITION_WRITE
public static final int ALLOW_POSITION_WRITE
Specifies that this node allows writing to its object's position information.- See Also:
- Constant Field Values
-
ALLOW_DISTANCE_GAIN_READ
public static final int ALLOW_DISTANCE_GAIN_READ
Specifies that this node allows access to its object's distance gain attenuation information.- See Also:
- Constant Field Values
-
ALLOW_DISTANCE_GAIN_WRITE
public static final int ALLOW_DISTANCE_GAIN_WRITE
Specifies that this node allows writing to its object's distance gain attenuation information.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
PointSound
public PointSound()
Constructs and initializes a new PointSound node using default parameters. The following default values are used:-
position vector: (0.0, 0.0, 0.0)
Back attenuation: null
distance gain attenuation: null (no attenuation performed)
-
PointSound
public PointSound(MediaContainer soundData, float initialGain, javax.vecmath.Point3f position)
Constructs a PointSound node object using only the provided parameter values for sound data, sample gain, and position. The remaining fields are set to the above default values. This form uses a point as input for its position.- Parameters:
soundData
- sound data associated with this sound source nodeinitialGain
- amplitude scale factor applied to sound sourceposition
- 3D location of source
-
PointSound
public PointSound(MediaContainer soundData, float initialGain, float posX, float posY, float posZ)
Constructs a PointSound node object using only the provided parameter values for sound data, sample gain, and position. The remaining fields are set to to the above default values. This form uses individual float parameters for the elements of the position point.- Parameters:
soundData
- sound data associated with this sound source nodeinitialGain
- amplitude scale factor applied to sound source dataposX
- x coordinate of location of sourceposY
- y coordinate of location of sourceposZ
- z coordinate of location of source
-
PointSound
public PointSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, javax.vecmath.Point3f position, javax.vecmath.Point2f[] distanceGain)
Construct a PointSound object accepting Point3f as input for the position and accepting an array of Point2f for the distance attenuation values where each pair in the array contains a distance and a gain scale factor.- Parameters:
soundData
- sound data associated with this sound source nodeinitialGain
- amplitude scale factor applied to sound sourceloopCount
- number of times loop is loopedrelease
- flag denoting playing sound data to endcontinuous
- denotes that sound silently plays when disabledenable
- sound switched on/offregion
- scheduling boundspriority
- playback ranking valueposition
- 3D location of sourcedistanceGain
- array of (distance,gain) pairs controling attenuation
-
PointSound
public PointSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, float posX, float posY, float posZ, javax.vecmath.Point2f[] distanceGain)
Construct a PointSound object accepting individual float parameters for the elements of the position point, and accepting an array of Point2f for the distance attenuation values where each pair in the array contains a distance and a gain scale factor.- Parameters:
soundData
- sound data associated with this sound source nodeinitialGain
- amplitude scale factor applied to sound sourceloopCount
- number of times loop is loopedrelease
- flag denoting playing sound to endcontinuous
- denotes that sound silently plays when disabledenable
- sound switched on/offregion
- scheduling boundspriority
- playback ranking valueposX
- x coordinate of location of sourceposY
- y coordinate of location of sourceposZ
- z coordinate of location of sourcedistanceGain
- array of (distance,gain) pairs controling attenuation
-
PointSound
public PointSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, javax.vecmath.Point3f position, float[] attenuationDistance, float[] attenuationGain)
Construct a PointSound object accepting points as input for the position. and accepting separate arrays for the distance and gain scale factors components of distance attenuation.- Parameters:
soundData
- sound data associated with this sound source nodeinitialGain
- amplitude scale factor applied to sound sourceloopCount
- number of times loop is loopedrelease
- flag denoting playing sound data to endcontinuous
- denotes that sound silently plays when disabledenable
- sound switched on/offregion
- scheduling boundspriority
- playback ranking valueposition
- 3D location of sourceattenuationDistance
- array of distance values used for attenuationattenuationGain
- array of gain scale factors used for attenuation
-
PointSound
public PointSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, float posX, float posY, float posZ, float[] attenuationDistance, float[] attenuationGain)
Construct a PointSound object accepting individual float parameters for the elements of the position points, and accepting separate arrays for the distance and gain scale factors components of distance attenuation.- Parameters:
soundData
- sound data associated with this sound source nodeinitialGain
- amplitude scale factor applied to sound sourceloopCount
- number of times loop is loopedrelease
- flag denoting playing sound to endcontinuous
- denotes that sound silently plays when disabledenable
- sound switched on/offregion
- scheduling boundspriority
- playback ranking valueposX
- x coordinate of location of sourceposY
- y coordinate of location of sourceposZ
- z coordinate of location of sourceattenuationDistance
- array of distance values used for attenuationattenuationGain
- array of gain scale factors used for attenuation
-
-
Method Detail
-
setPosition
public void setPosition(javax.vecmath.Point3f position)
Sets this sound's location from the vector provided.- Parameters:
position
- the new location- Throws:
CapabilityNotSetException
- if appropriate capability is not set and this object is part of live or compiled scene graph
-
setPosition
public void setPosition(float x, float y, float z)
Sets this sound's position from the three values provided.- Parameters:
x
- the new x positiony
- the new y positionz
- the new z position- Throws:
CapabilityNotSetException
- if appropriate capability is not set and this object is part of live or compiled scene graph
-
getPosition
public void getPosition(javax.vecmath.Point3f position)
Retrieves this sound's direction and places it in the vector provided.- Parameters:
position
- the variable to receive the direction vector- Throws:
CapabilityNotSetException
- if appropriate capability is not set and this object is part of live or compiled scene graph
-
setDistanceGain
public void setDistanceGain(javax.vecmath.Point2f[] attenuation)
Sets this sound's distance gain attenuation - where gain scale factor is applied to sound based on distance listener is from sound source. This form of setDistanceGain takes these pairs of values as an array of Point2f.- Parameters:
attenuation
- defined by pairs of (distance,gain-scale-factor)- Throws:
CapabilityNotSetException
- if appropriate capability is not set and this object is part of live or compiled scene graph
-
setDistanceGain
public void setDistanceGain(float[] distance, float[] gain)
Sets this sound's distance gain attenuation as an array of Point2fs. This form of setDistanceGain accepts two separate arrays for these values. The distance and gainScale arrays should be of the same length. If the gainScale array length is greater than the distance array length, the gainScale array elements beyond the length of the distance array are ignored. If the gainScale array is shorter than the distance array, the last gainScale array value is repeated to fill an array of length equal to distance array.- Parameters:
distance
- array of monotonically-increasing floatsgain
- array of non-negative scale factors- Throws:
CapabilityNotSetException
- if appropriate capability is not set and this object is part of live or compiled scene graph
-
getDistanceGainLength
public int getDistanceGainLength()
Get the length of this node's distance gain attenuation arrays.- Returns:
- distance gain attenuation array length
- Throws:
CapabilityNotSetException
- if appropriate capability is not set and this object is part of live or compiled scene graph
-
getDistanceGain
public void getDistanceGain(javax.vecmath.Point2f[] attenuation)
Gets this sound's distance attenuation. The distance attenuation pairs are copied into the specified array. The array must be large enough to hold all of the points. The individual array elements must be allocated by the caller.- Parameters:
attenuation
- arrays containing distance attenuation pairs- Throws:
CapabilityNotSetException
- if appropriate capability is not set and this object is part of live or compiled scene graph
-
getDistanceGain
public void getDistanceGain(float[] distance, float[] gain)
Gets this sound's distance gain attenuation values in separate arrays. The arrays must be large enough to hold all of the values.- Parameters:
distance
- array of float distance from sound sourcegain
- array of non-negative scale factors associated with- Throws:
CapabilityNotSetException
- if appropriate capability is not set and this object is part of live or compiled scene graph
-
cloneNode
public Node cloneNode(boolean forceDuplicate)
Creates a new instance of the node. This routine is called bycloneTree
to duplicate the current node.- Overrides:
cloneNode
in classNode
- Parameters:
forceDuplicate
- when set totrue
, causes theduplicateOnCloneTree
flag to be ignored. Whenfalse
, the value of each node'sduplicateOnCloneTree
variable determines whether NodeComponent data is duplicated or copied.- See Also:
Node.cloneTree()
,Node.cloneNode(boolean)
,Node.duplicateNode(javax.media.j3d.Node, boolean)
,NodeComponent.setDuplicateOnCloneTree(boolean)
-
duplicateNode
public void duplicateNode(Node originalNode, boolean forceDuplicate)
Copies all node information fromoriginalNode
into the current node. This method is called from thecloneNode
method which is, in turn, called by thecloneTree
method.For any
NodeComponent
objects contained by the object being duplicated, eachNodeComponent
object'sduplicateOnCloneTree
value is used to determine whether theNodeComponent
should be duplicated in the new node or if just a reference to the current node should be placed in the new node. This flag can be overridden by setting theforceDuplicate
parameter in thecloneTree
method totrue
.
NOTE: Applications should not call this method directly. It should only be called by the cloneNode method.- Overrides:
duplicateNode
in classNode
- Parameters:
originalNode
- the original node to duplicate.forceDuplicate
- when set totrue
, causes theduplicateOnCloneTree
flag to be ignored. Whenfalse
, the value of each node'sduplicateOnCloneTree
variable determines whether NodeComponent data is duplicated or copied.- Throws:
java.lang.ClassCastException
- if originalNode is not an instance ofPointSound
- See Also:
Node.cloneTree()
,Node.cloneNode(boolean)
,NodeComponent.setDuplicateOnCloneTree(boolean)
-
-