javax.media.j3d
Interface AudioDevice3D

public interface AudioDevice3D

extends AudioDevice

The methods in this interface SHOULD NOT BE CALLED AN APPLICATION. These are only to be called by Core Java 3D Sound classes.

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 choosen audio rendering to be performed on. Methods in this interface include:

Set up and clearing 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

Field Summary

static int	BACKGROUND_SOUND Sound Types Sound types match the Sound node classes defined for Java 3D core for BackgroundSound, PointSound and ConeSound.
static int	BUFFERED_AUDIO_DATA Sound data specified as Buffered is copied by the AudioDevice driver implementation.
static int	CONE_SOUND
static int	POINT_SOUND
static int	STREAMING_AUDIO_DATA Sound data specified as Streaming is not copied by the AudioDevice driver implementation.

Fields inherited from interface javax.media.j3d.AudioDevice

HEADPHONES, MONO_SPEAKER, STEREO_SPEAKERS

Method Summary

void	clearSound(int index) Clear sound The method clearSound() requests that the AudioDevice free all resources associated with sample with index id.
int	getNumberOfChannelsUsed(int index) Query number of channels used by Sound Retrieves number of channels (on executing audio device) that this sound is using, if its playing, or is expected to use if it were begun to be played.
int	getNumberOfChannelsUsed(int index, boolean muted) Query number of channels used by Sound Retrieves number of channels (on executing audio device) that this sound is using, if its playing, or is projected to use if were to be started playing.
long	getSampleDuration(int index) Query Sample Duration If it can be determined this method getSampleDuration() returns the duration in milliseconds of the the sound sample.
long	getStartTime(int index) Query last Start Time for this sound on the device This method getStartTime() returns the system time of when the sound was last "started".
void	muteSample(int index) Mute Sample Makes the sample 'play silently'.
void	pauseSample(int index) Pause Sample 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.
int	prepareSound(int soundType, MediaContainer soundData) Prepare Sound The method prepareSound() accepts a reference to the MediaContainer which contains a reference to sound data and information about the type of data it is.
void	setAngularAttenuation(int index, int filterType, double[] angle, float[] attenuationScaleFactor, float[] filterCutoff) Set Angular Attenuation 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.
void	setDirection(int index, Vector3d direction) Set Direction Sets this sound's direction from the local coordinate vector provided.
void	setDistanceFilter(int filterType, double[] distance, float[] filterCutoff) Set AuralAttribute Distance Filter Set Distance Filter corresponding arrays containing distances and frequency cutoff applied to all active positional sounds.
void	setDistanceGain(int index, double[] frontDistance, float[] frontAttenuationScaleFactor, double[] backDistance, float[] backAttenuationScaleFactor) Set Distance Gain 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.
void	setFrequencyScaleFactor(float frequencyScaleFactor) Set AuralAttribute Frequency Scale Factor This parameter specifies a scale factor applied to the frequency (or wavelength).
void	setLoop(int index, int count) Set Loop Count Sets a sound's loop count.
void	setPosition(int index, Point3d position) Set Position Sets this sound's location (in Local coordinates) from provided Point.
void	setReflectionCoefficient(float coefficient) Set AuralAttribute Reverberation Coeffient Set Reflective Coefficient scale factor defining the reflective/ absortive characteristic if the surfaces in the region defined by the current Soundscape region.
void	setReverbDelay(float reverbDelay) Set AuralAttribute Reverberation Delay Sets revereration delay time.
void	setReverbOrder(int reverbOrder) Set AuralAttribute Reverberation Order Sets reverberation order of reflections Its parameter specifies the number of times reflections are added to reverberation being calculated.
void	setRolloff(float rolloff) Set AuralAttribute Gain Rolloff Used to change the speed of sound factor.
void	setSampleGain(int index, float scaleFactor) Set Gain Scale Factor Set the overall gain scale factor applied to data associated with this source to increase or decrease its overall amplitude.
void	setVelocityScaleFactor(float velocityScaleFactor) Set AuralAttribute Velocity Scale Factor Set Velocity scale factor applied during Doppler Effect calculation.
void	setView(View reference) Set View The method setView() accepts a reference to the current View.
void	setVworldXfrm(int index, Transform3D trans) Set Virtual World Transform Passes a reference to the concatenated tranformation to be applied to local sound position and direction parameters.
int	startSample(int index) Start Sample This method startSample() begins a sound playing on the AudioDevice.
int	stopSample(int index) Stop Sample This method stopSample() stops the sound on the AudioDevice.
void	unmuteSample(int index) Unmute Sample Make a silently playing sample audible.
void	unpauseSample(int index) Unpause Sample Restarts the paused sample from the location in the sample where paused.
void	updateSample(int index) Explicit Update of a Sample This method is called when a Sound is to be explicitly updated.

Methods inherited from interface javax.media.j3d.AudioDevice

close, getAngleOffsetToSpeaker, getAudioPlaybackType, getCenterEarToSpeaker, getChannelsAvailable, getChannelsUsedForSound, getTotalChannels, initialize, setAngleOffsetToSpeaker, setAudioPlaybackType, setCenterEarToSpeaker

Field Detail

BACKGROUND_SOUND

public static final int BACKGROUND_SOUND

Sound Types Sound types match the Sound node classes defined for Java 3D core for BackgroundSound, PointSound and ConeSound. Type of sound a sample is loaded as determines which methods affect it.

POINT_SOUND

public static final int POINT_SOUND

CONE_SOUND

public static final int CONE_SOUND

STREAMING_AUDIO_DATA

public static final int STREAMING_AUDIO_DATA

Sound data specified as Streaming is not copied by the AudioDevice driver implementation. It is up the application to ensure that this data is continuously accessible during sound rendering. Futhermore, full sound spatialization may not be possible, for all AudioDevice3D implementations on unbuffered sound data.

BUFFERED_AUDIO_DATA

public static final int BUFFERED_AUDIO_DATA

Sound data specified as Buffered is copied by the AudioDevice driver implementation.

Method Detail

setView

public void setView(View reference)

Set View The method setView() 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 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.

Parameters:

reference - the current View

prepareSound

public int prepareSound(int soundType,
                        MediaContainer soundData)

Prepare Sound The method prepareSound() 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, a 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 are a parameter.

This method should only be called by Java3D Core and NOT by any application.

Parameters:

soundType - defines the type of Sound Node: Background, Point and Cone

soundData - reference to MediaContainer sound data and cached flag.

Returns:

device specific sample index used for referencing this sound.

clearSound

public void clearSound(int index)

Clear sound The method clearSound() 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.

Parameters:

index - device specific reference number to device driver sample

getSampleDuration

public long getSampleDuration(int index)

Query Sample Duration If it can be determined this method getSampleDuration() returns the duration in milliseconds of the the sound sample. For non-cached streams, this method returns Sound.DURATION_UNKNOWN.

This method should only be called by Java3D Core and NOT by any application.

Parameters:

index - device specific reference number to device driver sample

Returns:

sound duration in milliseconds if this can be determined, otherwise (for non-cached streams) Sound.DURATION_UNKNOWN is returned.

getNumberOfChannelsUsed

public int getNumberOfChannelsUsed(int index)

Query number of channels used by Sound Retrieves number of channels (on executing audio device) that this sound is using, if its playing, or is expected to use if it were begun to be played. This form of this method takes the sound's current state (included 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.

Parameters:

index - device specific reference number to device driver sample

Returns:

number of channels used by sound if it were playing

getNumberOfChannelsUsed

public int getNumberOfChannelsUsed(int index,
                                   boolean muted)

Query number of channels used by Sound Retrieves number of channels (on executing audio device) that this sound is using, if its playing, or is projected to use if 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.

Parameters:

index - device specific reference number to device driver sample

muted - flag to use as the current muted state ignoring current mute state.

Returns:

number of channels used by sound if it were playing

startSample

public int startSample(int index)

Start Sample This method startSample() begins a sound playing on the AudioDevice.

This method should only be called by Java3D Core and NOT by any application.

Parameters:

index - device specific reference number to device driver sample

Returns:

flag denoting is sample was started; 1 for true, 0 if false

getStartTime

public long getStartTime(int index)

Query last Start Time for this sound on the device This method getStartTime() 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.

Parameters:

index - device specific reference number to device driver sample

Returns:

system time in milliseconds of the last time sound was started

stopSample

public int stopSample(int index)

Stop Sample This method stopSample() stops the sound on the AudioDevice.

This method should only be called by Java3D Core and NOT by any application.

Parameters:

index - device specific reference number to device driver sample associated with sound data to be played.

Returns:

flag denoting is sample was stopped; 1 for true, 0 if false

setSampleGain

public void setSampleGain(int index,
                          float scaleFactor)

Set Gain Scale Factor Set 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 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.

Parameters:

index - device specific reference number to device driver sample

amplitude - (gain) scale factor

setLoop

public void setLoop(int index,
                    int count)

Set Loop Count Sets a sound's loop count. A full description of this parameter and how it is be used is in the documentation for Sound.setLoop.

This method should only be called by Java3D Core and NOT by any application.

Parameters:

index - device specific reference number to device driver sample

loopCount - number of times sound is looped during play

setVworldXfrm

public void setVworldXfrm(int index,
                          Transform3D trans)

Set Virtual World Transform Passes a reference to the concatenated tranformation to be applied to local sound position and direction parameters.

This method should only be called by Java3D Core and NOT by any application.

Parameters:

index - device specific reference number to device driver sample

trans - transformation matrix applied to local coordinate parameters

setPosition

public void setPosition(int index,
                        Point3d position)

Set Position Sets this sound's location (in Local coordinates) from provided 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 be used is in the documentation for PointSound class.

This method should only be called by Java3D Core and NOT by any application.

Parameters:

index - device specific reference number to device driver sample

position - location of Point or Cone Sound in Virtual World coordinates

setDistanceGain

public void setDistanceGain(int index,
                            double[] frontDistance,
                            float[] frontAttenuationScaleFactor,
                            double[] backDistance,
                            float[] backAttenuationScaleFactor)

Set Distance Gain 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 distance 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 be used is in the documentation for ConeSound class.

This method should only be called by Java3D Core and NOT by any application.

Parameters:

index - device specific reference number to device driver sample

frontDistance - defines an array of distance along positive axis thru which ellipses pass

frontAttenuationScaleFactor - gain scale factors

backDistance - defines an array of distance along the negative axis thru which ellipses pass

backAttenuationScaleFactor - gain scale factors

setDirection

public void setDirection(int index,
                         Vector3d direction)

Set Direction 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 be used is in the documentation for ConeSound class.

This method should only be called by Java3D Core and NOT by any application.

Parameters:

index - device specific reference number to device driver sample

direction - the new direction vector in local coordinates

setAngularAttenuation

public void setAngularAttenuation(int index,
                                  int filterType,
                                  double[] angle,
                                  float[] attenuationScaleFactor,
                                  float[] filterCutoff)

Set Angular Attenuation 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 angle betweent 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 be used is in the documentation for ConeSound class.

This method should only be called by Java3D Core and NOT by any application.

Parameters:

index - device specific reference number to device driver sample

filterType - describes type (if any) of filtering defined by attenuation

angle - array containing angular distances from sound axis

attenuationScaleFactor - array containing gain scale factor

filterCutoff - array containing filter cutoff frequencies. The filter values for each tuples can be set to Sound.NO_FILTER.

setRolloff

public void setRolloff(float rolloff)

Set AuralAttribute Gain Rolloff Used to change the speed of sound factor. A full description of this parameter and how it is be used is in the documentation for AuralAttribute class.

This method should only be called by Java3D Core and NOT by any application.

Parameters:

rolloff - atmospheric gain scale factor (changing speed of sound)

setReflectionCoefficient

public void setReflectionCoefficient(float coefficient)

Set AuralAttribute Reverberation Coeffient Set Reflective Coefficient scale factor defining the reflective/ absortive characteristic if the surfaces in the region defined by the current Soundscape region. A full description of this parameter and how it is be used is in the documentation for AuralAttribute class.

This method should only be called by Java3D Core and NOT by any application.

Parameters:

coefficient - reflection/absorption factor applied to reverb

setReverbDelay

public void setReverbDelay(float reverbDelay)

Set AuralAttribute Reverberation Delay Sets revereration 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. A value for delay time of 0.0 disables reverberation. A full description of this parameter and how it is be used is in the documentation for AuralAttribute class.

This method should only be called by Java3D Core and NOT by any application.

Parameters:

reverbDelay - time between each order of reflection

setReverbOrder

public void setReverbOrder(int reverbOrder)

Set AuralAttribute Reverberation Order Sets reverberation order of reflections Its 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 be used is in the documentation for AuralAttribute class.

This method should only be called by Java3D Core and NOT by any application.

Parameters:

reverbOrder - number of times reflections added to reverb signal

setDistanceFilter

public void setDistanceFilter(int filterType,
                              double[] distance,
                              float[] filterCutoff)

Set AuralAttribute Distance Filter Set Distance Filter corresponding arrays containing distances and frequency cutoff applied to all active positional sounds. Gain scale factor is applied to sound based on distance listener is from sound source. A full description of this parameter and how it is be used is in the documentation for AuralAttribute class.

This method should only be called by Java3D Core and NOT by any application.

Parameters:

filterType - denotes the type of filtering to be applied

distance - array of offset distances from sound origin

filterCutoff - array of frequency cutoff

setFrequencyScaleFactor

public void setFrequencyScaleFactor(float frequencyScaleFactor)

Set AuralAttribute Frequency Scale Factor This parameter 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 be 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 be used is in the documentation for AuralAttribute class.

This method should only be called by Java3D Core and NOT by any application.

Parameters:

frequencyScaleFactor - factor applied to change of frequency

setVelocityScaleFactor

public void setVelocityScaleFactor(float velocityScaleFactor)

Set AuralAttribute Velocity Scale Factor Set Velocity scale factor applied during Doppler Effect calculation. This parameter specifies a scale factor applied to the velocity of sound relative to 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 Doppler effect equation used during sound rendering. A full description of this parameter and how it is be used is in the documentation for AuralAttribute class.

This method should only be called by Java3D Core and NOT by any application.

Parameters:

velocityScaleFactor - applied to velocity of sound in relation to listener

muteSample

public void muteSample(int index)

Mute Sample Makes the sample 'play silently'. This methods 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.

Parameters:

index - device specific reference number to device driver sample

unmuteSample

public void unmuteSample(int index)

Unmute Sample Make 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.

Parameters:

index - device specific reference number to device driver sample

pauseSample

public void pauseSample(int index)

Pause Sample 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.

Parameters:

index - device specific reference number to device driver sample

unpauseSample

public void unpauseSample(int index)

Unpause Sample 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.

Parameters:

index - device specific reference number to device driver sample

updateSample

public void updateSample(int index)

Explicit Update of 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 choose.

This method should only be called by Java3D Core and NOT by any application.

Parameters:

index - device specific reference number to device driver sample