001: /*
002: * $RCSfile: AudioDevice3D.java,v $
003: *
004: * Copyright 1998-2008 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
006: *
007: * This code is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU General Public License version 2 only, as
009: * published by the Free Software Foundation. Sun designates this
010: * particular file as subject to the "Classpath" exception as provided
011: * by Sun in the LICENSE file that accompanied this code.
012: *
013: * This code is distributed in the hope that it will be useful, but WITHOUT
014: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
015: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
016: * version 2 for more details (a copy is included in the LICENSE file that
017: * accompanied this code).
018: *
019: * You should have received a copy of the GNU General Public License version
020: * 2 along with this work; if not, write to the Free Software Foundation,
021: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
022: *
023: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
024: * CA 95054 USA or visit www.sun.com if you need additional information or
025: * have any questions.
026: *
027: * $Revision: 1.5 $
028: * $Date: 2008/02/28 20:17:19 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: import javax.vecmath.*;
035:
036: /**
037: * The AudioDevice3D class defines a 3D audio device that is used to set
038: * sound and aural attributes.
039: *<P>
040: * After the application chooses the AudioDevice3D that Java3D sound
041: * is to be rendered on, the Java 3D Sound Scheduler will call these
042: * methods for all active sounds to render them on the audio device.
043: *<P>
044: * The intent is for this interface to be implemented by AudioDevice Driver
045: * developers using a software or hardware sound engine of their choice.
046: *<P>
047: * Methods in this interface provide the Java3D Core a generic way to
048: * set and query the audio device the application has chosen audio rendering
049: * to be performed on. Methods in this interface include:
050: * <UL>
051: * Set up and clear the sound as a sample on the device.
052: * <P>
053: * Start, stop, pause, unpause, mute, and unmute of sample on the device.
054: * <P>
055: * Set parameters for each sample corresponding to the fields in the
056: * Sound node.
057: * <P>
058: * Set the current active aural parameters that affect all positional samples.
059: * </UL>
060: * <P>
061: * Sound Types
062: * <P>
063: * Sound types match the Sound node classes defined for Java 3D core
064: * for BackgroundSound, PointSound, and ConeSound. The type of sound
065: * a sample is loaded as determines which methods affect it.
066: *
067: * <P>
068: * Sound Data Types
069: * <P>
070: * Samples can be processed as streaming or buffered data.
071: * Fully spatializing sound sources may require data to be buffered.
072: *
073: */
074:
075: public interface AudioDevice3D extends AudioDevice {
076:
077: /**
078: * Specifies the sound type as background sound.
079: */
080: public static final int BACKGROUND_SOUND = 1;
081:
082: /**
083: * Specifies the sound type as point sound.
084: */
085: public static final int POINT_SOUND = 2;
086:
087: /**
088: * Specifies the sound type as cone sound.
089: */
090:
091: public static final int CONE_SOUND = 3;
092:
093: /**
094: * Sound data specified as Streaming is not copied by the AudioDevice
095: * driver implementation. It is up to the application to ensure that
096: * this data is continuously accessible during sound rendering.
097: * Furthermore, full sound spatialization may not be possible, for
098: * all AudioDevice3D implementations on unbuffered sound data.
099: */
100: public static final int STREAMING_AUDIO_DATA = 1;
101: /**
102: * Sound data specified as Buffered is copied by the AudioDevice
103: * driver implementation.
104: */
105: public static final int BUFFERED_AUDIO_DATA = 2;
106:
107: /**
108: * Accepts a reference to the current View.
109: * Passes reference to current View Object. The PhysicalEnvironment
110: * parameters (with playback type and speaker placement), and the
111: * PhysicalBody parameters (position/orientation of ears)
112: * can be obtained from this object, and the transformations to/from
113: * ViewPlatform coordinate (space the listener's head is in) and
114: * Virtual World coordinates (space sounds are in).
115: * <P>
116: * This method should only be called by Java3D Core and NOT by any application.
117: * @param reference the current View
118: */
119: public abstract void setView(View reference);
120:
121: /**
122: * Accepts a reference to the MediaContainer
123: * which contains a reference to sound data and information about the
124: * type of data it is. A "sound type" input parameter denotes if the
125: * Java 3D sound associated with this sample is a Background, Point, or
126: * Cone Sound node.
127: * Depending on the type of MediaContainer the sound data is and on the
128: * implementation of the AudioDevice used, sound data preparation could
129: * consist of opening, attaching, or loading sound data into the device.
130: * Unless the cached flag is true, this sound data should NOT be copied,
131: * if possible, into host or device memory.
132: *<P>
133: * Once this preparation is complete for the sound sample, an AudioDevice
134: * specific index, used to reference the sample in future method calls,
135: * is returned. All the rest of the methods described below require
136: * this index as a parameter.
137: * <P>
138: * This method should only be called by Java3D Core and NOT by any application.
139: * @param soundType defines the type of Sound Node: Background, Point, and
140: * Cone
141: * @param soundData reference to MediaContainer sound data and cached flag
142: * @return device specific sample index used for referencing this sound
143: */
144: public abstract int prepareSound(int soundType,
145: MediaContainer soundData);
146:
147: /**
148: * Requests that the AudioDevice free all
149: * resources associated with sample with index id.
150: * <P>
151: * This method should only be called by Java3D Core and NOT by any application.
152: * @param index device specific reference number to device driver sample
153: */
154: public abstract void clearSound(int index);
155:
156: /**
157: * Returns the duration in milliseconds of the sound sample,
158: * if this information can be determined.
159: * For non-cached
160: * streams, this method returns Sound.DURATION_UNKNOWN.
161: * <P>
162: * This method should only be called by Java3D Core and NOT by any application.
163: * @param index device specific reference number to device driver sample
164: * @return sound duration in milliseconds if this can be determined,
165: * otherwise (for non-cached streams) Sound.DURATION_UNKNOWN is returned
166: */
167: public abstract long getSampleDuration(int index);
168:
169: /**
170: *
171: * Retrieves the number of channels (on executing audio device) that
172: * this sound is using, if it is playing, or is expected to use
173: * if it were begun to be played. This form of this method takes the
174: * sound's current state (including whether it is muted or unmuted)
175: * into account.
176: *<P>
177: * For some AudioDevice3D implementations:
178: *<UL>
179: * Muted sound take channels up on the systems mixer (because they're
180: * rendered as samples playing with gain zero.
181: *<P>
182: * A single sound could be rendered using multiple samples, each taking
183: * up mixer channels.
184: *</UL>
185: * <P>
186: * This method should only be called by Java3D Core and NOT by any application.
187: * @param index device specific reference number to device driver sample
188: * @return number of channels used by sound if it were playing
189: */
190: public abstract int getNumberOfChannelsUsed(int index);
191:
192: /**
193: *
194: * Retrieves the number of channels (on executing audio device) that
195: * this sound is using, if it is playing, or is projected to use if
196: * it were to be started playing. Rather than using the actual current
197: * muted/unmuted state of the sound, the muted parameter is used in
198: * making the determination.
199: * <P>
200: * This method should only be called by Java3D Core and NOT by any application.
201: * @param index device specific reference number to device driver sample
202: * @param muted flag to use as the current muted state ignoring current
203: * mute state
204: * @return number of channels used by sound if it were playing
205: */
206: public abstract int getNumberOfChannelsUsed(int index, boolean muted);
207:
208: /**
209: * Begins a sound playing on the AudioDevice.
210: * <P>
211: * This method should only be called by Java3D Core and NOT by any application.
212: * @param index device specific reference number to device driver sample
213: * @return flag denoting if sample was started; 1 if true, 0 if false
214: */
215: public abstract int startSample(int index);
216:
217: /**
218: * Returns the system time of when the sound
219: * was last "started". Note that this start time will be as accurate
220: * as the AudioDevice implementation can make it - but that it is not
221: * guaranteed to be exact.
222: * <P>
223: * This method should only be called by Java3D Core and NOT by any application.
224: * @param index device specific reference number to device driver sample
225: * @return system time in milliseconds of the last time sound was started
226: */
227: public abstract long getStartTime(int index);
228:
229: /**
230: * Stops the sound on the AudioDevice.
231: * <P>
232: * This method should only be called by Java3D Core and NOT by any application.
233: * @param index device specific reference number to device driver sample
234: * associated with sound data to be played
235: * @return flag denoting if sample was stopped; 1 if true, 0 if false
236: */
237: public abstract int stopSample(int index);
238:
239: /**
240: * Sets the overall gain scale factor applied to data associated with this
241: * source to increase or decrease its overall amplitude.
242: * The gain scale factor value passed into this method is the combined value
243: * of the Sound node's Initial Gain and the current AuralAttribute Gain
244: * scale factors.
245: * <P>
246: * This method should only be called by Java3D Core and NOT by any application.
247: * @param index device specific reference number to device driver sample
248: * @param scaleFactor amplitude (gain) scale factor
249: */
250: public abstract void setSampleGain(int index, float scaleFactor);
251:
252: /**
253: * Sets a sound's loop count.
254: * A full description of this parameter and how it is used is in
255: * the documentation for Sound.setLoop.
256: * <P>
257: * This method should only be called by Java3D Core and NOT by any application.
258: * @param index device specific reference number to device driver sample
259: * @param count number of times sound is looped during play
260: * @see Sound#setLoop
261: */
262: public abstract void setLoop(int index, int count);
263:
264: /**
265: * Passes a reference to the concatenated transformation to be applied to
266: * local sound position and direction parameters.
267: * <P>
268: * This method should only be called by Java3D Core and NOT by any application.
269: * @param index device specific reference number to device driver sample
270: * @param trans transformation matrix applied to local coordinate parameters
271: */
272: public abstract void setVworldXfrm(int index, Transform3D trans);
273:
274: /**
275: * Sets this sound's location (in Local coordinates) from specified
276: * Point. The form of the position parameter matches those of the PointSound
277: * method of the same name.
278: * A full description of this parameter and how it is used is in
279: * the documentation for PointSound class.
280: * <P>
281: * This method should only be called by Java3D Core and NOT by any application.
282: * @param index device specific reference number to device driver sample
283: * @param position location of Point or Cone Sound in Virtual World
284: * coordinates
285: * @see PointSound#setPosition(float x, float y, float z)
286: * @see PointSound#setPosition(Point3f position)
287: */
288: public abstract void setPosition(int index, Point3d position);
289:
290: /**
291: * Sets this sound's distance gain elliptical attenuation (not
292: * including filter cutoff frequency) by defining corresponding
293: * arrays containing distances from the sound's origin and gain
294: * scale factors applied to all active positional sounds.
295: * Gain scale factor is applied to sound based on the distance
296: * the listener
297: * is from sound source.
298: * These attenuation parameters are ignored for BackgroundSound nodes.
299: * The back attenuation parameter is ignored for PointSound nodes.
300: * <P>
301: * The form of the attenuation parameters match that of the ConeSound method
302: * of the same name.
303: * A full description of this parameter and how it is used is in
304: * the documentation for ConeSound class.
305: * <P>
306: * This method should only be called by Java3D Core and NOT by any application.
307: * @param index device specific reference number to device driver sample
308: * @param frontDistance defines an array of distance along positive axis
309: * through which ellipses pass
310: * @param frontAttenuationScaleFactor gain scale factors
311: * @param backDistance defines an array of distance along the negative axis
312: * through which ellipses pass
313: * @param backAttenuationScaleFactor gain scale factors
314: * @see ConeSound#setDistanceGain(float[] frontDistance, float[] frontGain,
315: * float[] backDistance, float[] backGain)
316: * @see ConeSound#setDistanceGain(Point2f[] frontAttenuation,
317: * Point2f[] backAttenuation)
318: */
319: public abstract void setDistanceGain(int index,
320: double[] frontDistance,
321: float[] frontAttenuationScaleFactor, double[] backDistance,
322: float[] backAttenuationScaleFactor);
323:
324: /**
325: * Sets this sound's direction from the local coordinate vector provided.
326: * The form of the direction parameter matches that of the ConeSound method
327: * of the same name.
328: * A full description of this parameter and how it is used is in
329: * the documentation for the ConeSound class.
330: * <P>
331: * This method should only be called by Java3D Core and NOT by any application.
332: * @param index device specific reference number to device driver sample
333: * @param direction the new direction vector in local coordinates
334: * @see ConeSound#setDirection(float x, float y, float z)
335: * @see ConeSound#setDirection(Vector3f direction)
336: */
337: public abstract void setDirection(int index, Vector3d direction);
338:
339: /**
340: * Sets this sound's angular gain attenuation (including filter)
341: * by defining corresponding arrays containing angular offsets from
342: * the sound's axis, gain scale factors, and frequency cutoff applied
343: * to all active directional sounds.
344: * Gain scale factor is applied to sound based on the angle between the
345: * sound's axis and the ray from the sound source origin to the listener.
346: * The form of the attenuation parameter matches that of the ConeSound
347: * method of the same name.
348: * A full description of this parameter and how it is used is in
349: * the documentation for the ConeSound class.
350: * <P>
351: * This method should only be called by Java3D Core and NOT by any application.
352: * @param index device specific reference number to device driver sample
353: * @param filterType describes type (if any) of filtering defined by attenuation
354: * @param angle array containing angular distances from sound axis
355: * @param attenuationScaleFactor array containing gain scale factor
356: * @param filterCutoff array containing filter cutoff frequencies.
357: * The filter values for each tuples can be set to Sound.NO_FILTER.
358: * @see ConeSound#setAngularAttenuation(float[] distance, float[] gain,
359: * float[] filter)
360: * @see ConeSound#setAngularAttenuation(Point3f[] attenuation)
361: * @see ConeSound#setAngularAttenuation(Point2f[] attenuation)
362: */
363: public abstract void setAngularAttenuation(int index,
364: int filterType, double[] angle,
365: float[] attenuationScaleFactor, float[] filterCutoff);
366:
367: /**
368: * Changes the speed of sound factor.
369: * A full description of this parameter and how it is used is in
370: * the documentation for the AuralAttributes class.
371: * <P>
372: * This method should only be called by Java3D Core and NOT by any application.
373: * @param rolloff atmospheric gain scale factor (changing speed of sound)
374: * @see AuralAttributes#setRolloff
375: */
376: public abstract void setRolloff(float rolloff);
377:
378: /**
379: * Sets the Reflective Coefficient scale factor applied to distinct
380: * low-order early reflections of sound off the surfaces in the region
381: * defined by the current listening region.
382: * <P>
383: * A full description of this parameter and how it is used is in
384: * the documentation for the AuralAttributes class.
385: * <P>
386: * This method should only be called by Java3D Core and NOT by any application.
387: * @param coefficient reflection/absorption factor applied to reverb
388: * @see AuralAttributes#setReflectionCoefficient
389: */
390: public abstract void setReflectionCoefficient(float coefficient);
391:
392: /**
393: * Sets the reverberation delay time.
394: * In this form, while reverberation is being rendered, the parameter
395: * specifies the delay time between each order of late reflections
396: * explicitly given in milliseconds.
397: * A value for delay time of 0.0 disables
398: * reverberation.
399: * <P>
400: * A full description of this parameter and how it is used is in
401: * the documentation for the AuralAttributes class.
402: * <P>
403: * This method should only be called by Java3D Core and NOT by any application.
404: * @param reverbDelay time between each order of late reflection
405: * @see AuralAttributes#setReverbDelay(float reverbDelay)
406: */
407: public abstract void setReverbDelay(float reverbDelay);
408:
409: /**
410: * Sets the reverberation order of reflections.
411: * The reverbOrder parameter specifies the number of times reflections are added to
412: * reverberation being calculated. A value of -1 specifies an unbounded
413: * number of reverberations.
414: * A full description of this parameter and how it is used is in
415: * the documentation for the AuralAttributes class.
416: * <P>
417: * This method should only be called by Java3D Core and NOT by any application.
418: * @param reverbOrder number of times reflections added to reverb signal
419: * @see AuralAttributes#setReverbOrder
420: */
421: public abstract void setReverbOrder(int reverbOrder);
422:
423: /**
424: * Sets Distance Filter corresponding arrays containing distances and
425: * frequency cutoff applied to all active positional sounds.
426: * Gain scale factor is applied to sound based on the distance the listener
427: * is from the sound source.
428: * A full description of this parameter and how it is used is in
429: * the documentation for the AuralAttributes class.
430: * <P>
431: * This method should only be called by Java3D Core and NOT by any application.
432: * @param filterType denotes the type of filtering to be applied
433: * @param distance array of offset distances from sound origin
434: * @param filterCutoff array of frequency cutoff
435: * @see AuralAttributes#setDistanceFilter(float[] distance,
436: * float[] frequencyCutoff)
437: * @see AuralAttributes#setDistanceFilter(Point2f[] attenuation)
438: */
439: public abstract void setDistanceFilter(int filterType,
440: double[] distance, float[] filterCutoff);
441:
442: /**
443: * Specifies a scale factor applied to the frequency (or
444: * wavelength). A value less than 1.0 will result of slowing the playback
445: * rate of the sample. A value greater than 1.0 will increase the playback
446: * rate.
447: * This parameter is also used to expand or contract the usual
448: * frequency shift applied to the sound source due to Doppler effect
449: * calculations. Valid values are >= 0.0.
450: * A full description of this parameter and how it is used is in
451: * the documentation for the AuralAttributes class.
452: * <P>
453: * This method should only be called by Java3D Core and NOT by any application.
454: * @param frequencyScaleFactor factor applied to change of frequency
455: * @see AuralAttributes#setFrequencyScaleFactor
456: */
457: public abstract void setFrequencyScaleFactor(
458: float frequencyScaleFactor);
459:
460: /**
461: * Sets the Velocity scale factor applied during Doppler Effect calculation.
462: * This parameter specifies a scale factor applied to the velocity of sound
463: * relative to the listener's position and movement in relation to the sound's
464: * position and movement. This scale factor is multipled by the calculated
465: * velocity portion of the Doppler effect equation used during sound rendering.
466: * A full description of this parameter and how it is used is in
467: * the documentation for the AuralAttributes class.
468: * <P>
469: * This method should only be called by Java3D Core and NOT by any application.
470: * @param velocityScaleFactor applied to velocity of sound in relation
471: * to listener
472: * @see AuralAttributes#setVelocityScaleFactor
473: */
474: public abstract void setVelocityScaleFactor(
475: float velocityScaleFactor);
476:
477: /**
478: * Makes the sample 'play silently'.
479: * This method implements (as efficiently as possible) the muting
480: * of a playing sound sample. Ideally this is implemented by
481: * stopping a sample and freeing channel resources (rather than
482: * just setting the gain of the sample to zero).
483: * <P>
484: * This method should only be called by Java3D Core and NOT by any application.
485: * @param index device specific reference number to device driver sample
486: */
487: public abstract void muteSample(int index);
488:
489: /**
490: * Makes a silently playing sample audible.
491: * In the ideal, this restarts a muted sample by offset from the
492: * beginning by the number of milliseconds since the time the sample
493: * began playing (rather than setting gain to current non-zero gain).
494: * <P>
495: * This method should only be called by Java3D Core and NOT by any application.
496: * @param index device specific reference number to device driver sample
497: */
498: public abstract void unmuteSample(int index);
499:
500: /**
501: * Temporarily stops a cached sample from playing without resetting the
502: * sample's current pointer back to the beginning of the sound data so
503: * that it can be unpaused at a later time from the same location in the
504: * sample when the pause was initiated. Pausing a streaming, non-cached
505: * sound sample will be treated as a mute.
506: * <P>
507: * This method should only be called by Java3D Core and NOT by any application.
508: * @param index device specific reference number to device driver sample
509: */
510: public abstract void pauseSample(int index);
511:
512: /**
513: * Restarts the paused sample from the location in the sample where
514: * paused.
515: * <P>
516: * This method should only be called by Java3D Core and NOT by any application.
517: * @param index device specific reference number to device driver sample
518: */
519: public abstract void unpauseSample(int index);
520:
521: /**
522: *
523: * Explicitly updates a Sample.
524: * This method is called when a Sound is to be explicitly updated.
525: * It is only called when all a sounds parameters are known to have
526: * been passed to the audio device. In this way, an implementation
527: * can choose to perform lazy-evaluation of a sample, rather than
528: * updating the rendering state of the sample after every individual
529: * parameter changed.
530: * This method can be left as a null method if the implementor so chooses.
531: * <P>
532: * This method should only be called by Java3D Core and NOT by any application.
533: * @param index device specific reference number to device driver sample
534: */
535: public abstract void updateSample(int index);
536:
537: }
|