javax.media.j3d
Class PointSound

java.lang.Object
  extended by javax.media.j3d.SceneGraphObject
      extended by javax.media.j3d.Node
          extended by javax.media.j3d.Leaf
              extended by javax.media.j3d.Sound
                  extended by 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


Field Summary
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_PICKABLE_READ, ALLOW_PICKABLE_WRITE, ENABLE_COLLISION_REPORTING, ENABLE_PICK_REPORTING
 
Constructor Summary
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, 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, 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, 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.
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.
 
Method Summary
 Node cloneNode(boolean forceDuplicate)
          Creates a new instance of the node.
 void duplicateNode(Node originalNode, boolean forceDuplicate)
          Copies all node information from originalNode into the current node.
 void getDistanceGain(float[] distance, float[] gain)
          Gets this sound's distance gain attenuation values in separate arrays.
 void getDistanceGain(Point2f[] attenuation)
          Gets this sound's distance attenuation.
 int getDistanceGainLength()
          Get the length of this node's distance gain attenuation arrays.
 void getPosition(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(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(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, getLocalToVworld, getLocalToVworld, getParent, getPickable, setBounds, setBoundsAutoCompute, setCollidable, setPickable
 
Methods inherited from class javax.media.j3d.SceneGraphObject
clearCapability, clearCapabilityIsFrequent, duplicateSceneGraphObject, getCapability, getCapabilityIsFrequent, getUserData, isCompiled, isLive, setCapability, setCapabilityIsFrequent, setUserData
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

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:


PointSound

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. 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
initialGain - amplitude scale factor applied to sound source
position - 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 node
initialGain - amplitude scale factor applied to sound source data
posX - x coordinate of location of source
posY - y coordinate of location of source
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)
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
initialGain - amplitude scale factor applied to sound source
loopCount - number of times loop is looped
release - flag denoting playing sound data to end
continuous - denotes that sound silently plays when disabled
enable - sound switched on/off
region - scheduling bounds
priority - playback ranking value
position - 3D location of source
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)
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
initialGain - amplitude scale factor applied to sound source
loopCount - number of times loop is looped
release - flag denoting playing sound to end
continuous - denotes that sound silently plays when disabled
enable - sound switched on/off
region - scheduling bounds
priority - playback ranking value
posX - x coordinate of location of source
posY - y coordinate of location of source
posZ - z coordinate of location of source
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)
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
initialGain - amplitude scale factor applied to sound source
loopCount - number of times loop is looped
release - flag denoting playing sound data to end
continuous - denotes that sound silently plays when disabled
enable - sound switched on/off
region - scheduling bounds
priority - playback ranking value
position - 3D location of source
attenuationDistance - array of distance values used for attenuation
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)
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
initialGain - amplitude scale factor applied to sound source
loopCount - number of times loop is looped
release - flag denoting playing sound to end
continuous - denotes that sound silently plays when disabled
enable - sound switched on/off
region - scheduling bounds
priority - playback ranking value
posX - x coordinate of location of source
posY - y coordinate of location of source
posZ - z coordinate of location of source
attenuationDistance - array of distance values used for attenuation
attenuationGain - array of gain scale factors used for attenuation
Method Detail

setPosition

public void setPosition(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 position
y - the new y position
z - 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(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(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 floats
gain - 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(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 source
gain - 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 by cloneTree to duplicate the current node.

Overrides:
cloneNode in class Node
Parameters:
forceDuplicate - when set to true, causes the duplicateOnCloneTree flag to be ignored. When false, the value of each node's duplicateOnCloneTree 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 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.

Overrides:
duplicateNode in class Node
Parameters:
originalNode - the original node to duplicate.
forceDuplicate - when set to true, causes the duplicateOnCloneTree flag to be ignored. When false, the value of each node's duplicateOnCloneTree variable determines whether NodeComponent data is duplicated or copied.
Throws:
java.lang.ClassCastException - if originalNode is not an instance of PointSound
See Also:
Node.cloneTree(), Node.cloneNode(boolean), NodeComponent.setDuplicateOnCloneTree(boolean)