javax.media.j3d
Interface AudioDevice

All Known Subinterfaces:
AudioDevice3D, AudioDevice3DL2
All Known Implementing Classes:
com.sun.j3d.audioengines.AudioEngine, com.sun.j3d.audioengines.AudioEngine3D, com.sun.j3d.audioengines.AudioEngine3DL2

public interface AudioDevice

The AudioDevice Class defines and encapsulates the audio device's basic information and characteristics.

A Java3D application running on a particular machine could have one of several options available to it for playing the audio image created by the sound renderer. Perhaps the machine Java3D is executing on has more than one sound card (e.g., one that is a Wave Table Synthesis card and the other with accelerated sound spatialization hardware). Furthermore, suppose there are Java3D audio device drivers that execute Java3D audio methods on each of these specific cards. In such a case the application would have at least two audio device drivers through which the audio could be produced. For such a case the Java3D application must choose the audio device driver with which sound rendering is to be performed. Once this audio device is chosen, the application can additionally select the type of audio playback type the rendered sound image is to be output on. The playback device (headphones or speaker(s)) is physically connected to the port the selected device driver outputs to.

AudioDevice Interface

Instantiating and Registering a New Device

General Rules for calling AudioDevice methods: It is illegal for an application to call any non-query AudioDevice method if the AudioDevice is created then explicitly assigned to a PhysicalEnvironment using PhysicalEnvironment.setAudioDevice(); When either PhysicalEnvironment.setAudioDevice() is called - including when implicitly called by SimpleUniverse.getViewer().createAudioDevice() - the Core creates a SoundScheduler thread which makes calls to the AudioDevice.

If an application creates it's own instance of an AudioDevice and initializes it directly, rather than using PhysicalEnvironment. setAudioDevice(), that application may make any AudioDevice3D methods calls without fear of the Java 3D Core also trying to control the AudioDevice. Under this condition it is safe to call AudioDevice non-query methods.


Field Summary
static int HEADPHONES
          Choosing Headphones as the audio playback type specifies that the audio playback will be through stereo headphones.
static int MONO_SPEAKER
          Choosing a single near-field monoaural speaker as the audio playback type specifies that the audio playback will be through a single speaker some supplied distance away from the listener.
static int STEREO_SPEAKERS
          Choosing a two near-field stereo speakers as the audio playback type specifies that the audio playback will be through stereo speakers some supplied distance away from, and at some given angle to the listener.
 
Method Summary
 boolean close()
          Code to close the device and release resources.
 float getAngleOffsetToSpeaker()
          Get Angle Offset (in radians) To Speaker.
 int getAudioPlaybackType()
          Get Type of Audio Playback Output Device.
 float getCenterEarToSpeaker()
          Get Distance from interaural mid-point between Ears to a Speaker.
 int getChannelsAvailable()
          Query number of channels currently available for use.
 int getChannelsUsedForSound(Sound node)
          Query number of channels that are used, or would be used to render a particular sound node.
 int getTotalChannels()
          Query total number of channels available for sound rendering for this audio device.
 boolean initialize()
          Initialize the audio device.
 void setAngleOffsetToSpeaker(float angle)
          Set Angle Offset (in radians) To Speaker.
 void setAudioPlaybackType(int type)
          Set Type of Audio Playback physical transducer(s) sound is output to.
 void setCenterEarToSpeaker(float distance)
          Set Distance from interaural mid-point between Ears to a Speaker.
 

Field Detail

HEADPHONES

public static final int HEADPHONES
Choosing Headphones as the audio playback type specifies that the audio playback will be through stereo headphones.

See Also:
Constant Field Values

MONO_SPEAKER

public static final int MONO_SPEAKER
Choosing a single near-field monoaural speaker as the audio playback type specifies that the audio playback will be through a single speaker some supplied distance away from the listener.

See Also:
Constant Field Values

STEREO_SPEAKERS

public static final int STEREO_SPEAKERS
Choosing a two near-field stereo speakers as the audio playback type specifies that the audio playback will be through stereo speakers some supplied distance away from, and at some given angle to the listener.

See Also:
Constant Field Values
Method Detail

initialize

public boolean initialize()
Initialize the audio device. Exactly what occurs during initialization is implementation dependent. This method provides explicit control by the user over when this initialization occurs. Initialization must be initiated before any other AudioDevice methods are called.

Returns:
true if initialization was successful without errors

close

public boolean close()
Code to close the device and release resources.

Returns:
true if close of device was successful without errors

setAudioPlaybackType

public void setAudioPlaybackType(int type)
Set Type of Audio Playback physical transducer(s) sound is output to. Valid types are HEADPHONES, MONO_SPEAKER, STEREO_SPEAKERS

Parameters:
type - audio playback type

getAudioPlaybackType

public int getAudioPlaybackType()
Get Type of Audio Playback Output Device.

Returns:
audio playback type

setCenterEarToSpeaker

public void setCenterEarToSpeaker(float distance)
Set Distance from interaural mid-point between Ears to a Speaker.

Parameters:
distance - from interaural midpoint between the ears to closest speaker

getCenterEarToSpeaker

public float getCenterEarToSpeaker()
Get Distance from interaural mid-point between Ears to a Speaker.

Returns:
distance from interaural midpoint between the ears to closest speaker

setAngleOffsetToSpeaker

public void setAngleOffsetToSpeaker(float angle)
Set Angle Offset (in radians) To Speaker.

Parameters:
angle - in radians from head Z axis and vector from center ear to speaker

getAngleOffsetToSpeaker

public float getAngleOffsetToSpeaker()
Get Angle Offset (in radians) To Speaker.

Returns:
angle in radians from head Z axis and vector from center ear to speaker

getTotalChannels

public int getTotalChannels()
Query total number of channels available for sound rendering for this audio device. This returns the maximum number of channels available for Java3D sound rendering for all sound sources.

Returns:
total number of channels that can be used for this audio device

getChannelsAvailable

public int getChannelsAvailable()
Query number of channels currently available for use. During rendering, when sound nodes are playing, this method returns the number of channels still available to Java3D for rendering additional sound nodes.

Returns:
total number of channels current available

getChannelsUsedForSound

public int getChannelsUsedForSound(Sound node)
Query number of channels that are used, or would be used to render a particular sound node. This method returns the number of channels needed to render a particular Sound node. The return value is the same no matter if the Sound is currently active and enabled (being played) or is inactive.

Returns:
number of channels a particular Sound node is using or would used if enabled and activated (rendered).