All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class javax.media.j3d.PointSound

java.lang.Object
   |
   +----javax.media.j3d.SceneGraphObject
           |
           +----javax.media.j3d.Node
                   |
                   +----javax.media.j3d.Leaf
                           |
                           +----javax.media.j3d.Sound
                                   |
                                   +----javax.media.j3d.PointSound

public class PointSound

extends Sound

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.

Set Sound Data

This fields defines the sound source data of this node. This overloaded method differs from the Sound node method, in that it calls the PointSoundRetained version of this method.

Enable Sound

This method enables or disables sound. Overloading this method allows this to be different from the Sound node version of the method.

ALLOW_DISTANCE_GAIN_READ

Specifies that this node allows access to its object's distance gain attenuation information.

ALLOW_DISTANCE_GAIN_WRITE

Specifies that this node allows writing to its object's distance gain attenuation information.

ALLOW_POSITION_READ

Specifies that this node allows access to its object's position information.

ALLOW_POSITION_WRITE

Specifies that this node allows writing to its object's position information.

PointSound()

Constructs a new Sound node using the following default parameters:

position vector: (0.0, 0.0, 0.0)

Back attenuation: null

distance gain attenuation: null (no attenuation performed)

PointSound(MediaContainer, float, float, float, float)

Constructs a PointSound node object using only the provided parameter values for sound data, sample gain, and position.

PointSound(MediaContainer, float, int, boolean, boolean, boolean, Bounds, float, float, float, float, float[], float[])

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, float, int, boolean, boolean, boolean, Bounds, float, float, float, float, Point2f[])

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, float, int, boolean, boolean, boolean, Bounds, float, Point3f, float[], float[])

Construct a PointSound object accepting points as input for the position.

PointSound(MediaContainer, float, int, boolean, boolean, boolean, Bounds, float, Point3f, Point2f[])

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, float, Point3f)

Constructs a PointSound node object using only the provided parameter values for sound data, sample gain, and position.

getDistanceGain(float[], float[])

Gets this sound's distance gain attenuation values in separate arrays

getDistanceGain(Point2f[])

Gets this sound's distance attenuation

getDistanceGainLength()

Get the length of this node's distance gain attenuation arrays.

getPosition(Point3f)

Retrieves this sound's direction and places it in the vector provided.

setDistanceGain(float[], float[])

Sets this sound's distance gain attenuation as an array of Point2fs.

setDistanceGain(Point2f[])

Sets this sound's distance gain attenuation - where gain scale factor is applied to sound based on distance listener is from sound source.

setEnable(boolean)

Enable or disable sound.

setPosition(float, float, float)

Sets this sound's position from the three values provided.

setPosition(Point3f)

Sets this sound's location from the vector provided.

setSoundData(MediaContainer)

Sets fields that define the sound source data of this node.

 public static final int ALLOW_POSITION_READ

Specifies that this node allows access to its object's position information.

 public static final int ALLOW_POSITION_WRITE

Specifies that this node allows writing to its object's position information.

 public static final int ALLOW_DISTANCE_GAIN_READ

Specifies that this node allows access to its object's distance gain attenuation information.

 public static final int ALLOW_DISTANCE_GAIN_WRITE

Specifies that this node allows writing to its object's distance gain attenuation information.

 public PointSound()

Constructs a new Sound node using the following default parameters:

position vector: (0.0, 0.0, 0.0)

Back attenuation: null

distance gain attenuation: null (no attenuation performed)

 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

 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

 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 - activation bounds

priority - playback ranking value

position - 3D location of source

distanceGain - array of (distance,gain) pairs controling 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,
                   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 - activation 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

 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 - activation 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

 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 - activation 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

 public final 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

 public final 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

 public final 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

 public final 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

 public final 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

 public final 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

 public final void getDistanceGain(Point2f attenuation[])

Gets this sound's distance attenuation

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

 public final void getDistanceGain(float distance[],
                                   float gain[])

Gets this sound's distance gain attenuation values in separate arrays

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

 public final void setSoundData(MediaContainer soundData)

Sets fields that define the sound source data of this node. This differs from the Sound node method, in that it calls the PointSoundRetained version of this method.

Parameters:

soundData - description of JMF source data used by this sound source

Throws: CapabilityNotSetException

if appropriate capability is not set and this object is part of live or compiled scene graph

Overrides:

setSoundData in class Sound

 public void setEnable(boolean state)

Enable or disable sound.

Parameters:

state - enable (on/off) flag denotes if active sound is heard

Throws: CapabilityNotSetException

if appropriate capability is not set and this object is part of live or compiled scene graph

Overrides:

setEnable in class Sound

All Packages  Class Hierarchy  This Package  Previous  Next  Index