Interface AudioDevice3DL2
- All Superinterfaces:
AudioDevice
,AudioDevice3D
- All Known Implementing Classes:
AudioEngine3DL2
,JavaSoundMixer
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:
-
Field Summary
Fields inherited from interface javax.media.j3d.AudioDevice
HEADPHONES, MONO_SPEAKER, STEREO_SPEAKERS
Fields inherited from interface javax.media.j3d.AudioDevice3D
BACKGROUND_SOUND, BUFFERED_AUDIO_DATA, CONE_SOUND, POINT_SOUND, STREAMING_AUDIO_DATA
-
Method Summary
Modifier and TypeMethodDescriptionvoid
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 javax.media.j3d.AudioDevice
close, getAngleOffsetToSpeaker, getAudioPlaybackType, getCenterEarToSpeaker, getChannelsAvailable, getChannelsUsedForSound, getTotalChannels, initialize, setAngleOffsetToSpeaker, setAudioPlaybackType, setCenterEarToSpeaker
Methods inherited from interface javax.media.j3d.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
-
Method Details
-
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 unchangedThis 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 samplescaleFactor
- 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:
-
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:
-
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:
-
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:
-
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:
-
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:
-
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 samplescaleFactor
- 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 samplescaleFactor
- 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.
-