com.sun.j3d.audioengines.AudioEngine3DL2 Maven / Gradle / Ivy
Show all versions of java3d-core Show documentation
/*
* Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* - Redistribution of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* - Redistribution in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* Neither the name of Sun Microsystems, Inc. or the names of
* contributors may be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* This software is provided "AS IS," without a warranty of any
* kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
* WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY
* EXCLUDED. SUN MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL
* NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF
* USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS
* DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR
* ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
* CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
* REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR
* INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGES.
*
* You acknowledge that this software is not designed, licensed or
* intended for use in the design, construction, operation or
* maintenance of any nuclear facility.
*
*/
package com.sun.j3d.audioengines;
import javax.media.j3d.AudioDevice3DL2;
import javax.media.j3d.AuralAttributes;
import javax.media.j3d.PhysicalEnvironment;
import javax.media.j3d.Sound;
/**
* The AudioEngine3DL2 Class defines an audio output device that generates
* sound 'image' from high-level sound parameters passed to it during
* scene graph.
*
*
* The methods in this class are meant to be optionally overridden by an
* extended class. This extended class would provice device specific code.
*
*
* Error checking on all parameters passed to these methods is already
* explicitly being done by the Java 3D core code that calls these methods.
*
*
* These methods should NOT be called by any application if the audio engine
* is associated with a Physical Environment used by Java3D Core.
*
* @since Java 3D 1.3
*/
public abstract class AudioEngine3DL2 extends AudioEngine3D implements AudioDevice3DL2 {
/**
* Construct a new AudioEngine3DL2 with the specified PhysicalEnvironment.
* @param physicalEnvironment the physical environment object where we
* want access to this device.
*/
public AudioEngine3DL2(PhysicalEnvironment physicalEnvironment ) {
super(physicalEnvironment);
}
/*
*
* Methods that affect AudioEngine3DLD fields that are NOT associated
* with a specific sound sample
*
*/
/**
* Pauses audio device engine without closing the device and associated
* threads.
* Causes all cached sounds to be paused and all streaming sounds to be
* stopped.
*/
@Override
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.
*/
@Override
public abstract void resume();
/**
* Set overall gain control of all sounds playing on the audio device.
* @param scaleFactor scale factor applied to calculated amplitudes for
* all sounds playing on this device
*/
@Override
public abstract void setGain(float scaleFactor);
/*
*
* Methods explicitly affect a particular sound rendering and that
* require audio device specific methods that override this class.
*
*/
/**
* 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.
* @param index device specific reference to device driver sample
* @param scaleFactor non-negative factor applied to calculated
* amplitudes for all sounds playing on this device
* @see Sound#setRateScaleFactor
*/
@Override
public void setRateScaleFactor(int index, float scaleFactor) {
Sample sample = getSample(index);
if (sample != null)
sample.setRateScaleFactor(scaleFactor);
return;
}
/*
*
* Methods explicitly affect aural attributes of the listening space
* used to calculated reverberation during sound rendering.
* These require audio device specific methods that override this class.
*
*/
/**
* 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.
* @param coefficient late reflection attenuation factor
* @see AuralAttributes#setReverbCoefficient
*/
@Override
public void setReverbCoefficient(float coefficient) {
attribs.reverbCoefficient = coefficient;
return;
}
/**
* 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.
* @param reflectionDelay time between each order of early reflection
* @see AuralAttributes#setReflectionDelay
*/
@Override
public void setReflectionDelay(float reflectionDelay) {
attribs.reflectionDelay = reflectionDelay;
return;
}
/**
* Set reverb decay time.
* Defines the reverberation decay curve.
* @param time decay time in milliseconds
* @see AuralAttributes#setDecayTime
*/
@Override
public void setDecayTime(float time) {
attribs.decayTime = time;
return;
}
/**
* 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.
* @param frequencyCutoff value of frequencies in Hertz above which a
* low-pass filter is applied.
* @see AuralAttributes#setDecayFilter
*/
@Override
public void setDecayFilter(float frequencyCutoff) {
attribs.decayFrequencyCutoff = frequencyCutoff;
return;
}
/**
* 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.
* @param diffusion percentage expressed within the range of 0.0 and 1.0
* @see AuralAttributes#setDiffusion
*/
@Override
public void setDiffusion(float diffusion) {
attribs.diffusion = diffusion;
return;
}
/**
* 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.
* @param density reverb density expressed as a percentage,
* within the range of 0.0 and 1.0
* @see AuralAttributes#setDensity
*/
@Override
public void setDensity(float density) {
attribs.density = density;
return;
}
/**
* 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.
* There is no corresponding Core AuralAttributes method at this time.
* @param index device specific reference to device driver sample
* @param scaleFactor non-negative factor applied to direct sound gain
*/
@Override
public void setObstructionGain(int index, float scaleFactor) {
Sample sample = getSample(index);
if (sample != null)
sample.setObstructionGain(scaleFactor);
return;
}
/**
* 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.
* There is no corresponding Core AuralAttributes method at this time.
* @param index device specific reference to device driver sample
* @param frequencyCutoff value of frequencies in Hertz above which a
* low-pass filter is applied.
*/
@Override
public void setObstructionFilter(int index, float frequencyCutoff) {
Sample sample = getSample(index);
if (sample != null)
sample.setObstructionFilter(frequencyCutoff);
return;
}
/**
* 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.
* There is no corresponding Core AuralAttributes method at this time.
* @param index device specific reference to device driver sample
* @param scaleFactor non-negative factor applied to direct sound gain
*/
@Override
public void setOcclusionGain(int index, float scaleFactor) {
Sample sample = getSample(index);
if (sample != null)
sample.setObstructionGain(scaleFactor);
return;
}
/**
* 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.
* There is no corresponding Core AuralAttributes method at this time.
* @param index device specific reference to device driver sample
* @param frequencyCutoff value of frequencies in Hertz above which a
* low-pass filter is applied.
*/
@Override
public void setOcclusionFilter(int index, float frequencyCutoff) {
Sample sample = getSample(index);
if (sample != null)
sample.setObstructionFilter(frequencyCutoff);
return;
}
}