

PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
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
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 piecewise 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 monotonicallyincreasing distances from the sound source origin along the position direction vector. A back distance attenuation array (if given) defines monotonicallyincreasing 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 the frontDistance[i] gain values.
Gain scale factors are associated with distances from the listener to the sound source via an array of (distance, gainscalefactor) 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.
The getDistanceGainLength method defined for PointSound returns the length of the all distance gain attenuation arrays, including the back distance gain arrays. Arrays passed into getDistanceGain methods should all be at least this size.
Direction Methods
Angular Attenuation
This attenuation is defined as a triple of (angular distance, gainscalefactor, 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 listenersoundposition vector and a sound's direction vector is less than the 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 the distance from the listenersoundposition vector and the sound's direction vector is greater than the last distance in the array, the last gain scale factor and last filter are applied to the sound source.
Distance elements in this array of points is a monotonicallyincreasing 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 monotonicallydecreasing, they do not have to be. The filter (for now) is a single simple frequency cutoff value.
The getAngularAttenuationArrayLength method returns the length of the angular attenuation arrays. Arrays passed into getAngularAttenuation methods should all be at least this size.
Field Summary  

static int 
ALLOW_ANGULAR_ATTENUATION_READ
Specifies that this ConeSound allows access to its object's cone params information. 
static int 
ALLOW_ANGULAR_ATTENUATION_WRITE
Specifies that this ConeSound allows writing to its object's cone params information. 
static int 
ALLOW_DIRECTION_READ
Specifies that this ConeSound allows access to its object's direction information. 
static int 
ALLOW_DIRECTION_WRITE
Specifies that this ConeSound allows writing to its object's direction information. 
Fields inherited from class javax.media.j3d.PointSound 

ALLOW_DISTANCE_GAIN_READ, ALLOW_DISTANCE_GAIN_WRITE, ALLOW_POSITION_READ, ALLOW_POSITION_WRITE 
Constructor Summary  

ConeSound()
Constructs and initializes a new ConeSound node using default parameters. 

ConeSound(MediaContainer soundData,
float initialGain,
float posX,
float posY,
float posZ,
float dirX,
float dirY,
float dirZ)
Constructs a ConeSound node object using only the provided parameter values for sound, overall initial gain, position, and direction. 

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. 

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)
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 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. 

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. 

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)
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 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. 

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. 
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 
getAngularAttenuation(float[] distance,
float[] gain,
float[] filter)
Copies the array of attenuation values from this sound, including gain and filter, into the separate arrays. 
void 
getAngularAttenuation(Point3f[] attenuation)
Copies the array of attenuation values from this sound, including gain and filter, into the specified array. 
int 
getAngularAttenuationLength()
Retrieves angular attenuation array length. 
void 
getDirection(Vector3f direction)
Retrieves this sound's direction and places it in the vector provided. 
void 
getDistanceGain(float[] frontDistance,
float[] frontGain,
float[] backDistance,
float[] backGain)
Gets this sound's elliptical distance gain attenuation values in separate arrays. 
void 
getDistanceGain(Point2f[] frontAttenuation,
Point2f[] backAttenuation)
Gets this sound's elliptical distance attenuation. 
void 
setAngularAttenuation(float[] distance,
float[] gain,
float[] filter)
Sets angular attenuation including gain and filter using separate arrays. 
void 
setAngularAttenuation(Point2f[] attenuation)
Sets this sound's angular gain attenuation (not including filter). 
void 
setAngularAttenuation(Point3f[] attenuation)
In the second form of setAngularAttenuation, an array of all three values is supplied. 
void 
setBackDistanceGain(float[] distance,
float[] gain)
Sets this sound's back distance gain attenuation as separate arrays. 
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. 
void 
setDirection(float x,
float y,
float z)
Sets this sound's direction from the three values provided. 
void 
setDirection(Vector3f direction)
Sets this sound's direction from the vector provided. 
void 
setDistanceGain(float[] frontDistance,
float[] frontGain,
float[] backDistance,
float[] backGain)
Sets this sound's distance gain attenuation as an array of Point2fs. 
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. 
Methods inherited from class javax.media.j3d.PointSound 

getDistanceGain, getDistanceGain, getDistanceGainLength, getPosition, setDistanceGain, setDistanceGain, setPosition, setPosition 
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, getCapability, getCapabilityIsFrequent, getName, getUserData, isCompiled, isLive, setCapability, setCapabilityIsFrequent, setName, setUserData, toString 
Methods inherited from class java.lang.Object 

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait 
Field Detail 

public static final int ALLOW_DIRECTION_READ
public static final int ALLOW_DIRECTION_WRITE
public static final int ALLOW_ANGULAR_ATTENUATION_READ
public static final int ALLOW_ANGULAR_ATTENUATION_WRITE
Constructor Detail 

public ConeSound()
public ConeSound(MediaContainer soundData, float initialGain, Point3f position, Vector3f direction)
soundData
 sound source data associated with this nodeinitialGain
 amplitude scale factor applied to soundposition
 3D location of sourcedirection
 3D vector defining cone's axispublic ConeSound(MediaContainer soundData, float initialGain, float posX, float posY, float posZ, float dirX, float dirY, float dirZ)
soundData
 sound source datainitialGain
 amplitude scale factor applied to soundposX
 x coordinate of location of sourceposY
 y coordinate of location of sourceposZ
 z coordinate of location of sourcedirX
 x coordinate cones' axii vectordirY
 y coordinate cones' axii vectordirZ
 z coordinate cones' axii vectorpublic 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)
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.
soundData
 sound source data associated with this nodeinitialGain
 amplitude scale factor applied to soundloopCount
 number of times sound is loopedrelease
 flag denoting playing sound to endcontinuous
 denotes that sound silently plays when disabledenable
 sound switched on/offregion
 scheduling boundspriority
 playback ranking valueposition
 3D location of sourcefrontDistanceAttenuation
 array of (distance,gain) pairs controlling
attenuation values along the positive direction axisbackDistanceAttenuation
 array of (distance,gain) pairs controlling
attenuation values along the negative direction axisdirection
 vector defining cones' axiipublic 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)
soundData
 sound source data associated with this nodeinitialGain
 amplitude scale factor applied to soundloopCount
 number of times sound 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 sourcefrontDistance
 array of front distance values used for attenuationfrontDistanceGain
 array of front gain scale factors used for attenuationbackDistance
 array of back distance values used for attenuationbackDistanceGain
 array of back gain scale factors used for attenuationdirX
 x coordinate cones' axii vectordirY
 y coordinate cones' axii vectordirZ
 z coordinate cones' axii vectorpublic 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)
soundData
 sound source data associated with this nodeinitialGain
 amplitude scale factor applied to soundloopCount
 number of times sound is loopedrelease
 flag denoting playing sound to endcontinuous
 denotes that sound silently plays when disabledenable
 sound switched on/offregion
 scheduling boundspriority
 playback ranking valueposition
 3D location of sourcedistanceAttenuation
 array of (distance,gain) pairs controlling
attenuation values along the positive direction axisdirection
 vector defining cones' axiiangularAttenuation
 array of tuples defining angular gain/filteringpublic 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)
soundData
 sound source data associated with this nodeinitialGain
 amplitude scale factor applied to soundloopCount
 number of times sound 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 sourcedistance
 array of front distance values used for attenuationdistanceGain
 array of front gain scale factors used for attenuationdirX
 x coordinate cones' axii vectordirY
 y coordinate cones' axii vectordirZ
 z coordinate cones' axii vectorangle
 array of angle radians for angularAttenuationangularGain
 array of gain scale factors for angularAttenuationfrequencyCutoff
 array of lowpass filter values in Hertzpublic 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)
soundData
 sound source data associated with this nodeinitialGain
 amplitude scale factor applied to soundloopCount
 number of times sound is loopedrelease
 flag denoting playing sound to endcontinuous
 denotes that sound silently plays when disabledenable
 sound switched on/offregion
 scheduling boundspriority
 playback ranking valueposition
 3D location of sourcefrontDistanceAttenuation
 array of (distance,gain) pairs controlling
attenuation values along the positive direction axisbackDistanceAttenuation
 array of (distance,gain) pairs controlling
attenuation values along the negative direction axisdirection
 vector defining cones' axiiangularAttenuation
 array of tuples defining angular gain/filteringpublic 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)
soundData
 sound source data associated with this nodeinitialGain
 amplitude scale factor applied to soundloopCount
 number of times sound 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 sourcefrontDistance
 array of front distance values used for attenuationfrontDistanceGain
 array of front gain scale factors used for attenuationbackDistance
 array of back distance values used for attenuationbackDistanceGain
 array of back gain scale factors used for attenuationdirX
 x coordinate cones' axii vectordirY
 y coordinate cones' axii vectordirZ
 z coordinate cones' axii vectorangle
 array of angle radians for angularAttenuationangularGain
 array of gain scale factors for angularAttenuationfrequencyCutoff
 array of lowpass filter values in HertzMethod Detail 

public void setDistanceGain(Point2f[] frontAttenuation, Point2f[] backAttenuation)
frontAttenuation
 defined by pairs of (distance,gainscalefactor)backAttenuation
 defined by pairs of (distance,gainscalefactor)
CapabilityNotSetException
 if appropriate capability is
not set and this object is part of live or compiled scene graphpublic void setDistanceGain(float[] frontDistance, float[] frontGain, float[] backDistance, float[] backGain)
frontDistance
 array of monotonicallyincreasing floatsfrontGain
 array of nonnegative scale factorsbackDistance
 array of monotonicallyincreasing floatsbackGain
 array of nonnegative scale factors
CapabilityNotSetException
 if appropriate capability is
not set and this object is part of live or compiled scene graphpublic void setBackDistanceGain(Point2f[] attenuation)
attenuation
 defined by pairs of (distance,gainscalefactor)
CapabilityNotSetException
 if appropriate capability is
not set and this object is part of live or compiled scene graphpublic void setBackDistanceGain(float[] distance, float[] gain)
distance
 array of monotonicallyincreasing floatsgain
 array of nonnegative scale factors
CapabilityNotSetException
 if appropriate capability is
not set and this object is part of live or compiled scene graphpublic void getDistanceGain(Point2f[] frontAttenuation, Point2f[] backAttenuation)
frontAttenuation
 arrays containing forward distances
attenuation pairsbackAttenuation
 arrays containing backward distances
attenuation pairs
CapabilityNotSetException
 if appropriate capability is
not set and this object is part of live or compiled scene graphpublic void getDistanceGain(float[] frontDistance, float[] frontGain, float[] backDistance, float[] backGain)
frontDistance
 array of float distances along the sound axisfrontGain
 array of nonnegative scale factors associated with
front distancesbackDistance
 array of float negative distances along the sound
axisbackGain
 array of nonnegative scale factors associated with
back distances
CapabilityNotSetException
 if appropriate capability is
not set and this object is part of live or compiled scene graphpublic void setDirection(Vector3f direction)
direction
 the new direction
CapabilityNotSetException
 if appropriate capability is
not set and this object is part of live or compiled scene graphpublic void setDirection(float x, float y, float z)
x
 the new x directiony
 the new y directionz
 the new z direction
CapabilityNotSetException
 if appropriate capability is
not set and this object is part of live or compiled scene graphpublic void getDirection(Vector3f direction)
direction
 axis of cones; 'direction' of sound
CapabilityNotSetException
 if appropriate capability is
not set and this object is part of live or compiled scene graphpublic void setAngularAttenuation(Point2f[] attenuation)
attenuation
 array containing angular distance and gain
CapabilityNotSetException
 if appropriate capability is
not set and this object is part of live or compiled scene graphpublic void setAngularAttenuation(Point3f[] attenuation)
attenuation
 array containing angular distance, gain, and filter
CapabilityNotSetException
 if appropriate capability is
not set and this object is part of live or compiled scene graphpublic void setAngularAttenuation(float[] distance, float[] gain, float[] filter)
distance
 array containing angular distancegain
 array containing angular gain attenuationfilter
 array containing angular lowpass frequency cutoff values
CapabilityNotSetException
 if appropriate capability is
not set and this object is part of live or compiled scene graphpublic int getAngularAttenuationLength()
CapabilityNotSetException
 if appropriate capability is
not set and this object is part of live or compiled scene graphpublic void getAngularAttenuation(Point3f[] attenuation)
attenuation
 the array to receive the attenuation values
applied to gain when listener is between cones
CapabilityNotSetException
 if appropriate capability is
not set and this object is part of live or compiled scene graphpublic void getAngularAttenuation(float[] distance, float[] gain, float[] filter)
distance
 array containing angular distancegain
 array containing angular gain attenuationfilter
 array containing angular lowpass frequency cutoff values
CapabilityNotSetException
 if appropriate capability is
not set and this object is part of live or compiled scene graphpublic Node cloneNode(boolean forceDuplicate)
cloneTree
to duplicate the current node.
cloneNode
in class PointSound
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.Node.cloneTree()
,
Node.cloneNode(boolean)
,
Node.duplicateNode(javax.media.j3d.Node, boolean)
,
NodeComponent.setDuplicateOnCloneTree(boolean)
public void duplicateNode(Node originalNode, boolean forceDuplicate)
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.
duplicateNode
in class PointSound
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.
java.lang.ClassCastException
 if originalNode is not an instance of
ConeSound
Node.cloneTree()
,
Node.cloneNode(boolean)
,
NodeComponent.setDuplicateOnCloneTree(boolean)


PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 