| java.lang.Object
 javax.media.j3d.SceneGraphObject
javax.media.j3d.Node
javax.media.j3d.Leaf
javax.media.j3d.Sound
javax.media.j3d.PointSound
All known Subclasses: javax.media.j3d.ConeSound,
| PointSound | | public class PointSound extends Sound (Code) | | 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 | |
| final public static int | ALLOW_DISTANCE_GAIN_READ
Specifies that this node allows access to its object's distance
gain attenuation information. | | final public static int | ALLOW_DISTANCE_GAIN_WRITE
Specifies that this node allows writing to its object's distance
gain attenuation information. | | final public static int | ALLOW_POSITION_READ
Specifies that this node allows access to its object's position
information. | | final public static int | ALLOW_POSITION_WRITE
Specifies that this node allows writing to its object's position
information. |
| Constructor Summary | |
| public | PointSound()
Constructs and initializes a new PointSound node using default
parameters. | | public | PointSound(MediaContainer soundData, float initialGain, Point3f position)
Constructs a PointSound node object using only the provided parameter
values for sound data, sample gain, and position. | | 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. | | public | PointSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, Point3f position, 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. | | public | PointSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, float posX, float posY, float posZ, 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. | | public | PointSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, 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. | | 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. |
| Method Summary | |
| public Node | cloneNode(boolean forceDuplicate)
Creates a new instance of the node. | | void | createRetained()
Creates the retained mode PointSoundRetained object that this
PointSound object will point to. | | void | duplicateAttributes(Node originalNode, boolean forceDuplicate)
Copies all PointSound information from
originalNode into
the current node. | | public void | duplicateNode(Node originalNode, boolean forceDuplicate)
Copies all node information from originalNode into
the current node. | | public void | getDistanceGain(Point2f[] attenuation)
Gets this sound's distance attenuation. | | public void | getDistanceGain(float[] distance, float[] gain)
Gets this sound's distance gain attenuation values in separate arrays. | | public int | getDistanceGainLength()
Get the length of this node's distance gain attenuation arrays. | | public void | getPosition(Point3f position)
Retrieves this sound's direction and places it in the
vector provided. | | public void | setDistanceGain(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. | | 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. | | public void | setPosition(Point3f position)
Sets this sound's location from the vector provided. | | public void | setPosition(float x, float y, float z)
Sets this sound's position from the three values provided. |
| ALLOW_DISTANCE_GAIN_READ | | final public static int ALLOW_DISTANCE_GAIN_READ(Code) | | Specifies that this node allows access to its object's distance
gain attenuation information.
|
| ALLOW_DISTANCE_GAIN_WRITE | | final public static int ALLOW_DISTANCE_GAIN_WRITE(Code) | | Specifies that this node allows writing to its object's distance
gain attenuation information.
|
| ALLOW_POSITION_READ | | final public static int ALLOW_POSITION_READ(Code) | | Specifies that this node allows access to its object's position
information.
|
| ALLOW_POSITION_WRITE | | final public static int ALLOW_POSITION_WRITE(Code) | | Specifies that this node allows writing to its object's position
information.
|
| PointSound | | public PointSound()(Code) | | 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, Point3f position)(Code) | | 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 node
Parameters:
initialGain - amplitude scale factor applied to sound source
Parameters:
position - 3D location of source |
| PointSound | | public PointSound(MediaContainer soundData, float initialGain, float posX, float posY, float posZ)(Code) | | 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 node
Parameters:
initialGain - amplitude scale factor applied to sound source data
Parameters:
posX - x coordinate of location of source
Parameters:
posY - y coordinate of location of source
Parameters:
posZ - 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, Point3f position, Point2f[] distanceGain)(Code) | | 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 node
Parameters:
initialGain - amplitude scale factor applied to sound source
Parameters:
loopCount - number of times loop is looped
Parameters:
release - flag denoting playing sound data to end
Parameters:
continuous - denotes that sound silently plays when disabled
Parameters:
enable - sound switched on/off
Parameters:
region - scheduling bounds
Parameters:
priority - playback ranking value
Parameters:
position - 3D location of source
Parameters:
distanceGain - 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, Point2f[] distanceGain)(Code) | | 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 node
Parameters:
initialGain - amplitude scale factor applied to sound source
Parameters:
loopCount - number of times loop is looped
Parameters:
release - flag denoting playing sound to end
Parameters:
continuous - denotes that sound silently plays when disabled
Parameters:
enable - sound switched on/off
Parameters:
region - scheduling bounds
Parameters:
priority - playback ranking value
Parameters:
posX - x coordinate of location of source
Parameters:
posY - y coordinate of location of source
Parameters:
posZ - z coordinate of location of source
Parameters:
distanceGain - 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, Point3f position, float[] attenuationDistance, float[] attenuationGain)(Code) | | 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 node
Parameters:
initialGain - amplitude scale factor applied to sound source
Parameters:
loopCount - number of times loop is looped
Parameters:
release - flag denoting playing sound data to end
Parameters:
continuous - denotes that sound silently plays when disabled
Parameters:
enable - sound switched on/off
Parameters:
region - scheduling bounds
Parameters:
priority - playback ranking value
Parameters:
position - 3D location of source
Parameters:
attenuationDistance - array of distance values used for attenuation
Parameters:
attenuationGain - 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)(Code) | | 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 node
Parameters:
initialGain - amplitude scale factor applied to sound source
Parameters:
loopCount - number of times loop is looped
Parameters:
release - flag denoting playing sound to end
Parameters:
continuous - denotes that sound silently plays when disabled
Parameters:
enable - sound switched on/off
Parameters:
region - scheduling bounds
Parameters:
priority - playback ranking value
Parameters:
posX - x coordinate of location of source
Parameters:
posY - y coordinate of location of source
Parameters:
posZ - z coordinate of location of source
Parameters:
attenuationDistance - array of distance values used for attenuation
Parameters:
attenuationGain - array of gain scale factors used for attenuation |
| cloneNode | | public Node cloneNode(boolean forceDuplicate)(Code) | | Creates a new instance of the node. This routine is called
by cloneTree to duplicate the current node.
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.
See Also: Node.cloneTree
See Also: Node.cloneNode
See Also: Node.duplicateNode
See Also: NodeComponent.setDuplicateOnCloneTree |
| createRetained | | void createRetained()(Code) | | Creates the retained mode PointSoundRetained object that this
PointSound object will point to.
|
| duplicateAttributes | | void duplicateAttributes(Node originalNode, boolean forceDuplicate)(Code) | | Copies all PointSound information from
originalNode into
the current node. This method is called from the
cloneNode method which is, in turn, called by the
cloneTree method.
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 |
| duplicateNode | | public void duplicateNode(Node originalNode, boolean forceDuplicate)(Code) | | Copies all node information from originalNode into
the current node. This method is called from the
cloneNode method which is, in turn, called by the
cloneTree method.
For any NodeComponent objects
contained by the object being duplicated, each NodeComponent
object's duplicateOnCloneTree value is used to determine
whether the NodeComponent 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 the
forceDuplicate parameter in the cloneTree
method to true.
NOTE: Applications should not call this method directly.
It should only be called by the cloneNode method.
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:
ClassCastException - if originalNode is not an instance of PointSound
See Also: Node.cloneTree
See Also: Node.cloneNode
See Also: NodeComponent.setDuplicateOnCloneTree |
| getDistanceGain | | public void getDistanceGain(Point2f[] attenuation)(Code) | | 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
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph |
| getDistanceGain | | public void getDistanceGain(float[] distance, float[] gain)(Code) | | 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 source
Parameters:
gain - array of non-negative scale factors associated with
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph |
| getDistanceGainLength | | public int getDistanceGainLength()(Code) | | Get the length of this node's distance gain attenuation arrays.
distance gain attenuation array length
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph |
| getPosition | | public void getPosition(Point3f position)(Code) | | Retrieves this sound's direction and places it in the
vector provided.
Parameters:
position - the variable to receive the direction vector
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph |
| setDistanceGain | | public void setDistanceGain(Point2f[] attenuation)(Code) | | 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)
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph |
| setDistanceGain | | public void setDistanceGain(float[] distance, float[] gain)(Code) | | 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 floats
Parameters:
gain - array of non-negative scale factors
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph |
| setPosition | | public void setPosition(Point3f position)(Code) | | Sets this sound's location from the vector provided.
Parameters:
position - the new location
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph |
| setPosition | | public void setPosition(float x, float y, float z)(Code) | | Sets this sound's position from the three values provided.
Parameters:
x - the new x position
Parameters:
y - the new y position
Parameters:
z - the new z position
exception:
CapabilityNotSetException - if appropriate capability isnot set and this object is part of live or compiled scene graph |
|
|