javax.microedition.amms.control.audio3d
Interface OrientationControl

All Superinterfaces:

javax.microedition.media.Control

All Known Subinterfaces:

DirectivityControl, MacroscopicControl

public interface OrientationControl

extends javax.microedition.media.Control

OrientationControl is an interface for manipulating the virtual orientation of an object in the virtual acoustical space. Usually, the object is either the listener via the Spectator or a source via a SoundSource3D. In the case of a sound source, subinterfaces DirectivityControl and/or MacroscopicControl are used instead of the superinterface OrientationControl.

Orientation

Orientation is a representation of a direction in a virtual acoustical space. Orientation is defined in rotation angles around coordinate axes. Positive rotation directions around the coordinate axes are counterclockwise when looking towards the origin from a positive coordinate position on each axis. The initial orientation is towards the negative Z-axis. Orientation is defined in three angles: heading that represents rotation around the Y-axis, pitch that represents rotation around the X-axis, and roll that represents rotation around the Z-axis. Orientation is applied in the following order: heading, pitch, and roll. Therefore, notice that heading rotates the X-axis and therefore affects the pitch, and similarly heading and pitch rotate the Z-axis and therefore affect the roll.

Orientation is defined in right-handed coordinates.

Default Values

The default orientation of all orientation controls (whether the application has obtained them or not) is pointing directly towards the negative Z-axis:

frontVector = (0, 0, -1000)
upVector = (0, 1000, 0)

In rotation angles this is equivalent to:

heading = 0
pitch = 0
roll = 0

See Also:

Control, DirectivityControl, LocationControl

Method Summary

int[]	getOrientationVectors() Gets the orientation of the object using two vectors.
void	setOrientation(int[] frontVector, int[] aboveVector) Turns the object to the new orientation.
void	setOrientation(int heading, int pitch, int roll) Turns the object to the new orientation.

Method Detail

setOrientation

public void setOrientation(int heading,
                           int pitch,
                           int roll)

Turns the object to the new orientation.

The new orientation is given using rotation angles. A zero vector corresponds to the orientation pointing directly towards the negative Z-axis. Orientation is applied in the following order: heading, pitch, and roll. Therefore, notice that heading rotates the X-axis and therefore affects the pitch, and similarly heading and pitch rotate the Z-axis and therefore affect the roll.

Parameters:

heading - the rotation around the Y-axis in degrees

pitch - the rotation around the X-axis in degrees

roll - the rotation around the Z-axis in degrees

setOrientation

public void setOrientation(int[] frontVector,
                           int[] aboveVector)
                    throws java.lang.IllegalArgumentException

Turns the object to the new orientation.

The orientation is specified using two vectors, one specifying the direction of the front vector of the object in world coordinates, and another specifying the "above" vector of the object. The right and up vectors of the object are calculated by first calculating the "right" vector as the cross product of the front vector and the "above" vector, and then the up vector as a cross product of the right and front vectors. (The magnitudes of the front and up vectors may be adjusted by the implementation.)

The specified vectors need not be unit vectors (i.e. normalized): they can have any non-zero magnitude.

Parameters:

frontVector - a 3-element array specifying the front vector of the object in the world coordinate system

aboveVector - a 3-element array specifying the "above" vector mentioned above

Throws:

java.lang.IllegalArgumentException - if any argument has fewer than or greater than 3 elements in the array; or if any argument is the zero vector; or if the specified vectors are parallel. (The orientation of the object will remain unchanged.)

getOrientationVectors

public int[] getOrientationVectors()

Gets the orientation of the object using two vectors.

Returns:

a 6-element array that has first the front vector and then the up vector

See Also:

setOrientation(int[] frontVector, int[] aboveVector)