

PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
public interface DistanceAttenuationControl
DistanceAttenuationControl
is an interface for controlling how
the sound from a sound source is attenuated with its distance from the Spectator
. If the
control is supported, it can be retrieved from a SoundSource3D
.
As the distance R of a sound source from the listener increases, its Distance Gain decreases accordingly, to model the reality that sounds which are further away tend to sound quieter than sounds that are nearby. The formula for Distance Gain is as follows:
where: R is the distance of the sound source from the listener,Rmin is the minimum distance, below which the distance gain is clipped to its maximum value of 1.0,Rmax is the maximum distance, beyond which the distance gain is clipped as follows:muteAfterMax is false implies that the distance gain for values of R= Rmax remains constant at its value for R = Rmax,muteAfterMax is true implies that the distance gain is clipped to zero for values of R= Rmax, andRolloffFactor is an exponent controlling the rate at which the distance gain attenuates with distance.
All of these values are set simultaneously, as arguments to the
 See Also:
Control
,
Player
,
method.
Minimum Distance
By definition, at the minimum distance the distance gain applied to the sound source is 1.0.
Below this distance, as the sound source approaches the listener, the distance gain stays at 1.0.
(The distance gain can never exceed 1.0.)
The following graph illustrates the effect of the minimum distance by comparing the
attenuation curves for two different values of minimum distance: 0.2 m (a good choice for a small
source such as a bee) and 2.0 m (which might be more appropriate for an object such as a car):
(The above graph also demonstrates the effect of setting muteAfterMax equal to
false for values of R= Rmax.)
Rolloff Factor
The rolloff factor is an exponent controlling the rate at which the distance gain
attenuates with distance. An exponent of 1.0 approximates natural distance attenuation and is the
default value. Specifying a higher value, such as 2.0, would make the distance gain get quieter
with distance much more quickly. A lower value, such as 0.5, would make the gain attenuate more
gradually.
NOTE: It is even possible to specify a value 0.0 (no attenuation), which
effectively holds the distance gain constant at its maximum value of 1.0, right up to the maximum
distance (and even beyond that, if muteAfterMax is false).
The following graph illustrates the effect of the rolloff factor by comparing the attenuation
curves for two different rolloff factor values, 1.0 and 2.0:
(The above graph also demonstrates the effect of setting muteAfterMax equal to
true for values of R= Rmax.)
Default Values
The default values for the properties of all distance
attenuation controls (whether
the application has obtained them or not) are:
minDistance = 1000 mm maxDistance = Integer.MAX_VALUE mm muteAfterMax = truerolloffFactor = 1000 thousandths (=1.0)
Method Summary  

int 
getMaxDistance()


int 
getMinDistance()


boolean 
getMuteAfterMax()


int 
getRolloffFactor()


void 
setParameters(int minDistance,
int maxDistance,
boolean muteAfterMax,
int rolloffFactor)
Sets all the 3D audio distance attenuation parameters simultaneously. 
Method Detail 

void setParameters(int minDistance, int maxDistance, boolean muteAfterMax, int rolloffFactor)
Distances are specified in millimeters.
minDistance
 the minimum distance, below which the distance
gain is clipped to its maximum value of 1.0maxDistance
 the maximum distance, beyond which the distance gain does not decrease any
more. The exact behaviour of the gain at distances beyond the maximum distance
depends on the value of the muteAfterMax
.muteAfterMax
 a boolean determining how the distance gain behaves at distances greater
than maxDistance
:
true
if beyond the maximum distance the source is silent;
false
if beyond the maximum distance the source's gain is held constant at the
level at the maximum distance.rolloffFactor
 the rolloff factor, specified in thousandths
(1000
representing a rolloff factor of 1.0, 2000
representing 2.0
and 500
representing 0.5). Higher values cause the distance gain to attenuate
more quickly.
IllegalArgumentException
 if maxDistance = minDistance
,
minDistance = 0
, maxDistance = 0
or
rolloffFactor 0
int getMinDistance()
the minimum distance in millimeters
int getMaxDistance()
muteAfterMax
.
the maximum distance in millimeters
boolean getMuteAfterMax()
true if beyond the maximum distance the source is silent, or false if beyond the maximum distance the source's gain is held constant at the level at the maximum distance
int getRolloffFactor()
the rolloff factor as an exponent specified in thousandths


PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
Copyright 19992011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal