001: /*
002: * $RCSfile: AudioEngine3DL2.java,v $
003: *
004: * Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * Redistribution and use in source and binary forms, with or without
007: * modification, are permitted provided that the following conditions
008: * are met:
009: *
010: * - Redistribution of source code must retain the above copyright
011: * notice, this list of conditions and the following disclaimer.
012: *
013: * - Redistribution in binary form must reproduce the above copyright
014: * notice, this list of conditions and the following disclaimer in
015: * the documentation and/or other materials provided with the
016: * distribution.
017: *
018: * Neither the name of Sun Microsystems, Inc. or the names of
019: * contributors may be used to endorse or promote products derived
020: * from this software without specific prior written permission.
021: *
022: * This software is provided "AS IS," without a warranty of any
023: * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
024: * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY,
025: * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY
026: * EXCLUDED. SUN MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL
027: * NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF
028: * USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS
029: * DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR
030: * ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
031: * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
032: * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR
033: * INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
034: * POSSIBILITY OF SUCH DAMAGES.
035: *
036: * You acknowledge that this software is not designed, licensed or
037: * intended for use in the design, construction, operation or
038: * maintenance of any nuclear facility.
039: *
040: * $Revision: 1.5 $
041: * $Date: 2007/02/09 17:20:02 $
042: * $State: Exp $
043: */
044:
045: package com.sun.j3d.audioengines;
046:
047: import javax.media.j3d.*;
048: import javax.vecmath.*;
049: import java.util.ArrayList;
050:
051: /**
052: * The AudioEngine3DL2 Class defines an audio output device that generates
053: * sound 'image' from high-level sound parameters passed to it during
054: * scene graph.
055: *
056: * <P>
057: * The methods in this class are meant to be optionally overridden by an
058: * extended class. This extended class would provice device specific code.
059: *
060: * <P>
061: * Error checking on all parameters passed to these methods is already
062: * explicitly being done by the Java 3D core code that calls these methods.
063: *
064: * <P>
065: * These methods should NOT be called by any application if the audio engine
066: * is associated with a Physical Environment used by Java3D Core.
067: *
068: * @since Java 3D 1.3
069: */
070: public abstract class AudioEngine3DL2 extends AudioEngine3D implements
071: AudioDevice3DL2 {
072: /**
073: * Construct a new AudioEngine3DL2 with the specified PhysicalEnvironment.
074: * @param physicalEnvironment the physical environment object where we
075: * want access to this device.
076: */
077: public AudioEngine3DL2(PhysicalEnvironment physicalEnvironment) {
078: super (physicalEnvironment);
079: }
080:
081: /*
082: *
083: * Methods that affect AudioEngine3DLD fields that are NOT associated
084: * with a specific sound sample
085: *
086: */
087:
088: /**
089: * Pauses audio device engine without closing the device and associated
090: * threads.
091: * Causes all cached sounds to be paused and all streaming sounds to be
092: * stopped.
093: */
094: public abstract void pause();
095:
096: /**
097: * Resumes audio device engine (if previously paused) without
098: * reinitializing the device.
099: * Causes all paused cached sounds to be resumed and all streaming
100: * sounds restarted.
101: */
102: public abstract void resume();
103:
104: /**
105: * Set overall gain control of all sounds playing on the audio device.
106: * @param scaleFactor scale factor applied to calculated amplitudes for
107: * all sounds playing on this device
108: */
109: public abstract void setGain(float scaleFactor);
110:
111: /*
112: *
113: * Methods explicitly affect a particular sound rendering and that
114: * require audio device specific methods that override this class.
115: *
116: */
117:
118: /**
119: * Set scale factor applied to sample playback rate for a particular sound
120: * associated with the audio device.
121: * Changing the device sample rate affects both the pitch and speed.
122: * This scale factor is applied to ALL sound types.
123: * Changes (scales) the playback rate of a sound independent of
124: * Doppler rate changes.
125: * @param index device specific reference to device driver sample
126: * @param scaleFactor non-negative factor applied to calculated
127: * amplitudes for all sounds playing on this device
128: * @see Sound#setRateScaleFactor
129: */
130: public void setRateScaleFactor(int index, float scaleFactor) {
131: Sample sample = (Sample) getSample(index);
132: if (sample != null)
133: sample.setRateScaleFactor(scaleFactor);
134: return;
135: }
136:
137: /*
138: *
139: * Methods explicitly affect aural attributes of the listening space
140: * used to calculated reverberation during sound rendering.
141: * These require audio device specific methods that override this class.
142: *
143: */
144:
145: /**
146: * Set late reflection (referred to as 'reverb') attenuation.
147: * This scale factor is applied to iterative, indistinguishable
148: * late reflections that constitute the tail of reverberated sound in
149: * the aural environment.
150: * This parameter, along with the early reflection coefficient, defines
151: * the reflective/absorptive characteristic of the surfaces in the
152: * current listening region.
153: * @param coefficient late reflection attenuation factor
154: * @see AuralAttributes#setReverbCoefficient
155: */
156: public void setReverbCoefficient(float coefficient) {
157: attribs.reverbCoefficient = coefficient;
158: return;
159: }
160:
161: /**
162: * Sets the early reflection delay time.
163: * In this form, the parameter specifies the delay time between each order
164: * of reflection (while reverberation is being rendered) explicitly given
165: * in milliseconds.
166: * @param reflectionDelay time between each order of early reflection
167: * @see AuralAttributes#setReflectionDelay
168: */
169: public void setReflectionDelay(float reflectionDelay) {
170: attribs.reflectionDelay = reflectionDelay;
171: return;
172: }
173:
174: /**
175: * Set reverb decay time.
176: * Defines the reverberation decay curve.
177: * @param time decay time in milliseconds
178: * @see AuralAttributes#setDecayTime
179: */
180: public void setDecayTime(float time) {
181: attribs.decayTime = time;
182: return;
183: }
184:
185: /**
186: * Set reverb decay filter.
187: * This provides for frequencies above the given cutoff frequency to be
188: * attenuated during reverb decay at a different rate than frequencies
189: * below this value. Thus, defining a different reverb decay curve for
190: * frequencies above the cutoff value.
191: * @param frequencyCutoff value of frequencies in Hertz above which a
192: * low-pass filter is applied.
193: * @see AuralAttributes#setDecayFilter
194: */
195: public void setDecayFilter(float frequencyCutoff) {
196: attribs.decayFrequencyCutoff = frequencyCutoff;
197: return;
198: }
199:
200: /**
201: * Set reverb diffusion.
202: * This defines the echo dispersement (also referred to as 'echo density').
203: * The value of this reverb parameter is expressed as a percent of the
204: * audio device's minimum-to-maximum values.
205: * @param diffusion percentage expressed within the range of 0.0 and 1.0
206: * @see AuralAttributes#setDiffusion
207: */
208: public void setDiffusion(float diffusion) {
209: attribs.diffusion = diffusion;
210: return;
211: }
212:
213: /**
214: * Set reverb density.
215: * This defines the modal density (also referred to as 'spectral
216: * coloration').
217: * The value of this parameter is expressed as a percent of the audio
218: * device's minimum-to-maximum values for this reverb parameter.
219: * @param density reverb density expressed as a percentage,
220: * within the range of 0.0 and 1.0
221: * @see AuralAttributes#setDensity
222: */
223: public void setDensity(float density) {
224: attribs.density = density;
225: return;
226: }
227:
228: /**
229: * Set the obstruction gain control. This method allows for attenuating
230: * sound waves traveling between the sound source and the listener
231: * obstructed by objects. Direct sound signals/waves for obstructed sound
232: * source are attenuated but not indirect (reflected) waves.
233: * There is no corresponding Core AuralAttributes method at this time.
234: * @param index device specific reference to device driver sample
235: * @param scaleFactor non-negative factor applied to direct sound gain
236: */
237: public void setObstructionGain(int index, float scaleFactor) {
238: Sample sample = (Sample) getSample(index);
239: if (sample != null)
240: sample.setObstructionGain(scaleFactor);
241: return;
242: }
243:
244: /**
245: * Set the obstruction filter control.
246: * This provides for frequencies above the given cutoff frequency
247: * to be attenuated, during while the gain of an obstruction signal
248: * is being calculated, at a different rate than frequencies
249: * below this value.
250: * There is no corresponding Core AuralAttributes method at this time.
251: * @param index device specific reference to device driver sample
252: * @param frequencyCutoff value of frequencies in Hertz above which a
253: * low-pass filter is applied.
254: */
255:
256: public void setObstructionFilter(int index, float frequencyCutoff) {
257: Sample sample = (Sample) getSample(index);
258: if (sample != null)
259: sample.setObstructionFilter(frequencyCutoff);
260: return;
261: }
262:
263: /**
264: * Set the occlusion gain control. This method allows for attenuating
265: * sound waves traveling between the sound source and the listener
266: * occluded by objects. Both direct and indirect sound signals/waves
267: * for occluded sound sources are attenuated.
268: * There is no corresponding Core AuralAttributes method at this time.
269: * @param index device specific reference to device driver sample
270: * @param scaleFactor non-negative factor applied to direct sound gain
271: */
272: public void setOcclusionGain(int index, float scaleFactor) {
273: Sample sample = (Sample) getSample(index);
274: if (sample != null)
275: sample.setObstructionGain(scaleFactor);
276: return;
277: }
278:
279: /**
280: * Set the occlusion filter control.
281: * This provides for frequencies above the given cutoff frequency
282: * to be attenuated, during while the gain of an occluded signal
283: * is being calculated, at a different rate than frequencies below
284: * this value.
285: * There is no corresponding Core AuralAttributes method at this time.
286: * @param index device specific reference to device driver sample
287: * @param frequencyCutoff value of frequencies in Hertz above which a
288: * low-pass filter is applied.
289: */
290: public void setOcclusionFilter(int index, float frequencyCutoff) {
291: Sample sample = (Sample) getSample(index);
292: if (sample != null)
293: sample.setObstructionFilter(frequencyCutoff);
294: return;
295: }
296: }
|