AudioDevice3D (Java 3D Javadocs 0-SNAPSHOT API)

All Superinterfaces:

AudioDevice

All Known Subinterfaces:

AudioDevice3DL2

All Known Implementing Classes:

AudioEngine3D, AudioEngine3DL2, JavaSoundMixer
```
public interface AudioDevice3D
extends AudioDevice
```
The AudioDevice3D class defines a 3D audio device that is used to set sound and aural attributes.
After the application chooses the AudioDevice3D that Java3D sound is to be rendered on, the Java 3D Sound Scheduler will call these methods for all active sounds to render them on the audio device.
The intent is for this interface to be implemented by AudioDevice Driver developers using a software or hardware sound engine of their choice.
Methods in this interface provide the Java3D Core a generic way to set and query the audio device the application has chosen audio rendering to be performed on. Methods in this interface include:
Sound Types
Sound types match the Sound node classes defined for Java 3D core for BackgroundSound, PointSound, and ConeSound. The type of sound a sample is loaded as determines which methods affect it.
Sound Data Types
Samples can be processed as streaming or buffered data. Fully spatializing sound sources may require data to be buffered.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`BACKGROUND_SOUND` Specifies the sound type as background sound.
`static int`	`BUFFERED_AUDIO_DATA` Sound data specified as Buffered is copied by the AudioDevice driver implementation.
`static int`	`CONE_SOUND` Specifies the sound type as cone sound.
`static int`	`POINT_SOUND` Specifies the sound type as point sound.
`static int`	`STREAMING_AUDIO_DATA` Sound data specified as Streaming is not copied by the AudioDevice driver implementation.

Fields inherited from interface org.scijava.java3d.AudioDevice
HEADPHONES, MONO_SPEAKER, STEREO_SPEAKERS

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`clearSound(int index)` Requests that the AudioDevice free all resources associated with sample with index id.
`int`	`getNumberOfChannelsUsed(int index)` Retrieves the number of channels (on executing audio device) that this sound is using, if it is playing, or is expected to use if it were begun to be played.
`int`	`getNumberOfChannelsUsed(int index, boolean muted)` Retrieves the number of channels (on executing audio device) that this sound is using, if it is playing, or is projected to use if it were to be started playing.
`long`	`getSampleDuration(int index)` Returns the duration in milliseconds of the sound sample, if this information can be determined.
`long`	`getStartTime(int index)` Returns the system time of when the sound was last "started".
`void`	`muteSample(int index)` Makes the sample 'play silently'.
`void`	`pauseSample(int index)` Temporarily stops a cached sample from playing without resetting the sample's current pointer back to the beginning of the sound data so that it can be unpaused at a later time from the same location in the sample when the pause was initiated.
`int`	`prepareSound(int soundType, MediaContainer soundData)` Accepts a reference to the MediaContainer which contains a reference to sound data and information about the type of data it is.
`void`	`setAngularAttenuation(int index, int filterType, double[] angle, float[] attenuationScaleFactor, float[] filterCutoff)` Sets this sound's angular gain attenuation (including filter) by defining corresponding arrays containing angular offsets from the sound's axis, gain scale factors, and frequency cutoff applied to all active directional sounds.
`void`	`setDirection(int index, Vector3d direction)` Sets this sound's direction from the local coordinate vector provided.
`void`	`setDistanceFilter(int filterType, double[] distance, float[] filterCutoff)` Sets Distance Filter corresponding arrays containing distances and frequency cutoff applied to all active positional sounds.
`void`	`setDistanceGain(int index, double[] frontDistance, float[] frontAttenuationScaleFactor, double[] backDistance, float[] backAttenuationScaleFactor)` Sets this sound's distance gain elliptical attenuation (not including filter cutoff frequency) by defining corresponding arrays containing distances from the sound's origin and gain scale factors applied to all active positional sounds.
`void`	`setFrequencyScaleFactor(float frequencyScaleFactor)` Specifies a scale factor applied to the frequency (or wavelength).
`void`	`setLoop(int index, int count)` Sets a sound's loop count.
`void`	`setPosition(int index, Point3d position)` Sets this sound's location (in Local coordinates) from specified Point.
`void`	`setReflectionCoefficient(float coefficient)` Sets the Reflective Coefficient scale factor applied to distinct low-order early reflections of sound off the surfaces in the region defined by the current listening region.
`void`	`setReverbDelay(float reverbDelay)` Sets the reverberation delay time.
`void`	`setReverbOrder(int reverbOrder)` Sets the reverberation order of reflections.
`void`	`setRolloff(float rolloff)` Changes the speed of sound factor.
`void`	`setSampleGain(int index, float scaleFactor)` Sets the overall gain scale factor applied to data associated with this source to increase or decrease its overall amplitude.
`void`	`setVelocityScaleFactor(float velocityScaleFactor)` Sets the Velocity scale factor applied during Doppler Effect calculation.
`void`	`setView(View reference)` Accepts a reference to the current View.
`void`	`setVworldXfrm(int index, Transform3D trans)` Passes a reference to the concatenated transformation to be applied to local sound position and direction parameters.
`int`	`startSample(int index)` Begins a sound playing on the AudioDevice.
`int`	`stopSample(int index)` Stops the sound on the AudioDevice.
`void`	`unmuteSample(int index)` Makes a silently playing sample audible.
`void`	`unpauseSample(int index)` Restarts the paused sample from the location in the sample where paused.
`void`	`updateSample(int index)` Explicitly updates a Sample.

Methods inherited from interface org.scijava.java3d.AudioDevice
close, getAngleOffsetToSpeaker, getAudioPlaybackType, getCenterEarToSpeaker, getChannelsAvailable, getChannelsUsedForSound, getTotalChannels, initialize, setAngleOffsetToSpeaker, setAudioPlaybackType, setCenterEarToSpeaker

- Field Detail
  - BACKGROUND_SOUND
```
static final int BACKGROUND_SOUND
```
    Specifies the sound type as background sound.
    
    See Also:
    
    Constant Field Values
  - POINT_SOUND
```
static final int POINT_SOUND
```
    Specifies the sound type as point sound.
    
    See Also:
    
    Constant Field Values
  - CONE_SOUND
```
static final int CONE_SOUND
```
    Specifies the sound type as cone sound.
    
    See Also:
    
    Constant Field Values
  - STREAMING_AUDIO_DATA
```
static final int STREAMING_AUDIO_DATA
```
    Sound data specified as Streaming is not copied by the AudioDevice driver implementation. It is up to the application to ensure that this data is continuously accessible during sound rendering. Furthermore, full sound spatialization may not be possible, for all AudioDevice3D implementations on unbuffered sound data.
    
    See Also:
    
    Constant Field Values
  - BUFFERED_AUDIO_DATA
```
static final int BUFFERED_AUDIO_DATA
```
    Sound data specified as Buffered is copied by the AudioDevice driver implementation.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - setView
```
void setView(View reference)
```
    Accepts a reference to the current View. Passes reference to current View Object. The PhysicalEnvironment parameters (with playback type and speaker placement), and the PhysicalBody parameters (position/orientation of ears) can be obtained from this object, and the transformations to/from ViewPlatform coordinate (space the listener's head is in) and Virtual World coordinates (space sounds are in).
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    reference - the current View
  - prepareSound
```
int prepareSound(int soundType,
                 MediaContainer soundData)
```
    Accepts a reference to the MediaContainer which contains a reference to sound data and information about the type of data it is. A "sound type" input parameter denotes if the Java 3D sound associated with this sample is a Background, Point, or Cone Sound node. Depending on the type of MediaContainer the sound data is and on the implementation of the AudioDevice used, sound data preparation could consist of opening, attaching, or loading sound data into the device. Unless the cached flag is true, this sound data should NOT be copied, if possible, into host or device memory.
    Once this preparation is complete for the sound sample, an AudioDevice specific index, used to reference the sample in future method calls, is returned. All the rest of the methods described below require this index as a parameter.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    soundType - defines the type of Sound Node: Background, Point, and Cone
    
    soundData - reference to MediaContainer sound data and cached flag
    
    Returns:
    
    device specific sample index used for referencing this sound
  - clearSound
```
void clearSound(int index)
```
    Requests that the AudioDevice free all resources associated with sample with index id.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    index - device specific reference number to device driver sample
  - getSampleDuration
```
long getSampleDuration(int index)
```
    Returns the duration in milliseconds of the sound sample, if this information can be determined. For non-cached streams, this method returns Sound.DURATION_UNKNOWN.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    index - device specific reference number to device driver sample
    
    Returns:
    
    sound duration in milliseconds if this can be determined, otherwise (for non-cached streams) Sound.DURATION_UNKNOWN is returned
  - getNumberOfChannelsUsed
```
int getNumberOfChannelsUsed(int index)
```
    Retrieves the number of channels (on executing audio device) that this sound is using, if it is playing, or is expected to use if it were begun to be played. This form of this method takes the sound's current state (including whether it is muted or unmuted) into account.
    For some AudioDevice3D implementations:
    This method should only be called by Java3D Core and NOT by any application.
    Parameters:
    
    index - device specific reference number to device driver sample
    
    Returns:
    
    number of channels used by sound if it were playing
  - getNumberOfChannelsUsed
```
int getNumberOfChannelsUsed(int index,
                            boolean muted)
```
    Retrieves the number of channels (on executing audio device) that this sound is using, if it is playing, or is projected to use if it were to be started playing. Rather than using the actual current muted/unmuted state of the sound, the muted parameter is used in making the determination.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    index - device specific reference number to device driver sample
    
    muted - flag to use as the current muted state ignoring current mute state
    
    Returns:
    
    number of channels used by sound if it were playing
  - startSample
```
int startSample(int index)
```
    Begins a sound playing on the AudioDevice.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    index - device specific reference number to device driver sample
    
    Returns:
    
    flag denoting if sample was started; 1 if true, 0 if false
  - getStartTime
```
long getStartTime(int index)
```
    Returns the system time of when the sound was last "started". Note that this start time will be as accurate as the AudioDevice implementation can make it - but that it is not guaranteed to be exact.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    index - device specific reference number to device driver sample
    
    Returns:
    
    system time in milliseconds of the last time sound was started
  - stopSample
```
int stopSample(int index)
```
    Stops the sound on the AudioDevice.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    index - device specific reference number to device driver sample associated with sound data to be played
    
    Returns:
    
    flag denoting if sample was stopped; 1 if true, 0 if false
  - setSampleGain
```
void setSampleGain(int index,
                   float scaleFactor)
```
    Sets the overall gain scale factor applied to data associated with this source to increase or decrease its overall amplitude. The gain scale factor value passed into this method is the combined value of the Sound node's Initial Gain and the current AuralAttribute Gain scale factors.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    index - device specific reference number to device driver sample
    
    scaleFactor - amplitude (gain) scale factor
  - setLoop
```
void setLoop(int index,
             int count)
```
    Sets a sound's loop count. A full description of this parameter and how it is used is in the documentation for Sound.setLoop.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    index - device specific reference number to device driver sample
    
    count - number of times sound is looped during play
    
    See Also:
    
    Sound.setLoop(int)
  - setVworldXfrm
```
void setVworldXfrm(int index,
                   Transform3D trans)
```
    Passes a reference to the concatenated transformation to be applied to local sound position and direction parameters.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    index - device specific reference number to device driver sample
    
    trans - transformation matrix applied to local coordinate parameters
  - setPosition
```
void setPosition(int index,
                 Point3d position)
```
    Sets this sound's location (in Local coordinates) from specified Point. The form of the position parameter matches those of the PointSound method of the same name. A full description of this parameter and how it is used is in the documentation for PointSound class.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    index - device specific reference number to device driver sample
    
    position - location of Point or Cone Sound in Virtual World coordinates
    
    See Also:
    
    PointSound.setPosition(float x, float y, float z), PointSound.setPosition(Point3f position)
  - setDistanceGain
```
void setDistanceGain(int index,
                     double[] frontDistance,
                     float[] frontAttenuationScaleFactor,
                     double[] backDistance,
                     float[] backAttenuationScaleFactor)
```
    Sets this sound's distance gain elliptical attenuation (not including filter cutoff frequency) by defining corresponding arrays containing distances from the sound's origin and gain scale factors applied to all active positional sounds. Gain scale factor is applied to sound based on the distance the listener is from sound source. These attenuation parameters are ignored for BackgroundSound nodes. The back attenuation parameter is ignored for PointSound nodes.
    The form of the attenuation parameters match that of the ConeSound method of the same name. A full description of this parameter and how it is used is in the documentation for ConeSound class.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    index - device specific reference number to device driver sample
    
    frontDistance - defines an array of distance along positive axis through which ellipses pass
    
    frontAttenuationScaleFactor - gain scale factors
    
    backDistance - defines an array of distance along the negative axis through which ellipses pass
    
    backAttenuationScaleFactor - gain scale factors
    
    See Also:
    
    ConeSound.setDistanceGain(float[] frontDistance, float[] frontGain, float[] backDistance, float[] backGain), ConeSound.setDistanceGain(Point2f[] frontAttenuation, Point2f[] backAttenuation)
  - setDirection
```
void setDirection(int index,
                  Vector3d direction)
```
    Sets this sound's direction from the local coordinate vector provided. The form of the direction parameter matches that of the ConeSound method of the same name. A full description of this parameter and how it is used is in the documentation for the ConeSound class.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    index - device specific reference number to device driver sample
    
    direction - the new direction vector in local coordinates
    
    See Also:
    
    ConeSound.setDirection(float x, float y, float z), ConeSound.setDirection(Vector3f direction)
  - setAngularAttenuation
```
void setAngularAttenuation(int index,
                           int filterType,
                           double[] angle,
                           float[] attenuationScaleFactor,
                           float[] filterCutoff)
```
    Sets this sound's angular gain attenuation (including filter) by defining corresponding arrays containing angular offsets from the sound's axis, gain scale factors, and frequency cutoff applied to all active directional sounds. Gain scale factor is applied to sound based on the angle between the sound's axis and the ray from the sound source origin to the listener. The form of the attenuation parameter matches that of the ConeSound method of the same name. A full description of this parameter and how it is used is in the documentation for the ConeSound class.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    index - device specific reference number to device driver sample
    
    filterType - describes type (if any) of filtering defined by attenuation
    
    angle - array containing angular distances from sound axis
    
    attenuationScaleFactor - array containing gain scale factor
    
    filterCutoff - array containing filter cutoff frequencies. The filter values for each tuples can be set to Sound.NO_FILTER.
    
    See Also:
    
    ConeSound.setAngularAttenuation(float[] distance, float[] gain, float[] filter), ConeSound.setAngularAttenuation(Point3f[] attenuation), ConeSound.setAngularAttenuation(Point2f[] attenuation)
  - setRolloff
```
void setRolloff(float rolloff)
```
    Changes the speed of sound factor. A full description of this parameter and how it is used is in the documentation for the AuralAttributes class.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    rolloff - atmospheric gain scale factor (changing speed of sound)
    
    See Also:
    
    AuralAttributes.setRolloff(float)
  - setReflectionCoefficient
```
void setReflectionCoefficient(float coefficient)
```
    Sets the Reflective Coefficient scale factor applied to distinct low-order early reflections of sound off the surfaces in the region defined by the current listening region.
    A full description of this parameter and how it is used is in the documentation for the AuralAttributes class.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    coefficient - reflection/absorption factor applied to reverb
    
    See Also:
    
    AuralAttributes.setReflectionCoefficient(float)
  - setReverbDelay
```
void setReverbDelay(float reverbDelay)
```
    Sets the reverberation delay time. In this form, while reverberation is being rendered, the parameter specifies the delay time between each order of late reflections explicitly given in milliseconds. A value for delay time of 0.0 disables reverberation.
    A full description of this parameter and how it is used is in the documentation for the AuralAttributes class.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    reverbDelay - time between each order of late reflection
    
    See Also:
    
    AuralAttributes.setReverbDelay(float reverbDelay)
  - setReverbOrder
```
void setReverbOrder(int reverbOrder)
```
    Sets the reverberation order of reflections. The reverbOrder parameter specifies the number of times reflections are added to reverberation being calculated. A value of -1 specifies an unbounded number of reverberations. A full description of this parameter and how it is used is in the documentation for the AuralAttributes class.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    reverbOrder - number of times reflections added to reverb signal
    
    See Also:
    
    AuralAttributes.setReverbOrder(int)
  - setDistanceFilter
```
void setDistanceFilter(int filterType,
                       double[] distance,
                       float[] filterCutoff)
```
    Sets Distance Filter corresponding arrays containing distances and frequency cutoff applied to all active positional sounds. Gain scale factor is applied to sound based on the distance the listener is from the sound source. A full description of this parameter and how it is used is in the documentation for the AuralAttributes class.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    filterType - denotes the type of filtering to be applied
    
    distance - array of offset distances from sound origin
    
    filterCutoff - array of frequency cutoff
    
    See Also:
    
    AuralAttributes.setDistanceFilter(float[] distance, float[] frequencyCutoff), AuralAttributes.setDistanceFilter(Point2f[] attenuation)
  - setFrequencyScaleFactor
```
void setFrequencyScaleFactor(float frequencyScaleFactor)
```
    Specifies a scale factor applied to the frequency (or wavelength). A value less than 1.0 will result of slowing the playback rate of the sample. A value greater than 1.0 will increase the playback rate. This parameter is also used to expand or contract the usual frequency shift applied to the sound source due to Doppler effect calculations. Valid values are >= 0.0. A full description of this parameter and how it is used is in the documentation for the AuralAttributes class.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    frequencyScaleFactor - factor applied to change of frequency
    
    See Also:
    
    AuralAttributes.setFrequencyScaleFactor(float)
  - setVelocityScaleFactor
```
void setVelocityScaleFactor(float velocityScaleFactor)
```
    Sets the Velocity scale factor applied during Doppler Effect calculation. This parameter specifies a scale factor applied to the velocity of sound relative to the listener's position and movement in relation to the sound's position and movement. This scale factor is multipled by the calculated velocity portion of the Doppler effect equation used during sound rendering. A full description of this parameter and how it is used is in the documentation for the AuralAttributes class.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    velocityScaleFactor - applied to velocity of sound in relation to listener
    
    See Also:
    
    AuralAttributes.setVelocityScaleFactor(float)
  - muteSample
```
void muteSample(int index)
```
    Makes the sample 'play silently'. This method implements (as efficiently as possible) the muting of a playing sound sample. Ideally this is implemented by stopping a sample and freeing channel resources (rather than just setting the gain of the sample to zero).
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    index - device specific reference number to device driver sample
  - unmuteSample
```
void unmuteSample(int index)
```
    Makes a silently playing sample audible. In the ideal, this restarts a muted sample by offset from the beginning by the number of milliseconds since the time the sample began playing (rather than setting gain to current non-zero gain).
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    index - device specific reference number to device driver sample
  - pauseSample
```
void pauseSample(int index)
```
    Temporarily stops a cached sample from playing without resetting the sample's current pointer back to the beginning of the sound data so that it can be unpaused at a later time from the same location in the sample when the pause was initiated. Pausing a streaming, non-cached sound sample will be treated as a mute.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    index - device specific reference number to device driver sample
  - unpauseSample
```
void unpauseSample(int index)
```
    Restarts the paused sample from the location in the sample where paused.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    index - device specific reference number to device driver sample
  - updateSample
```
void updateSample(int index)
```
    Explicitly updates a Sample. This method is called when a Sound is to be explicitly updated. It is only called when all a sounds parameters are known to have been passed to the audio device. In this way, an implementation can choose to perform lazy-evaluation of a sample, rather than updating the rendering state of the sample after every individual parameter changed. This method can be left as a null method if the implementor so chooses.
    This method should only be called by Java3D Core and NOT by any application.
    
    Parameters:
    
    index - device specific reference number to device driver sample

Interface AudioDevice3D

Field Summary

Fields inherited from interface org.scijava.java3d.AudioDevice

Method Summary

Methods inherited from interface org.scijava.java3d.AudioDevice

Field Detail

BACKGROUND_SOUND

POINT_SOUND

CONE_SOUND

STREAMING_AUDIO_DATA

BUFFERED_AUDIO_DATA

Method Detail

setView

prepareSound

clearSound

getSampleDuration

getNumberOfChannelsUsed

getNumberOfChannelsUsed

startSample

getStartTime

stopSample

setSampleGain

setLoop

setVworldXfrm

setPosition

setDistanceGain

setDirection

setAngularAttenuation

setRolloff

setReflectionCoefficient

setReverbDelay

setReverbOrder

setDistanceFilter

setFrequencyScaleFactor

setVelocityScaleFactor

muteSample

unmuteSample

pauseSample

unpauseSample

updateSample