javax.microedition.amms.control.audio3d
Interface DirectivityControl

All Superinterfaces:

OrientationControl, Control

public interface DirectivityControl
extends OrientationControl

DirectivityControl adds to OrientationControl a method for setting the directivity pattern of a sound source.

The following diagram illustrates (in 2D) how the parameters of the DirectivityControl affect the intensity of sound perceived by the Spectator at various angles from the sound source's axis of orientation (defined by DirectivityControl's methods inherited from OrientationControl). In reality, minAngle and maxAngle define two sound cones which radiate outwards in 3D space from the location of the sound source, rather than sectors as shown in the diagram. Note that the actual volume perceived also attenuates with distance from the sound source, according to the parameters of the DistanceAttenuationControl.

Default Values

The default values for the properties of all directivity controls (whether the application has obtained them or not) are: minAngle = 360 degrees maxAngle = 360 degreesrearLevel = 0 mB

See Also:

Control, OrientationControl, DistanceAttenuationControl

Since:

BlackBerry API 5.0.0

Method Summary
int[]	getParameters() Gets the directivity pattern of a sound source.
void	setParameters(int minAngle, int maxAngle, int rearLevel) Sets all the directivity parameters simultaneously.

Methods inherited from interface javax.microedition.amms.control.audio3d.OrientationControl

getOrientationVectors, setOrientation, setOrientation

Method Detail

setParameters

void setParameters(int minAngle,
                   int maxAngle,
                   int rearLevel)

Sets all the directivity parameters simultaneously.

The minAngle and maxAngle parameters define the inner and outer sound cones, respectively. The symmetry axis of the cones is the orientation axis defined by setOrientation(int heading, int pitch, int roll) (or the front vector defined by setOrientation(int[] frontVector, int[] aboveVector)). The effect of the cones depends on the location of the Spectator as follows:

Within the inner cone, the sound from a source is not attenuated due to directivity and is therefore at its loudest.Between the inner and outer cones, the level of the perceived sound decreases linearly as the angle of the listener from the axis of orientation of the sound source increases.Outside of the outer cone, the sound is heard at a level rearLevel relative to the level inside the inner cone.

The sound can be completely muted in the region outside the outer cone by setting rearLevel to Integer.MIN_VALUE. (In practice, the implementation will probably then interpolate linearly in the logarithmic (level) domain from the maximum level (at minAngle) to the quietest level it supports (at maxAngle), which will be approximately -90 dB if the native processing uses 16-bit samples, or about -140 dB for 24-bit samples.)

Setting the rearLevel to 0 or setting both angles to 360 degrees causes the sound source to revert once again to being an omnidirectional source, which is the default stateno directivity attenuation.

NOTE: If minAngle = maxAngle then when the Spectator happens to be located exactly on the common surface of both cones, the perceived level is unattenuated (as though the Spectator were within the inner cone), this being consistent with the omnidirectional behaviour where minAngle = maxAngle = 360. In the exceptional case that minAngle = maxAngle = 0, the perceived level is always maximally attenuated (as though the Spectator were within the outer cone). In all cases the implementation should ensure that the transition from the inner cone to the outer cone is smooth.

Parameters:

minAngle - the total angle in degrees (a value from 0 to 360 inclusive), subtended by the inner cone at its vertex

maxAngle - the total angle in degrees (a value from 0 to 360 inclusive, where minAngle = maxAngle), subtended by the outer cone at its vertex

rearLevel - the level in millibels (mB, 1 mB = 1/100 dB), at which the sound from a source will be heard at maxAngle and wider angles; must be a non-positive value. Setting the rearLevel to 0 makes the source omnidirectional.

Throws:

IllegalArgumentException - if minAngle and maxAngle are not between 0 and 360inclusive

IllegalArgumentException - if maxAngle minAngle

IllegalArgumentException - if rearLevel 0

Since:

BlackBerry API 5.0.0

getParameters

int[] getParameters()

Gets the directivity pattern of a sound source.

Returns:

an array of type int[3] containing the minAngle, maxAngle and rearLevel parameters, in that order

Since:

BlackBerry API 5.0.0