javax.media.j3d.AudioDevice3DL2 Maven / Gradle / Ivy
Show all versions of java3d-core Show documentation
/*
* Copyright 2001-2008 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*
*/
package javax.media.j3d;
/**
* 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.
*
* @see Sound
* @see AuralAttributes
* @see AudioDevice3D
* @since Java 3D 1.3
*/
public interface AudioDevice3DL2 extends AudioDevice3D {
/**
* 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.
*/
public abstract void pause();
/**
* 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.
*/
public abstract void resume();
/**
* 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.
* @param scaleFactor scale factor applied to calculated amplitudes for
* all sounds playing on this device
*/
public abstract void setGain(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.
* @param sampleId device specific reference number to device driver sample
* @param scaleFactor non-negative factor applied to calculated
* amplitudes for all sounds playing on this device
*/
public abstract void setRateScaleFactor(int sampleId, float scaleFactor);
/**
* 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.
* @param coefficient late reflection attenuation factor
* @see AuralAttributes#setReverbCoefficient
*/
public abstract void setReverbCoefficient(float coefficient);
/**
* 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.
* @param reflectionDelay time between each order of early reflection
* @see AuralAttributes#setReflectionDelay
*/
public abstract void setReflectionDelay(float reflectionDelay);
/**
* 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.
* @param time decay time in milliseconds
* @see AuralAttributes#setDecayTime
*/
public abstract void setDecayTime(float time);
/**
* 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.
* @param frequencyCutoff value of frequencies in Hertz above which a
* low-pass filter is applied.
* @see AuralAttributes#setDecayFilter
*/
public abstract void setDecayFilter(float frequencyCutoff);
/**
* 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.
* @param diffusion percentage expressed within the range of 0.0 and 1.0
* @see AuralAttributes#setDiffusion
*/
public abstract void setDiffusion(float diffusion);
/**
* 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.
* @param density reverb density expressed as a percentage,
* within the range of 0.0 and 1.0
* @see AuralAttributes#setDensity
*/
public abstract void setDensity(float density);
/**
* 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.
* @param sampleId device specific reference number to device driver sample
* @param scaleFactor non-negative factor applied to direct sound gain
*/
public abstract void setObstructionGain(int sampleId, float scaleFactor);
/**
* 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.
* @param frequencyCutoff value of frequencies in Hertz above which a
* low-pass filter is applied.
*/
public abstract void setObstructionFilter(int sampleId, float frequencyCutoff);
/**
* 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.
* @param sampleId device specific reference number to device driver sample
* @param scaleFactor non-negative factor applied to direct sound gain
*/
public abstract void setOcclusionGain(int sampleId, float scaleFactor);
/**
* 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.
* @param frequencyCutoff value of frequencies in Hertz above which a
* low-pass filter is applied.
*/
public abstract void setOcclusionFilter(int sampleId, float frequencyCutoff);
}