org.scijava.java3d

Interface AudioDevice3DL2

All Superinterfaces:

AudioDevice, AudioDevice3D

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

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.