javax.microedition.amms.control.audio3d
Interface LocationControl

All Superinterfaces:
Control

public interface LocationControl
extends 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 = 0z = 0

See Also:
Control, Player, Spectator, SoundSource3D, OrientationControl, CommitControl
Since:
BlackBerry API 5.0.0

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

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
Since:
BlackBerry API 5.0.0

setSpherical

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.

To maximize the precision of the representation, this method should only be used at relatively small radius values. Please use setCartesian when larger radii are needed.

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:
IllegalArgumentException - if radius 0
Since:
BlackBerry API 5.0.0

getCartesian

int[] getCartesian()
Gets the coordinates of the current location.

Returns:
the x, y and z coordinates of the current location in millimeters
Since:
BlackBerry API 5.0.0





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.