All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class javax.media.j3d.ConeSound

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

public class ConeSound
extends PointSound

The ConeSound node object defines a PointSound node whose sound source is directed along a specific vector in space. A ConeSound source is attenuated by gain scale factors and filters based on the angle between the vector from the source to the listener, and the ConeSound's direction vector. This attenuation is either a single spherical distance gain attenuation (as for a general PointSound source) or dual front and back distance gain attenuations defining elliptical attenuation areas. The angular filter and the active AuralAttribute component filter define what filtering is applied to the sound source. (See AuralAtttribute class for more details on filtering.) This node has the same attributes as a PointSound node with the addition of a direction vector and an array of points each containing: angular distance (in radians), gain scale factor, and filter (which for now consists of a lowpass filter cutoff frequency). Similar to the definition of the back distance gain array for PointSounds, a piece-wise linear curve (defined in terms of radians from the axis) specifies the slope of these additional attenuation values.

Distance Gain attuation

Use PointSound setDistanceGain() method to set the front distance attenuation array separate from the back distance attenuation array. A front distance attenuation array defines monotonically increasing distances from the sound source origin along the position direction vector. A back distance attenuation array (if given) defines mono- tonically increasing distances from the sound source origin along the negative direction vector. The two arrays must be of the same length. The backDistance[i] gain values must be less than or equal to frontDistance[i] gain values.

Gain scale factors are 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 the listener to the sound source.

getDistanceGainLength method defined for PointSound returns the length of the all distance gain attenuation arrays, including the back distance gain arrays. Arrays passed into getBackDistanceGain methods should all be at least this size.

Direction Methods

This value is the sound source's direction vector. It is the axis from which angular distance is measured.

Angular Attenuation

This attenuation is defined as a triple of (angular distance, gain-scale-factor, filter). The distance is measured as the angle in radians between the ConeSound's direction vector and the vector from the sound source position to the listener. Both the gain scale factor and filter applied to the sound source is the linear interpolation of values between the distance value range that includes the angular distance from the sound source axis.

If this is not set no angular gain attenuation or filtering is performed (equivalent to using an angular gain scale factor of 1.0 and an angular filter of Sound.NO_FILTER for all distances).

If angular distance from the listener-sound-position vector and a sound's direction vector is less than first distance in the array, only the first gain scale factor and first filter are applied to the sound source. This creates a conical region around the listener within which the sound is uniformly attenuated by first gain and first filter in the array.

If distance from the listener-sound-position vector and the sound's direction vector is greater than last distance in the array, last gain scale factor and last filter are applied to the sound source.

Distance elements in this array of points is a monotonically-increasing set of floating point numbers measured from 0 to p radians. Gain scale factors elements in this list of points 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. The filter (for now) is a single simple frequency cutoff value.

getAngularAttenuationArrayLength method returns the length of the angular attenuation arrays. Arrays passed into getAngularAttenuation methods should all be at least this size.

ALLOW_ANGULAR_ATTENUATION_READ: Specifies that this ConeSound allows access to its object's cone params information.
ALLOW_ANGULAR_ATTENUATION_WRITE: Specifies that this ConeSound allows writing to its object's cone params information.
ALLOW_DIRECTION_READ: Specifies that this ConeSound allows access to its object's direction information.
ALLOW_DIRECTION_WRITE: Specifies that this ConeSound allows writing to its object's direction information.

ConeSound()

Constructs a ConeSound node object that includes the defaults for a PointSound object plus the following defaults for its own fields:

Direction vector: (0.0, 0.0, 1.0)

Angular attenuation: ((0.0, 1.0), Sound.NO_FILTER,(p/2, 0.0, Sound.NO_FILTER))

ConeSound(MediaContainer, float, float, float, float, float, float, float)

Constructs a ConeSound node object using only the provided parameter values for sound, overall initial gain, position, and direction.

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

Constructs a ConeSound node object using all the provided PointSound parameter values, which include a single spherical distance attenuation array, but includes an angular attenuation array.

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

Constructs a ConeSound node object using the provided parameter values.

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

Constructs and initializes a new Cone Sound node explicitly setting all PointSound and ConeSound fields as arguments but all the vector and point arguments are broken into individual float array components.

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

Constructs a ConeSound node object using all the provided PointSound parameter values.

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

Constructs and initializes a new Cone Sound node explicitly setting all PointSound and ConeSound fields as arguments: the PointSound position, front and back distance attenuation Point2f array, and ConeSound direction vector and Point3f angular attenuation.

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

Constructs a ConeSound node object using all the provided PointSound parameter values, which include a single spherical distance attenuation array, but includes an angular attenuation array.

ConeSound(MediaContainer, float, Point3f, Vector3f)

Constructs a ConeSound node object using only the provided parameter values for sound, overall initial gain, position, and direction.

getAngularAttenuation(float[], float[], float[]): Retrieves angular attenuation including gain and filter using separate arrays
getAngularAttenuation(Point3f[]): Retrieves angular attenuation including gain and filter in a single array
getAngularAttenuationLength(): Retrieves angular attenuation array length.
getDirection(Vector3f): Retrieves this sound's direction and places it in the vector provided.
getDistanceGain(float[], float[], float[], float[]): Gets this sound's elliptical distance gain attenuation values in separate arrays
getDistanceGain(Point2f[], Point2f[]): Gets this sound's elliptical distance attenuation
setAngularAttenuation(float[], float[], float[]): Sets angular attenuation including gain and filter using separate arrays.
setAngularAttenuation(Point2f[]): Sets this sound's angular gain attenuation (not including filter) In this form of setAngularAttenuation, only the angular distances and angular gain scale factors pairs are given.
setAngularAttenuation(Point3f[]): In the second form of setAngularAttenuation, an array of all three values is supplied.
setBackDistanceGain(float[], float[]): Sets this sound's back distance gain attenuation as an array of Point2fs.
setBackDistanceGain(Point2f[]): Sets this sound's back distance gain attenuation - where gain scale factor is applied to sound based on distance listener along the negative sound direction axis from sound source.
setDirection(float, float, float): Sets this sound's direction from the three values provided.
setDirection(Vector3f): Sets this sound's direction from the vector provided.
setDistanceGain(float[], float[], float[], float[]): Sets this sound's distance gain attenuation as an array of Point2fs.
setDistanceGain(Point2f[], Point2f[]): Sets this sound's distance gain elliptical attenuation - where gain scale factor is applied to sound based on distance listener is from sound source.

ALLOW_DIRECTION_READ

 public static final int ALLOW_DIRECTION_READ

Specifies that this ConeSound allows access to its object's direction information.

ALLOW_DIRECTION_WRITE

 public static final int ALLOW_DIRECTION_WRITE

Specifies that this ConeSound allows writing to its object's direction information.

ALLOW_ANGULAR_ATTENUATION_READ

 public static final int ALLOW_ANGULAR_ATTENUATION_READ

Specifies that this ConeSound allows access to its object's cone params information.

ALLOW_ANGULAR_ATTENUATION_WRITE

 public static final int ALLOW_ANGULAR_ATTENUATION_WRITE

Specifies that this ConeSound allows writing to its object's cone params information.

ConeSound

 public ConeSound()

Constructs a ConeSound node object that includes the defaults for a PointSound object plus the following defaults for its own fields:

Direction vector: (0.0, 0.0, 1.0)

Angular attenuation: ((0.0, 1.0), Sound.NO_FILTER,(p/2, 0.0, Sound.NO_FILTER))

ConeSound

 public ConeSound(MediaContainer soundData,
                  float initialGain,
                  Point3f position,
                  Vector3f direction)

Constructs a ConeSound node object using only the provided parameter values for sound, overall initial gain, position, and direction. The remaining fields are set to the default values above. This form uses Point3f as input for its position and direction.

Parameters:: soundData - sound source data associated with this node; initialGain - amplitude scale factor applied to sound; position - 3D location of source; direction - 3D vector defining cones axis

ConeSound

 public ConeSound(MediaContainer soundData,
                  float initialGain,
                  float posX,
                  float posY,
                  float posZ,
                  float dirX,
                  float dirY,
                  float dirZ)

Parameters:: soundData - sound source data; initialGain - amplitude scale factor applied to sound; posX - x coordinate of location of source; posY - y coordinate of location of source; posZ - z coordinate of location of source; dirX - x coordinate cones' axii vector; dirY - y coordinate cones' axii vector; dirZ - z coordinate cones' axii vector

ConeSound

 public ConeSound(MediaContainer soundData,
                  float initialGain,
                  int loopCount,
                  boolean release,
                  boolean continuous,
                  boolean enable,
                  Bounds region,
                  float priority,
                  Point3f position,
                  Point2f frontDistanceAttenuation[],
                  Point2f backDistanceAttenuation[],
                  Vector3f direction)

Constructs a ConeSound node object using all the provided PointSound parameter values. This form uses points or vectors as input for its position, direction, and front/back distance attenuation arrays.

Unlike the single distance gain attenuation array for PointSounds which define spherical areas about the sound source between which gains are linearly interpolated, this directed ConeSound can have two distance gain attenuation arrays that define ellipsoidal attenuation areas. See the setDistanceGain PointSound method for details on how the separate distance and distanceGain arrays are interpreted.

The ConeSound's direction vector and angular measurements are defined in the local coordinate system of the node.

Parameters:: soundData - sound source data associated with this node; initialGain - amplitude scale factor applied to sound; loopCount - number of times sound 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; position - 3D location of source; frontDistanceAttenuation - array of (distance,gain) pairs controlling attenuation values along the positive direction axis; backDistanceAttenuation - array of (distance,gain) pairs controlling attenuation values along the negative direction axis; direction - vector defining cones' axii

ConeSound

 public ConeSound(MediaContainer soundData,
                  float initialGain,
                  int loopCount,
                  boolean release,
                  boolean continuous,
                  boolean enable,
                  Bounds region,
                  float priority,
                  float posX,
                  float posY,
                  float posZ,
                  float frontDistance[],
                  float frontDistanceGain[],
                  float backDistance[],
                  float backDistanceGain[],
                  float dirX,
                  float dirY,
                  float dirZ)

Constructs a ConeSound node object using the provided parameter values. This form uses individual float parameters for the elements of the position, direction and two distance attenuation arrays. Unlike the single distance gain attenuation array for PointSounds which define spherical areas about the sound source between which gains are linearly interpolated, this directed ConeSound can have two distance gain attenuation arrays that define ellipsoidal attenuation areas. See the setDistanceGain PointSound method for details on how the separate distance and distanceGain arrays are interpreted. The ConeSound's direction vector and angular measurements are defined in the local coordinate system of the node.

Parameters:: soundData - sound source data associated with this node.; initialGain - amplitude scale factor applied to sound; loopCount - number of times sound 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; frontDistance - array of front distance values used for attenuation; frontDistanceGain - array of front gain scale factors used for attenuation; backDistance - array of back distance values used for attenuation; backDistanceGain - array of back gain scale factors used for attenuation; dirX - x coordinate cones' axii vector; dirY - y coordinate cones' axii vector; dirZ - z coordinate cones' axii vector

ConeSound

 public ConeSound(MediaContainer soundData,
                  float initialGain,
                  int loopCount,
                  boolean release,
                  boolean continuous,
                  boolean enable,
                  Bounds region,
                  float priority,
                  Point3f position,
                  Point2f distanceAttenuation[],
                  Vector3f direction,
                  Point3f angularAttenuation[])

Constructs a ConeSound node object using all the provided PointSound parameter values, which include a single spherical distance attenuation array, but includes an angular attenuation array. This form uses point and vectors as input for its position, direction, single spherical distanceAttenuation array, and angularAttenuation array. It also accepts arrays of points for the distance attenuation and angular values. Each Point2f in the distanceAttenuation array contains a distance and a gain scale factor. Each Point3f in the angularAttenuation array contains an angular distance, a gain scale factor, and a filtering value (which is currently defined as a simple cutoff frequency).

Parameters:: soundData - sound source data associated with this node; initialGain - amplitude scale factor applied to sound; loopCount - number of times sound 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; position - 3D location of source; distanceAttenuation - array of (distance,gain) pairs controlling attenuation values along the positive direction axis; direction - vector defining cones' axii; angularAttenuation - array of tuples defining angular gain/filtering

ConeSound

 public ConeSound(MediaContainer soundData,
                  float initialGain,
                  int loopCount,
                  boolean release,
                  boolean continuous,
                  boolean enable,
                  Bounds region,
                  float priority,
                  float posX,
                  float posY,
                  float posZ,
                  float distance[],
                  float distanceGain[],
                  float dirX,
                  float dirY,
                  float dirZ,
                  float angle[],
                  float angularGain[],
                  float frequencyCutoff[])

Constructs a ConeSound node object using all the provided PointSound parameter values, which include a single spherical distance attenuation array, but includes an angular attenuation array. This form uses individual float parameters for elements of position, direction, distanceAttenuation array, and angularAttenuation array. It also accepts separate arrays for the distance and gain scale factors components of distance attenuation, and separate arrays for the angular distance, angular gain, and filtering components of angular attenuation. See the setDistanceGain ConeSound method for details on how the separate distance and distanceGain arrays are interpreted. See the setAngularAttenuation ConeSound method for details on how the separate angularDistance, angularGain, and filter arrays are interpreted.

Parameters:: soundData - sound source data associated with this node.; initialGain - amplitude scale factor applied to sound; loopCount - number of times sound 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; distance - array of front distance values used for attenuation; distanceGain - array of front gain scale factors used for attenuation; dirX - x coordinate cones' axii vector; dirY - y coordinate cones' axii vector; dirZ - z coordinate cones' axii vector; angle - array of angle radians for angularAttenuation; angularGain - array of gain scale factors for angularAttenuation; frequencyCutoff - array of lowpass filter values in Hertz

ConeSound

 public ConeSound(MediaContainer soundData,
                  float initialGain,
                  int loopCount,
                  boolean release,
                  boolean continuous,
                  boolean enable,
                  Bounds region,
                  float priority,
                  Point3f position,
                  Point2f frontDistanceAttenuation[],
                  Point2f backDistanceAttenuation[],
                  Vector3f direction,
                  Point3f angularAttenuation[])

Parameters:: soundData - sound source data associated with this node; initialGain - amplitude scale factor applied to sound; loopCount - number of times sound 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; position - 3D location of source; frontDistanceAttenuation - array of (distance,gain) pairs controlling attenuation values along the positive direction axis; backDistanceAttenuation - array of (distance,gain) pairs controlling attenuation values along the negative direction axis; direction - vector defining cones' axii; angularAttenuation - array of tuples defining angular gain/filtering

ConeSound

 public ConeSound(MediaContainer soundData,
                  float initialGain,
                  int loopCount,
                  boolean release,
                  boolean continuous,
                  boolean enable,
                  Bounds region,
                  float priority,
                  float posX,
                  float posY,
                  float posZ,
                  float frontDistance[],
                  float frontDistanceGain[],
                  float backDistance[],
                  float backDistanceGain[],
                  float dirX,
                  float dirY,
                  float dirZ,
                  float angle[],
                  float angularGain[],
                  float frequencyCutoff[])

Parameters:: soundData - sound source data associated with this node.; initialGain - amplitude scale factor applied to sound; loopCount - number of times sound 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; frontDistance - array of front distance values used for attenuation; frontDistanceGain - array of front gain scale factors used for attenuation; backDistance - array of back distance values used for attenuation; backDistanceGain - array of back gain scale factors used for attenuation; dirX - x coordinate cones' axii vector; dirY - y coordinate cones' axii vector; dirZ - z coordinate cones' axii vector; angle - array of angle radians for angularAttenuation; angularGain - array of gain scale factors for angularAttenuation; frequencyCutoff - array of lowpass filter values in Hertz

setDistanceGain

 public final void setDistanceGain(Point2f frontAttenuation[],
                                   Point2f backAttenuation[])

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

Parameters:: frontAttenuation - defined by pairs of (distance,gain-scale-factor); backAttenuation - 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 final void setDistanceGain(float frontDistance[],
                                   float frontGain[],
                                   float backDistance[],
                                   float backGain[])

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

Parameters:: frontDistance - array of monotonically-increasing floats; frontGain - array of non-negative scale factors; backDistance - array of monotonically-increasing floats; backGain - 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

setBackDistanceGain

 public final void setBackDistanceGain(Point2f attenuation[])

Sets this sound's back distance gain attenuation - where gain scale factor is applied to sound based on distance listener along the negative sound direction axis from sound source.

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

setBackDistanceGain

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

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

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

getDistanceGain

 public final void getDistanceGain(Point2f frontAttenuation[],
                                   Point2f backAttenuation[])

Gets this sound's elliptical distance attenuation

Parameters:: frontAttenuation - arrays containing forward distances attenuation pairs; backAttenuation - arrays containing backward distances attenuation pairs
Throws: CapabilityNotSetException: if appropriate capability is not set and this object is part of live or compiled scene graph

getDistanceGain

 public final void getDistanceGain(float frontDistance[],
                                   float frontGain[],
                                   float backDistance[],
                                   float backGain[])

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

Parameters:: frontDistance - array of float distances along the sound axis; fronGain - array of non-negative scale factors associated with front distances; backDistance - array of float negative distances along the sound axis; backGain - array of non-negative scale factors associated with back distances
Throws: CapabilityNotSetException: if appropriate capability is not set and this object is part of live or compiled scene graph

setDirection

 public final void setDirection(Vector3f direction)

Sets this sound's direction from the vector provided.

Parameters:: direction - the new direction
Throws: CapabilityNotSetException: if appropriate capability is not set and this object is part of live or compiled scene graph

setDirection

 public final void setDirection(float x,
                                float y,
                                float z)

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

Parameters:: x - the new x direction; y - the new y direction; z - the new z direction
Throws: CapabilityNotSetException: if appropriate capability is not set and this object is part of live or compiled scene graph

getDirection

 public final void getDirection(Vector3f direction)

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

Parameters:: direction - axis of cones; 'direction' of sound
Throws: CapabilityNotSetException: if appropriate capability is not set and this object is part of live or compiled scene graph

setAngularAttenuation

 public final void setAngularAttenuation(Point2f attenuation[])

Sets this sound's angular gain attenuation (not including filter) In this form of setAngularAttenuation, only the angular distances and angular gain scale factors pairs are given. The filter values for these tuples are implicitly set to Sound.NO_FILTER.

Parameters:: attenuation - array containing angular distance and gain
Throws: CapabilityNotSetException: if appropriate capability is not set and this object is part of live or compiled scene graph

setAngularAttenuation

 public final void setAngularAttenuation(Point3f attenuation[])

In the second form of setAngularAttenuation, an array of all three values is supplied.

Parameters:: attenuation - array containing angular distance, gain and filter
Throws: CapabilityNotSetException: if appropriate capability is not set and this object is part of live or compiled scene graph

setAngularAttenuation

 public final void setAngularAttenuation(float distance[],
                                         float gain[],
                                         float filter[])

Sets angular attenuation including gain and filter using separate arrays. The third form of setAngularAttenuation accepts three separate arrays for these angular attenuation values. These arrays should be of the same length. If the angularGain or filtering array length is greater than angularDistance array length, the array elements beyond the length of the angularDistance array are ignored. If the angularGain or filtering array is shorter than the angularDistance array, the last value of the short array is repeated to fill an array of length equal to angularDistance array.

Parameters:: distance - array containing angular distance; gain - array containing angular gain attenuation; filter - array containing angular low-pass frequency cutoff values
Throws: CapabilityNotSetException: if appropriate capability is not set and this object is part of live or compiled scene graph

getAngularAttenuationLength

 public final int getAngularAttenuationLength()

Retrieves angular attenuation array length. All arrays are forced to same size

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

getAngularAttenuation

 public final void getAngularAttenuation(Point3f attenuation[])

Retrieves angular attenuation including gain and filter in a single array

Parameters:: attenuation - applied to gain when listener is between cones
Throws: CapabilityNotSetException: if appropriate capability is not set and this object is part of live or compiled scene graph

getAngularAttenuation

 public final void getAngularAttenuation(float distance[],
                                         float gain[],
                                         float filter[])

Retrieves angular attenuation including gain and filter using separate arrays

Parameters:: distance - array containing angular distance; gain - array containing angular gain attenuation; filter - array containing angular low-pass frequency cutoff values
Throws: CapabilityNotSetException: if appropriate capability is not set and this object is part of live or compiled scene graph

All Packages  Class Hierarchy  This Package  Previous  Next  Index