Initial creation of j3d-core-utils sources in CVS repository

git-svn-id: https://svn.java.net/svn/j3d-core-utils~svn/trunk@5 9497e636-51bd-65ba-982d-a4982e1767a5

1 files changed, 308 insertions, 0 deletions

diff --git a/src/classes/share/com/sun/j3d/audioengines/AudioEngine3DL2.java b/src/classes/share/com/sun/j3d/audioengines/AudioEngine3DL2.java
new file mode 100644
index 0000000..c8865c2
--- /dev/null
+++ b/src/classes/share/com/sun/j3d/audioengines/AudioEngine3DL2.java
@@ -0,0 +1,308 @@
+/*
+ * $RCSfile$
+ *
+ * Copyright (c) 2004 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.
+ *
+ * $Revision$
+ * $Date$
+ * $State$
+ */
+
+package com.sun.j3d.audioengines;
+
+import javax.media.j3d.*;
+import javax.vecmath.*;
+import java.util.ArrayList;
+
+
+/**
+ * The AudioEngine3DL2 Class defines an audio output device that generates
+ * sound 'image' from high-level sound parameters passed to it during 
+ * scene graph.
+ *
+ * <P>
+ * The methods in this class are meant to be optionally overridden by an 
+ * extended class.  This extended class would provice device specific code.
+ *
+ * <P>
+ * Error checking on all parameters passed to these methods is already
+ * explicitly being done by the Java 3D core code that calls these methods.
+ *
+ * <P>
+ * 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 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.
+     */
+    public void  pause() {
+        // This method must be overridden by device specific implementation
+        return;
+    }
+    /**
+     * Resumes audio device engine (if previously paused) without
+     * reinitializing the device.
+     * Causes all paused cached sounds to be resumed and all streaming
+     * sounds restarted.
+     */
+    public void resume() {
+        // This method must be overridden by device specific implementation
+        return;
+    }
+
+    /**
+     * 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
+     */  
+    public void setGain(float scaleFactor) {
+        // This method must be overridden by device specific implementation
+        return;
+    }
+
+
+    /*
+     *
+     *  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
+     */
+    public void  setRateScaleFactor(int index, float scaleFactor) {
+        Sample 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
+     */
+    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
+     */ 
+    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
+     */
+    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
+     */
+    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
+     */
+    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
+     */
+    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
+     */
+    public void setObstructionGain(int index, float scaleFactor) {
+        Sample 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. 
+     */
+
+    public void setObstructionFilter(int index, float frequencyCutoff) {
+        Sample 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
+     */
+    public void setOcclusionGain(int index, float scaleFactor) {
+        Sample 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. 
+     */
+    public void  setOcclusionFilter(int index, float frequencyCutoff) {
+        Sample sample = (Sample)getSample(index);
+        if (sample != null)
+            sample.setObstructionFilter(frequencyCutoff);
+        return;
+    }
+}