javax.media.j3d.AudioDevice3D Maven / Gradle / Ivy
Show all versions of java3d-core Show documentation
/*
* 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.
*
* 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.
*
* The intent is for this interface to be implemented by AudioDevice Driver
* developers using a software or hardware sound engine of their choice.
*
* 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:
*
* Set up and clear the sound as a sample on the device.
*
* Start, stop, pause, unpause, mute, and unmute of sample on the device.
*
* Set parameters for each sample corresponding to the fields in the
* Sound node.
*
* Set the current active aural parameters that affect all positional samples.
*
*
* Sound Types
*
* 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.
*
*
* Sound Data Types
*
* 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).
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* For some AudioDevice3D implementations:
*
* Muted sound take channels up on the systems mixer (because they're
* rendered as samples playing with gain zero.
*
* A single sound could be rendered using multiple samples, each taking
* up mixer channels.
*
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* A full description of this parameter and how it is used is in
* the documentation for the AuralAttributes class.
*
* 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.
*
* A full description of this parameter and how it is used is in
* the documentation for the AuralAttributes class.
*
* 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.
*
* 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.
*
* 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.
*
* 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.
*
* 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).
*
* 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).
*
* 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.
*
* 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.
*
* 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.
*
* 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);
}