AudioDevice3DL2 (Java 3D Javadocs 0-SNAPSHOT API)

All Superinterfaces:

AudioDevice, AudioDevice3D

All Known Implementing Classes:

AudioEngine3DL2, JavaSoundMixer
```
public interface AudioDevice3DL2
extends AudioDevice3D
```
Extends AudioDevice3D to include reverb and environmental audio parameters that are defined in the MIDI Manufactures' Association Interactive Audio Special Interest Group (MMA IASIG) Level 2 Specification.
The reverberation methods of AudioDevice3DL2 interface augment the reverberation methods defined in AudioDevice3D.
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.
The non-query methods of this interface should only be called by an application if the AudioDevice instance is not referenced by any PhysicalEnvironment explicitly with .setAudioDevice() or implicitly through Universe utility method in which case these are called by Core Java 3D Sound classes and Sound Scheduler thread(s).
After the application chooses the AudioDevice3DL2 implementation 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 AudioDevice3DL2 methods should not be call by any application if the audio device is associated with a Physical Environment and thus used by Java3D Core.
Filtering for this extended AudioDevice interface is defined uniformly as a simple low-pass filter defined by a cutoff frequency. This will allow the same type of high-frequency attenuation that the MMA IASIG Level 2 filtering model with its 'reference frequency' and 'attenuation ratio' parameters affords. Use of a cutoff frequency is consistent with the filtering type for distance and angular attenuation for ConeSound and AuralAttributes. The filter methods will likely be overloaded in some future extension of this interface.

Since:

Java 3D 1.3

See Also:

Sound, AuralAttributes, AudioDevice3D

Field Summary
- Fields inherited from interface org.scijava.java3d.AudioDevice3D
  BACKGROUND_SOUND, BUFFERED_AUDIO_DATA, CONE_SOUND, POINT_SOUND, STREAMING_AUDIO_DATA
- 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`	`pause()` Pause audio device engine (thread/server) without closing the device.
`void`	`resume()` Resumes audio device engine (if previously paused) without reinitializing the device.
`void`	`setDecayFilter(float frequencyCutoff)` Set reverb decay filter.
`void`	`setDecayTime(float time)` Set reverb decay time.
`void`	`setDensity(float density)` Set reverb density.
`void`	`setDiffusion(float diffusion)` Set reverb diffusion.
`void`	`setGain(float scaleFactor)` Set overall gain control of all sounds playing on the audio device.
`void`	`setObstructionFilter(int sampleId, float frequencyCutoff)` Set the obstruction filter control.
`void`	`setObstructionGain(int sampleId, float scaleFactor)` Set the obstruction gain control.
`void`	`setOcclusionFilter(int sampleId, float frequencyCutoff)` Set the occlusion filter control.
`void`	`setOcclusionGain(int sampleId, float scaleFactor)` Set the occlusion gain control.
`void`	`setRateScaleFactor(int sampleId, float scaleFactor)` Set scale factor applied to sample playback rate for a particular sound associated with the audio device.
`void`	`setReflectionDelay(float reflectionDelay)` Sets the early reflection delay time.
`void`	`setReverbCoefficient(float coefficient)` Set late reflection (referred to as 'reverb') attenuation.

Methods inherited from interface org.scijava.java3d.AudioDevice3D
clearSound, getNumberOfChannelsUsed, getNumberOfChannelsUsed, getSampleDuration, getStartTime, muteSample, pauseSample, prepareSound, setAngularAttenuation, setDirection, setDistanceFilter, setDistanceGain, setFrequencyScaleFactor, setLoop, setPosition, setReflectionCoefficient, setReverbDelay, setReverbOrder, setRolloff, setSampleGain, setVelocityScaleFactor, setView, setVworldXfrm, startSample, stopSample, unmuteSample, unpauseSample, updateSample

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

- Method Detail
  - pause
```
void pause()
```
    Pause audio device engine (thread/server) without closing the device. Causes all cached sounds to be paused and all streaming sounds to be stopped.
    This method should NOT be called by any application if the audio device is associated with a Physical Environment used by Java3D Core. This method will be implicitly called when View (associated with this device) is deactivated.
  - resume
```
void resume()
```
    Resumes audio device engine (if previously paused) without reinitializing the device. Causes all paused cached sounds to be resumed and all streaming sounds restarted.
    This method should NOT be called by any application if the audio device is associated with a Physical Environment used by Java3D Core. This method will be implicitly called when View (associated with this device) is actived.
  - setGain
```
void setGain(float scaleFactor)
```
    Set overall gain control of all sounds playing on the audio device. Default: 1.0f = no attenuation.
    This method should NOT be called by any application if the audio device is associated with a Physical Environment used by Java3D Core.
    
    Parameters:
    
    scaleFactor - scale factor applied to calculated amplitudes for all sounds playing on this device
  - setRateScaleFactor
```
void setRateScaleFactor(int sampleId,
                        float scaleFactor)
```
    Set scale factor applied to sample playback rate for a particular sound associated with the audio device. Changing the device sample rate affects both the pitch and speed. This scale factor is applied to ALL sound types. Changes (scales) the playback rate of a sound independent of Doppler rate changes. Default: 1.0f = original sample rate is unchanged
    This method should NOT be called by any application if the audio device is associated with a Physical Environment used by Java3D Core.
    
    Parameters:
    
    sampleId - device specific reference number to device driver sample
    
    scaleFactor - non-negative factor applied to calculated amplitudes for all sounds playing on this device
  - setReverbCoefficient
```
void setReverbCoefficient(float coefficient)
```
    Set late reflection (referred to as 'reverb') attenuation. This scale factor is applied to iterative, indistinguishable late reflections that constitute the tail of reverberated sound in the aural environment. This parameter, along with the early reflection coefficient, defines the reflective/absorptive characteristic of the surfaces in the current listening region. A coefficient value of 0 disables reverberation. Valid values of parameters range from 0.0 to 1.0. Default: 0.0f.
    A full description of this parameter and how it is used is in the documentation for the AuralAttributes class.
    This method should NOT be called by any application if the audio device is associated with a Physical Environment used by Java3D Core.
    
    Parameters:
    
    coefficient - late reflection attenuation factor
    
    See Also:
    
    AuralAttributes.setReverbCoefficient(float)
  - setReflectionDelay
```
void setReflectionDelay(float reflectionDelay)
```
    Sets the early reflection delay time. In this form, the parameter specifies the delay time between each order of reflection (while reverberation is being rendered) explicitly given in milliseconds. Valid values are non-negative floats. There may be limitations imposed by the device on how small or large this value can be made. A value of 0.0 would result in early reflections being added as soon as possible after the sound begins. Default = 20.0 milliseconds.
    A full description of this parameter and how it is used is in the documentation for the AuralAttributes class.
    This method should NOT be called by any application if the audio device is associated with a Physical Environment used by Java3D Core.
    
    Parameters:
    
    reflectionDelay - time between each order of early reflection
    
    See Also:
    
    AuralAttributes.setReflectionDelay(float)
  - setDecayTime
```
void setDecayTime(float time)
```
    Set reverb decay time. Defines the reverberation decay curve. Default: 1000.0 milliseconds.
    A full description of this parameter and how it is used is in the documentation for the AuralAttributes class.
    This method should NOT be called by any application if the audio device is associated with a Physical Environment used by Java3D Core.
    
    Parameters:
    
    time - decay time in milliseconds
    
    See Also:
    
    AuralAttributes.setDecayTime(float)
  - setDecayFilter
```
void setDecayFilter(float frequencyCutoff)
```
    Set reverb decay filter. This provides for frequencies above the given cutoff frequency to be attenuated during reverb decay at a different rate than frequencies below this value. Thus, defining a different reverb decay curve for frequencies above the cutoff value. Default: 1.0 decay is uniform for all frequencies.
    There is no corresponding Core AuralAttributes method at this time. Until high frequency attenuation is supported by new Core API, this will be set by the Core with the value 1.0. It is highly recommended that this method should NOT be called by any application if the audio device is associated with a Physical Environment used by Java3D Core.
    
    Parameters:
    
    frequencyCutoff - value of frequencies in Hertz above which a low-pass filter is applied.
    
    See Also:
    
    AuralAttributes.setDecayFilter(float)
  - setDiffusion
```
void setDiffusion(float diffusion)
```
    Set reverb diffusion. This defines the echo dispersement (also referred to as 'echo density'). The value of this reverb parameter is expressed as a percent of the audio device's minimum-to-maximum values. Default: 1.0f - maximum diffusion on device.
    A full description of this parameter and how it is used is in the documentation for the AuralAttributes class.
    This method should NOT be called by any application if the audio device is associated with a Physical Environment used by Java3D Core.
    
    Parameters:
    
    diffusion - percentage expressed within the range of 0.0 and 1.0
    
    See Also:
    
    AuralAttributes.setDiffusion(float)
  - setDensity
```
void setDensity(float density)
```
    Set reverb density. This defines the modal density (also referred to as 'spectral coloration'). The value of this parameter is expressed as a percent of the audio device's minimum-to-maximum values for this reverb parameter. Default: 1.0f - maximum density on device.
    A full description of this parameter and how it is used is in the documentation for the AuralAttributes class.
    This method should NOT be called by any application if the audio device is associated with a Physical Environment used by Java3D Core.
    
    Parameters:
    
    density - reverb density expressed as a percentage, within the range of 0.0 and 1.0
    
    See Also:
    
    AuralAttributes.setDensity(float)
  - setObstructionGain
```
void setObstructionGain(int sampleId,
                        float scaleFactor)
```
    Set the obstruction gain control. This method allows for attenuating sound waves traveling between the sound source and the listener obstructed by objects. Direct sound signals/waves for obstructed sound source are attenuated but not indirect (reflected) waves. Default: 1.0 - gain is not attenuated; obstruction is not occurring.
    There is no corresponding Core AuralAttributes method at this time. Even so, this method should NOT be called by any application if the audio device is associated with a Physical Environment used by Java3D Core.
    
    Parameters:
    
    sampleId - device specific reference number to device driver sample
    
    scaleFactor - non-negative factor applied to direct sound gain
  - setObstructionFilter
```
void setObstructionFilter(int sampleId,
                          float frequencyCutoff)
```
    Set the obstruction filter control. This provides for frequencies above the given cutoff frequency to be attenuated, during while the gain of an obstruction signal is being calculated, at a different rate than frequencies below this value. Default: 1.0 - filtering is uniform for all frequencies.
    There is no corresponding Core AuralAttributes method at this time. Until high frequency attenuation is supported by new Core API this will be set by the Core with the value 1.0. It is highly recommended that this method should NOT be called by any application if the audio device is associated with a Physical Environment used by Java3D Core.
    
    Parameters:
    
    frequencyCutoff - value of frequencies in Hertz above which a low-pass filter is applied.
  - setOcclusionGain
```
void setOcclusionGain(int sampleId,
                      float scaleFactor)
```
    Set the occlusion gain control. This method allows for attenuating sound waves traveling between the sound source and the listener occluded by objects. Both direct and indirect sound signals/waves for occluded sound sources are attenuated. Default: 1.0 - gain is not attenuated; occlusion is not occurring.
    There is no corresponding Core AuralAttributes method at this time. Even so, this method should NOT be called by any application if the audio device is associated with a Physical Environment used by Java3D Core.
    
    Parameters:
    
    sampleId - device specific reference number to device driver sample
    
    scaleFactor - non-negative factor applied to direct sound gain
  - setOcclusionFilter
```
void setOcclusionFilter(int sampleId,
                        float frequencyCutoff)
```
    Set the occlusion filter control. This provides for frequencies above the given cutoff frequency to be attenuated, during while the gain of an occluded signal is being calculated, at a different rate than frequencies below this value. Default: 1.0 - filtering is uniform for all frequencies.
    There is no corresponding Core AuralAttributes method at this time. Until high frequency attenuation is supported by new Core API this will be set by the Core with the value 1.0. It is highly recommended that this method should NOT be called by any application if the audio device is associated with a Physical Environment used by Java3D Core.
    
    Parameters:
    
    frequencyCutoff - value of frequencies in Hertz above which a low-pass filter is applied.

Interface AudioDevice3DL2

Field Summary

Fields inherited from interface org.scijava.java3d.AudioDevice3D

Fields inherited from interface org.scijava.java3d.AudioDevice

Method Summary

Methods inherited from interface org.scijava.java3d.AudioDevice3D

Methods inherited from interface org.scijava.java3d.AudioDevice

Method Detail

pause

resume

setGain

setRateScaleFactor

setReverbCoefficient

setReflectionDelay

setDecayTime

setDecayFilter

setDiffusion

setDensity

setObstructionGain

setObstructionFilter

setOcclusionGain

setOcclusionFilter