javax.microedition.amms.control.audio3d
Interface DistanceAttenuationControl

All Superinterfaces:

Control

public interface DistanceAttenuationControl
extends Control

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.

Distance Attenuation

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)

Since:

BlackBerry API 5.0.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

setParameters

void setParameters(int minDistance,
                   int maxDistance,
                   boolean muteAfterMax,
                   int rolloffFactor)

Sets all the 3D audio distance attenuation parameters simultaneously.

Distances are specified in millimeters.

Parameters:

minDistance - the minimum distance, below which the distance gain is clipped to its maximum value of 1.0

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

Throws:

IllegalArgumentException - if maxDistance = minDistance, minDistance = 0, maxDistance = 0 or rolloffFactor 0

Since:

BlackBerry API 5.0.0

getMinDistance

int getMinDistance()

Returns:

The gain does not increase if the distance gets smaller than this.

the minimum distance in millimeters

Since:

BlackBerry API 5.0.0

getMaxDistance

int getMaxDistance()

Returns:

At the maximum distance, the gain does not decrease any more. The exact behavior of the gain at distances beyond the maximum distance depends on the value of muteAfterMax.

the maximum distance in millimeters

Since:

BlackBerry API 5.0.0

getMuteAfterMax

boolean getMuteAfterMax()

Returns:

the maximum distance.

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

Since:

BlackBerry API 5.0.0

getRolloffFactor

int getRolloffFactor()

Returns:

the rolloff factor as an exponent specified in thousandths

Since:

BlackBerry API 5.0.0