diff options
Diffstat (limited to 'src/javax/media/j3d/AudioDevice3D.java')
| -rw-r--r-- | src/javax/media/j3d/AudioDevice3D.java | 533 |
1 files changed, 533 insertions, 0 deletions
diff --git a/src/javax/media/j3d/AudioDevice3D.java b/src/javax/media/j3d/AudioDevice3D.java new file mode 100644 index 0000000..7f152e4 --- /dev/null +++ b/src/javax/media/j3d/AudioDevice3D.java @@ -0,0 +1,533 @@ +/* + * Copyright 1998-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; + +import javax.vecmath.Point2f; +import javax.vecmath.Point3d; +import javax.vecmath.Point3f; +import javax.vecmath.Vector3d; +import javax.vecmath.Vector3f; + + +/** + * The AudioDevice3D class defines a 3D audio device that is used to set + * sound and aural attributes. + *<P> + * After the application chooses the AudioDevice3D 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. + *<P> + * The intent is for this interface to be implemented by AudioDevice Driver + * developers using a software or hardware sound engine of their choice. + *<P> + * 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. Methods in this interface include: + * <UL> + * Set up and clear the sound as a sample on the device. + * <P> + * Start, stop, pause, unpause, mute, and unmute of sample on the device. + * <P> + * Set parameters for each sample corresponding to the fields in the + * Sound node. + * <P> + * Set the current active aural parameters that affect all positional samples. + * </UL> + * <P> + * Sound Types + * <P> + * Sound types match the Sound node classes defined for Java 3D core + * for BackgroundSound, PointSound, and ConeSound. The type of sound + * a sample is loaded as determines which methods affect it. + * + * <P> + * Sound Data Types + * <P> + * Samples can be processed as streaming or buffered data. + * Fully spatializing sound sources may require data to be buffered. + * + */ + +public interface AudioDevice3D extends AudioDevice { + + /** + * Specifies the sound type as background sound. + */ + public static final int BACKGROUND_SOUND = 1; + + /** + * Specifies the sound type as point sound. + */ + public static final int POINT_SOUND = 2; + + /** + * Specifies the sound type as cone sound. + */ + + public static final int CONE_SOUND = 3; + + /** + * Sound data specified as Streaming is not copied by the AudioDevice + * driver implementation. It is up to the application to ensure that + * this data is continuously accessible during sound rendering. + * Furthermore, full sound spatialization may not be possible, for + * all AudioDevice3D implementations on unbuffered sound data. + */ + public static final int STREAMING_AUDIO_DATA = 1; + /** + * Sound data specified as Buffered is copied by the AudioDevice + * driver implementation. + */ + public static final int BUFFERED_AUDIO_DATA = 2; + + + /** + * Accepts a reference to the current View. + * Passes reference to current View Object. The PhysicalEnvironment + * parameters (with playback type and speaker placement), and the + * PhysicalBody parameters (position/orientation of ears) + * can be obtained from this object, and the transformations to/from + * ViewPlatform coordinate (space the listener's head is in) and + * Virtual World coordinates (space sounds are in). + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param reference the current View + */ + public abstract void setView(View reference); + + /** + * Accepts a reference to the MediaContainer + * which contains a reference to sound data and information about the + * type of data it is. A "sound type" input parameter denotes if the + * Java 3D sound associated with this sample is a Background, Point, or + * Cone Sound node. + * Depending on the type of MediaContainer the sound data is and on the + * implementation of the AudioDevice used, sound data preparation could + * consist of opening, attaching, or loading sound data into the device. + * Unless the cached flag is true, this sound data should NOT be copied, + * if possible, into host or device memory. + *<P> + * Once this preparation is complete for the sound sample, an AudioDevice + * specific index, used to reference the sample in future method calls, + * is returned. All the rest of the methods described below require + * this index as a parameter. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param soundType defines the type of Sound Node: Background, Point, and + * Cone + * @param soundData reference to MediaContainer sound data and cached flag + * @return device specific sample index used for referencing this sound + */ + public abstract int prepareSound(int soundType, MediaContainer soundData); + + /** + * Requests that the AudioDevice free all + * resources associated with sample with index id. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param index device specific reference number to device driver sample + */ + public abstract void clearSound(int index); + + /** + * Returns the duration in milliseconds of the sound sample, + * if this information can be determined. + * For non-cached + * streams, this method returns Sound.DURATION_UNKNOWN. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param index device specific reference number to device driver sample + * @return sound duration in milliseconds if this can be determined, + * otherwise (for non-cached streams) Sound.DURATION_UNKNOWN is returned + */ + public abstract long getSampleDuration(int index); + + /** + * + * Retrieves the number of channels (on executing audio device) that + * this sound is using, if it is playing, or is expected to use + * if it were begun to be played. This form of this method takes the + * sound's current state (including whether it is muted or unmuted) + * into account. + *<P> + * For some AudioDevice3D implementations: + *<UL> + * Muted sound take channels up on the systems mixer (because they're + * rendered as samples playing with gain zero. + *<P> + * A single sound could be rendered using multiple samples, each taking + * up mixer channels. + *</UL> + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param index device specific reference number to device driver sample + * @return number of channels used by sound if it were playing + */ + public abstract int getNumberOfChannelsUsed(int index); + + /** + * + * Retrieves the number of channels (on executing audio device) that + * this sound is using, if it is playing, or is projected to use if + * it were to be started playing. Rather than using the actual current + * muted/unmuted state of the sound, the muted parameter is used in + * making the determination. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param index device specific reference number to device driver sample + * @param muted flag to use as the current muted state ignoring current + * mute state + * @return number of channels used by sound if it were playing + */ + public abstract int getNumberOfChannelsUsed(int index, boolean muted); + + /** + * Begins a sound playing on the AudioDevice. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param index device specific reference number to device driver sample + * @return flag denoting if sample was started; 1 if true, 0 if false + */ + public abstract int startSample(int index); + + /** + * Returns the system time of when the sound + * was last "started". Note that this start time will be as accurate + * as the AudioDevice implementation can make it - but that it is not + * guaranteed to be exact. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param index device specific reference number to device driver sample + * @return system time in milliseconds of the last time sound was started + */ + public abstract long getStartTime(int index); + + /** + * Stops the sound on the AudioDevice. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param index device specific reference number to device driver sample + * associated with sound data to be played + * @return flag denoting if sample was stopped; 1 if true, 0 if false + */ + public abstract int stopSample(int index); + + /** + * Sets the overall gain scale factor applied to data associated with this + * source to increase or decrease its overall amplitude. + * The gain scale factor value passed into this method is the combined value + * of the Sound node's Initial Gain and the current AuralAttribute Gain + * scale factors. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param index device specific reference number to device driver sample + * @param scaleFactor amplitude (gain) scale factor + */ + public abstract void setSampleGain(int index, float scaleFactor); + + /** + * Sets a sound's loop count. + * A full description of this parameter and how it is used is in + * the documentation for Sound.setLoop. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param index device specific reference number to device driver sample + * @param count number of times sound is looped during play + * @see Sound#setLoop + */ + public abstract void setLoop(int index, int count); + + /** + * Passes a reference to the concatenated transformation to be applied to + * local sound position and direction parameters. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param index device specific reference number to device driver sample + * @param trans transformation matrix applied to local coordinate parameters + */ + public abstract void setVworldXfrm(int index, Transform3D trans); + + + /** + * Sets this sound's location (in Local coordinates) from specified + * Point. The form of the position parameter matches those of the PointSound + * method of the same name. + * A full description of this parameter and how it is used is in + * the documentation for PointSound class. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param index device specific reference number to device driver sample + * @param position location of Point or Cone Sound in Virtual World + * coordinates + * @see PointSound#setPosition(float x, float y, float z) + * @see PointSound#setPosition(Point3f position) + */ + public abstract void setPosition(int index, Point3d position); + + /** + * Sets this sound's distance gain elliptical attenuation (not + * including filter cutoff frequency) by defining corresponding + * arrays containing distances from the sound's origin and gain + * scale factors applied to all active positional sounds. + * Gain scale factor is applied to sound based on the distance + * the listener + * is from sound source. + * These attenuation parameters are ignored for BackgroundSound nodes. + * The back attenuation parameter is ignored for PointSound nodes. + * <P> + * The form of the attenuation parameters match that of the ConeSound method + * of the same name. + * A full description of this parameter and how it is used is in + * the documentation for ConeSound class. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param index device specific reference number to device driver sample + * @param frontDistance defines an array of distance along positive axis + * through which ellipses pass + * @param frontAttenuationScaleFactor gain scale factors + * @param backDistance defines an array of distance along the negative axis + * through which ellipses pass + * @param backAttenuationScaleFactor gain scale factors + * @see ConeSound#setDistanceGain(float[] frontDistance, float[] frontGain, + * float[] backDistance, float[] backGain) + * @see ConeSound#setDistanceGain(Point2f[] frontAttenuation, + * Point2f[] backAttenuation) + */ + public abstract void setDistanceGain(int index, + double[] frontDistance, float[] frontAttenuationScaleFactor, + double[] backDistance, float[] backAttenuationScaleFactor); + /** + * Sets this sound's direction from the local coordinate vector provided. + * The form of the direction parameter matches that of the ConeSound method + * of the same name. + * A full description of this parameter and how it is used is in + * the documentation for the ConeSound class. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param index device specific reference number to device driver sample + * @param direction the new direction vector in local coordinates + * @see ConeSound#setDirection(float x, float y, float z) + * @see ConeSound#setDirection(Vector3f direction) + */ + public abstract void setDirection(int index, Vector3d direction); + + /** + * Sets this sound's angular gain attenuation (including filter) + * by defining corresponding arrays containing angular offsets from + * the sound's axis, gain scale factors, and frequency cutoff applied + * to all active directional sounds. + * Gain scale factor is applied to sound based on the angle between the + * sound's axis and the ray from the sound source origin to the listener. + * The form of the attenuation parameter matches that of the ConeSound + * method of the same name. + * A full description of this parameter and how it is used is in + * the documentation for the ConeSound class. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param index device specific reference number to device driver sample + * @param filterType describes type (if any) of filtering defined by attenuation + * @param angle array containing angular distances from sound axis + * @param attenuationScaleFactor array containing gain scale factor + * @param filterCutoff array containing filter cutoff frequencies. + * The filter values for each tuples can be set to Sound.NO_FILTER. + * @see ConeSound#setAngularAttenuation(float[] distance, float[] gain, + * float[] filter) + * @see ConeSound#setAngularAttenuation(Point3f[] attenuation) + * @see ConeSound#setAngularAttenuation(Point2f[] attenuation) + */ + public abstract void setAngularAttenuation(int index, int filterType, + double[] angle, float[] attenuationScaleFactor, float[] filterCutoff); + + /** + * Changes the speed of sound factor. + * A full description of this parameter and how it is used is in + * the documentation for the AuralAttributes class. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param rolloff atmospheric gain scale factor (changing speed of sound) + * @see AuralAttributes#setRolloff + */ + public abstract void setRolloff(float rolloff); + + /** + * Sets the Reflective Coefficient scale factor applied to distinct + * low-order early reflections of sound off the surfaces in the region + * defined by the current listening region. + * <P> + * A full description of this parameter and how it is used is in + * the documentation for the AuralAttributes class. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param coefficient reflection/absorption factor applied to reverb + * @see AuralAttributes#setReflectionCoefficient + */ + public abstract void setReflectionCoefficient(float coefficient); + + /** + * Sets the reverberation delay time. + * In this form, while reverberation is being rendered, the parameter + * specifies the delay time between each order of late reflections + * explicitly given in milliseconds. + * A value for delay time of 0.0 disables + * reverberation. + * <P> + * A full description of this parameter and how it is used is in + * the documentation for the AuralAttributes class. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param reverbDelay time between each order of late reflection + * @see AuralAttributes#setReverbDelay(float reverbDelay) + */ + public abstract void setReverbDelay(float reverbDelay); + + /** + * Sets the reverberation order of reflections. + * The reverbOrder parameter specifies the number of times reflections are added to + * reverberation being calculated. A value of -1 specifies an unbounded + * number of reverberations. + * A full description of this parameter and how it is used is in + * the documentation for the AuralAttributes class. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param reverbOrder number of times reflections added to reverb signal + * @see AuralAttributes#setReverbOrder + */ + public abstract void setReverbOrder(int reverbOrder); + + /** + * Sets Distance Filter corresponding arrays containing distances and + * frequency cutoff applied to all active positional sounds. + * Gain scale factor is applied to sound based on the distance the listener + * is from the sound source. + * A full description of this parameter and how it is used is in + * the documentation for the AuralAttributes class. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param filterType denotes the type of filtering to be applied + * @param distance array of offset distances from sound origin + * @param filterCutoff array of frequency cutoff + * @see AuralAttributes#setDistanceFilter(float[] distance, + * float[] frequencyCutoff) + * @see AuralAttributes#setDistanceFilter(Point2f[] attenuation) + */ + public abstract void setDistanceFilter(int filterType, + double[] distance, float[] filterCutoff); + + /** + * Specifies a scale factor applied to the frequency (or + * wavelength). A value less than 1.0 will result of slowing the playback + * rate of the sample. A value greater than 1.0 will increase the playback + * rate. + * This parameter is also used to expand or contract the usual + * frequency shift applied to the sound source due to Doppler effect + * calculations. Valid values are >= 0.0. + * A full description of this parameter and how it is used is in + * the documentation for the AuralAttributes class. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param frequencyScaleFactor factor applied to change of frequency + * @see AuralAttributes#setFrequencyScaleFactor + */ + public abstract void setFrequencyScaleFactor(float frequencyScaleFactor); + + /** + * Sets the Velocity scale factor applied during Doppler Effect calculation. + * This parameter specifies a scale factor applied to the velocity of sound + * relative to the listener's position and movement in relation to the sound's + * position and movement. This scale factor is multipled by the calculated + * velocity portion of the Doppler effect equation used during sound rendering. + * A full description of this parameter and how it is used is in + * the documentation for the AuralAttributes class. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param velocityScaleFactor applied to velocity of sound in relation + * to listener + * @see AuralAttributes#setVelocityScaleFactor + */ + public abstract void setVelocityScaleFactor(float velocityScaleFactor); + + /** + * Makes the sample 'play silently'. + * This method implements (as efficiently as possible) the muting + * of a playing sound sample. Ideally this is implemented by + * stopping a sample and freeing channel resources (rather than + * just setting the gain of the sample to zero). + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param index device specific reference number to device driver sample + */ + public abstract void muteSample(int index); + + /** + * Makes a silently playing sample audible. + * In the ideal, this restarts a muted sample by offset from the + * beginning by the number of milliseconds since the time the sample + * began playing (rather than setting gain to current non-zero gain). + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param index device specific reference number to device driver sample + */ + public abstract void unmuteSample(int index); + + /** + * Temporarily stops a cached sample from playing without resetting the + * sample's current pointer back to the beginning of the sound data so + * that it can be unpaused at a later time from the same location in the + * sample when the pause was initiated. Pausing a streaming, non-cached + * sound sample will be treated as a mute. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param index device specific reference number to device driver sample + */ + public abstract void pauseSample(int index); + + /** + * Restarts the paused sample from the location in the sample where + * paused. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param index device specific reference number to device driver sample + */ + public abstract void unpauseSample(int index); + + /** + * + * Explicitly updates a Sample. + * This method is called when a Sound is to be explicitly updated. + * It is only called when all a sounds parameters are known to have + * been passed to the audio device. In this way, an implementation + * can choose to perform lazy-evaluation of a sample, rather than + * updating the rendering state of the sample after every individual + * parameter changed. + * This method can be left as a null method if the implementor so chooses. + * <P> + * This method should only be called by Java3D Core and NOT by any application. + * @param index device specific reference number to device driver sample + */ + public abstract void updateSample(int index); + +} |