javax.microedition.amms.control.audio3d
Interface DistanceAttenuationControl

All Superinterfaces:

javax.microedition.media.Control

public interface DistanceAttenuationControl
extends javax.microedition.media.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,
• R_min is the minimum distance, below which the distance gain is clipped to its maximum value of 1.0,
• R_max 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 >= R_max remains constant at its value for R = R_max,
• muteAfterMax is true implies that the distance gain is clipped to zero for values of R >= R_max, and
• RolloffFactor 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 setParameters 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 >= R_max.)

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

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 = true
rolloffFactor = 1000 thousandths (=1.0)

See Also:

Control, Player, LocationControl

Method Summary

int	getMaxDistance() Returns the maximum distance.
int	getMinDistance() Returns the distance where the source is loudest.
boolean	getMuteAfterMax() Returns how the distance gain behaves for distances beyond the maximum distance.
int	getRolloffFactor() Returns the rolloff factor for the distance gain.
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:

java.lang.IllegalArgumentException - if maxDistance <= minDistance, minDistance <= 0, maxDistance <= 0 or rolloffFactor < 0

getMinDistance

int getMinDistance()

Returns the distance where the source is loudest. The gain does not increase if the distance gets smaller than this.

Returns:

the minimum distance in millimeters

See Also:

setParameters(int, int, boolean, int)

getMaxDistance

int getMaxDistance()

Returns the maximum distance. 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.

Returns:

the maximum distance in millimeters

See Also:

setParameters(int, int, boolean, int)

getMuteAfterMax

boolean getMuteAfterMax()

Returns how the distance gain behaves for distances beyond the maximum distance.

Returns:

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

See Also:

setParameters(int, int, boolean, int)

getRolloffFactor

int getRolloffFactor()

Returns the rolloff factor for the distance gain.

Returns:

the rolloff factor as an exponent specified in thousandths

See Also:

setParameters(int, int, boolean, int)