javax.microedition.amms.control.audio3d
Interface LocationControl

All Superinterfaces:

javax.microedition.media.Control

public interface LocationControl

extends javax.microedition.media.Control

LocationControl is an interface for manipulating the virtual location of an object (usually a SoundSource3D or the listener via the Spectator) in the virtual acoustic space.

Location

Location is a representation of a place in a virtual acoustic space.

Location is defined in right-handed coordinates.

This interface allows the location to be specified in a 3-dimensional space with setCartesian() or setSpherical() methods.

Spatialization

One of the main features of this API is the possibility to locate sound sources in a virtual space. Humans can perceive the direction of a sound source quite accurately using certain physical properties of the sound arriving to the ears. These so-called location cues can be simulated by a computer and thus a virtual direction for the arriving sound can be created.

The distance has an effect of attenuating the far positioned source and also lowering the relative level of the source compared to the reverberation level. Therefore, giving just the direction of the source is not enough, because the distance of the source can also be simulated.

In this API, the sound sources have a location primarily defined in 3D coordinates so that both the distance and the direction are specified by just giving the XYZ coordinates. The coordinate system used is right-handed. Giving the location using radius and angles instead of XYZ coordinates is an optional method. The direction where the sound is actually heard from depends both on the location of the sound source and the location of the listener.

Default Values

The default location of all location controls (whether the application has obtained them or not) is the origin:

x = 0
y = 0
z = 0

See Also:

Control, Player, Spectator, SoundSource3D, OrientationControl, CommitControl

Method Summary

int[]	getCartesian() Gets the coordinates of the current location.
void	setCartesian(int x, int y, int z) Moves the object to the new location.
void	setSpherical(int azimuth, int elevation, int radius) Moves the object to the new location.

Method Detail

setCartesian

public void setCartesian(int x,
                         int y,
                         int z)

Moves the object to the new location.

Sets the location using cartesian right-handed coordinates that are relative to the origin.

Parameters:

x - the x-coordinate of the new location in millimeters

y - the y-coordinate of the new location in millimeters

z - the z-coordinate of the new location in millimeters

See Also:

getCartesian()

setSpherical

public void setSpherical(int azimuth,
                         int elevation,
                         int radius)

Moves the object to the new location.

Sets the new location using spherical coordinates. The negative z-axis is the reference. That is, a location where both azimuth and elevation are zero, is on the negative z-axis. Radius is defined in millimeters.

An illustration of the angles when the listener (LocationControl and OrientationControl of the Spectator) is kept in the origin with default orientation and just the SoundSource3D, namely P, is moved using its LocationControl.setSpherical method.

Parameters:

azimuth - the azimuth angle of the new location in degrees. The azimuth is measured from the negative z-axis in the direction of the x-axis.

elevation - the elevation angle of the new location in degrees. The elevation is measured from the x-z-plane in the direction of the y-axis.

radius - the radius of the new location from the origin in millimeters

Throws:

java.lang.IllegalArgumentException - if radius < 0

getCartesian

public int[] getCartesian()

Gets the coordinates of the current location.

Returns:

the x, y and z coordinates of the current location in millimeters