| javax.media.j3d.AudioDevice3D
All known Subclasses: org.jdesktop.j3d.audioengines.joal.JOALMixer, com.sun.j3d.audioengines.AudioEngine3D,
| AudioDevice3D | | public interface AudioDevice3D extends AudioDevice(Code) | | 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.
|
| Field Summary | |
| final public static int | BACKGROUND_SOUND
Specifies the sound type as background sound. | | final public static int | BUFFERED_AUDIO_DATA
Sound data specified as Buffered is copied by the AudioDevice
driver implementation. | | final public static int | CONE_SOUND
Specifies the sound type as cone sound. | | final public static int | POINT_SOUND
Specifies the sound type as point sound. | | final public static int | STREAMING_AUDIO_DATA
Sound data specified as Streaming is not copied by the AudioDevice
driver implementation. |
| Method Summary | |
| abstract public void | clearSound(int index)
Requests that the AudioDevice free all
resources associated with sample with index id. | | abstract public int | getNumberOfChannelsUsed(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. | | abstract public int | getNumberOfChannelsUsed(int index, boolean muted)
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. | | abstract public long | getSampleDuration(int index)
Returns the duration in milliseconds of the sound sample,
if this information can be determined. | | abstract public long | getStartTime(int index)
Returns the system time of when the sound
was last "started". | | abstract public void | muteSample(int index)
Makes the sample 'play silently'.
This method implements (as efficiently as possible) the muting
of a playing sound sample. | | abstract public void | pauseSample(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. | | abstract public int | prepareSound(int soundType, MediaContainer soundData)
Accepts a reference to the MediaContainer
which contains a reference to sound data and information about the
type of data it is. | | abstract public void | setAngularAttenuation(int index, int filterType, double[] angle, float[] attenuationScaleFactor, float[] filterCutoff)
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.
Parameters:
index - device specific reference number to device driver sample
Parameters:
filterType - describes type (if any) of filtering defined by attenuation
Parameters:
angle - array containing angular distances from sound axis
Parameters:
attenuationScaleFactor - array containing gain scale factor
Parameters:
filterCutoff - array containing filter cutoff frequencies.The filter values for each tuples can be set to Sound.NO_FILTER. | | abstract public void | setDirection(int index, Vector3d direction)
Sets this sound's direction from the local coordinate vector provided. | | abstract public void | setDistanceFilter(int filterType, double[] distance, float[] filterCutoff)
Sets Distance Filter corresponding arrays containing distances and
frequency cutoff applied to all active positional sounds. | | abstract public void | setDistanceGain(int index, double[] frontDistance, float[] frontAttenuationScaleFactor, double[] backDistance, float[] backAttenuationScaleFactor)
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. | | abstract public void | setFrequencyScaleFactor(float frequencyScaleFactor)
Specifies a scale factor applied to the frequency (or
wavelength). | | abstract public void | setLoop(int index, int count)
Sets a sound's loop count. | | abstract public void | setPosition(int index, Point3d position)
Sets this sound's location (in Local coordinates) from specified
Point. | | abstract public void | setReflectionCoefficient(float coefficient)
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. | | abstract public void | setReverbDelay(float reverbDelay)
Sets the reverberation delay time. | | abstract public void | setReverbOrder(int reverbOrder)
Sets the reverberation order of reflections.
The reverbOrder parameter specifies the number of times reflections are added to
reverberation being calculated. | | abstract public void | setRolloff(float rolloff)
Changes the speed of sound factor. | | abstract public void | setSampleGain(int index, float scaleFactor)
Sets the overall gain scale factor applied to data associated with this
source to increase or decrease its overall amplitude. | | abstract public void | setVelocityScaleFactor(float velocityScaleFactor)
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. | | abstract public void | setView(View reference)
Accepts a reference to the current View.
Passes reference to current View Object. | | abstract public void | setVworldXfrm(int index, Transform3D trans)
Passes a reference to the concatenated transformation to be applied to
local sound position and direction parameters. | | abstract public int | startSample(int index)
Begins a sound playing on the AudioDevice. | | abstract public int | stopSample(int index)
Stops the sound on the AudioDevice. | | abstract public void | unmuteSample(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). | | abstract public void | unpauseSample(int index)
Restarts the paused sample from the location in the sample where
paused. | | abstract public void | updateSample(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. |
| BACKGROUND_SOUND | | final public static int BACKGROUND_SOUND(Code) | | Specifies the sound type as background sound.
|
| BUFFERED_AUDIO_DATA | | final public static int BUFFERED_AUDIO_DATA(Code) | | Sound data specified as Buffered is copied by the AudioDevice
driver implementation.
|
| CONE_SOUND | | final public static int CONE_SOUND(Code) | | Specifies the sound type as cone sound.
|
| POINT_SOUND | | final public static int POINT_SOUND(Code) | | Specifies the sound type as point sound.
|
| STREAMING_AUDIO_DATA | | final public static int STREAMING_AUDIO_DATA(Code) | | 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.
|
| clearSound | | abstract public void clearSound(int index)(Code) | | 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 |
| getNumberOfChannelsUsed | | abstract public int getNumberOfChannelsUsed(int index)(Code) | | 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.
Parameters:
index - device specific reference number to device driver sample number of channels used by sound if it were playing |
| getNumberOfChannelsUsed | | abstract public int getNumberOfChannelsUsed(int index, boolean muted)(Code) | | 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.
Parameters:
index - device specific reference number to device driver sample
Parameters:
muted - flag to use as the current muted state ignoring currentmute state number of channels used by sound if it were playing |
| getSampleDuration | | abstract public long getSampleDuration(int index)(Code) | | 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.
Parameters:
index - device specific reference number to device driver sample sound duration in milliseconds if this can be determined,otherwise (for non-cached streams) Sound.DURATION_UNKNOWN is returned |
| getStartTime | | abstract public long getStartTime(int index)(Code) | | 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 system time in milliseconds of the last time sound was started |
| muteSample | | abstract public void muteSample(int index)(Code) | | 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.
Parameters:
index - device specific reference number to device driver sample |
| pauseSample | | abstract public void pauseSample(int index)(Code) | | 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 |
| prepareSound | | abstract public int prepareSound(int soundType, MediaContainer soundData)(Code) | | 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.
Parameters:
soundType - defines the type of Sound Node: Background, Point, and Cone
Parameters:
soundData - reference to MediaContainer sound data and cached flag device specific sample index used for referencing this sound |
| setAngularAttenuation | | abstract public void setAngularAttenuation(int index, int filterType, double[] angle, float[] attenuationScaleFactor, float[] filterCutoff)(Code) | | 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.
Parameters:
index - device specific reference number to device driver sample
Parameters:
filterType - describes type (if any) of filtering defined by attenuation
Parameters:
angle - array containing angular distances from sound axis
Parameters:
attenuationScaleFactor - array containing gain scale factor
Parameters:
filterCutoff - array containing filter cutoff frequencies.The filter values for each tuples can be set to Sound.NO_FILTER.
See Also: ConeSound.setAngularAttenuation(float[] distancefloat[] gainfloat[] filter)
See Also: ConeSound.setAngularAttenuation(Point3f[] attenuation)
See Also: ConeSound.setAngularAttenuation(Point2f[] attenuation) |
| setDirection | | abstract public void setDirection(int index, Vector3d direction)(Code) | | 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.
Parameters:
index - device specific reference number to device driver sample
Parameters:
direction - the new direction vector in local coordinates
See Also: ConeSound.setDirection(float xfloat yfloat z)
See Also: ConeSound.setDirection(Vector3f direction) |
| setDistanceFilter | | abstract public void setDistanceFilter(int filterType, double[] distance, float[] filterCutoff)(Code) | | 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.
Parameters:
filterType - denotes the type of filtering to be applied
Parameters:
distance - array of offset distances from sound origin
Parameters:
filterCutoff - array of frequency cutoff
See Also: AuralAttributes.setDistanceFilter(float[] distancefloat[] frequencyCutoff)
See Also:
See Also: AuralAttributes.setDistanceFilter(Point2f[] attenuation)
See Also: |
| setDistanceGain | | abstract public void setDistanceGain(int index, double[] frontDistance, float[] frontAttenuationScaleFactor, double[] backDistance, float[] backAttenuationScaleFactor)(Code) | | 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.
Parameters:
index - device specific reference number to device driver sample
Parameters:
frontDistance - defines an array of distance along positive axisthrough which ellipses pass
Parameters:
frontAttenuationScaleFactor - gain scale factors
Parameters:
backDistance - defines an array of distance along the negative axisthrough which ellipses pass
Parameters:
backAttenuationScaleFactor - gain scale factors
See Also: ConeSound.setDistanceGain(float[] frontDistancefloat[] frontGainfloat[] backDistancefloat[] backGain)
See Also: ConeSound.setDistanceGain(Point2f[] frontAttenuationPoint2f[] backAttenuation) |
| setFrequencyScaleFactor | | abstract public void setFrequencyScaleFactor(float frequencyScaleFactor)(Code) | | 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.
Parameters:
frequencyScaleFactor - factor applied to change of frequency
See Also: AuralAttributes.setFrequencyScaleFactor |
| setLoop | | abstract public void setLoop(int index, int count)(Code) | | 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.
Parameters:
index - device specific reference number to device driver sample
Parameters:
count - number of times sound is looped during play
See Also: Sound.setLoop |
| setPosition | | abstract public void setPosition(int index, Point3d position)(Code) | | 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.
Parameters:
index - device specific reference number to device driver sample
Parameters:
position - location of Point or Cone Sound in Virtual Worldcoordinates
See Also: PointSound.setPosition(float xfloat yfloat z)
See Also: PointSound.setPosition(Point3f position) |
| setReflectionCoefficient | | abstract public void setReflectionCoefficient(float coefficient)(Code) | | 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.
Parameters:
coefficient - reflection/absorption factor applied to reverb
See Also: AuralAttributes.setReflectionCoefficient |
| setReverbDelay | | abstract public void setReverbDelay(float reverbDelay)(Code) | | 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.
Parameters:
reverbDelay - time between each order of late reflection
See Also: AuralAttributes.setReverbDelay(float reverbDelay)
See Also: |
| setReverbOrder | | abstract public void setReverbOrder(int reverbOrder)(Code) | | 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.
Parameters:
reverbOrder - number of times reflections added to reverb signal
See Also: AuralAttributes.setReverbOrder |
| setRolloff | | abstract public void setRolloff(float rolloff)(Code) | | 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.
Parameters:
rolloff - atmospheric gain scale factor (changing speed of sound)
See Also: AuralAttributes.setRolloff |
| setSampleGain | | abstract public void setSampleGain(int index, float scaleFactor)(Code) | | 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.
Parameters:
index - device specific reference number to device driver sample
Parameters:
scaleFactor - amplitude (gain) scale factor |
| setVelocityScaleFactor | | abstract public void setVelocityScaleFactor(float velocityScaleFactor)(Code) | | 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.
Parameters:
velocityScaleFactor - applied to velocity of sound in relation to listener
See Also: AuralAttributes.setVelocityScaleFactor |
| setView | | abstract public void setView(View reference)(Code) | | 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.
Parameters:
reference - the current View |
| setVworldXfrm | | abstract public void setVworldXfrm(int index, Transform3D trans)(Code) | | 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.
Parameters:
index - device specific reference number to device driver sample
Parameters:
trans - transformation matrix applied to local coordinate parameters |
| startSample | | abstract public int startSample(int index)(Code) | | 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 flag denoting if sample was started; 1 if true, 0 if false |
| stopSample | | abstract public int stopSample(int index)(Code) | | 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 sampleassociated with sound data to be played flag denoting if sample was stopped; 1 if true, 0 if false |
| unmuteSample | | abstract public void unmuteSample(int index)(Code) | | 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.
Parameters:
index - device specific reference number to device driver sample |
| unpauseSample | | abstract public void unpauseSample(int index)(Code) | | 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 | | abstract public void updateSample(int index)(Code) | | 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.
Parameters:
index - device specific reference number to device driver sample |
|
|