com.sun.j3d.audioengines.headspace
Class HeadspaceMixer

java.lang.Object
  |
  +--com.sun.j3d.audioengines.AudioEngine
        |
        +--com.sun.j3d.audioengines.AudioEngine3D
              |
              +--com.sun.j3d.audioengines.AudioEngine3DL2
                    |
                    +--com.sun.j3d.audioengines.headspace.HeadspaceMixer

All Implemented Interfaces:

AudioDevice, AudioDevice3D, AudioDevice3DL2

public class HeadspaceMixer

extends com.sun.j3d.audioengines.AudioEngine3DL2

The HeadspaceMixer Class defines an audio output device that accesses Headspace mixing engine.

Field Summary

protected float	deviceGain
protected static int	NOT_PAUSED
protected int	pause
protected static int	PAUSE_PENDING
protected static int	PAUSED
protected static int	RESUME_PENDING

Fields inherited from class com.sun.j3d.audioengines.AudioEngine3D

attribs, currentView, samples

Fields inherited from interface javax.media.j3d.AudioDevice3D

BACKGROUND_SOUND, BUFFERED_AUDIO_DATA, CONE_SOUND, POINT_SOUND, STREAMING_AUDIO_DATA

Fields inherited from interface javax.media.j3d.AudioDevice

HEADPHONES, MONO_SPEAKER, STEREO_SPEAKERS

Constructor Summary

HeadspaceMixer(PhysicalEnvironment physicalEnvironment)

Method Summary

void	clearSound(int index) Clears the fields associated with sample data for this sound.
boolean	close() Code to close the device
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.
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.
long	getSampleDuration(int index) Returns the duration in milliseconds of the sound sample, if this information can be determined.
long	getStartTime(int index) Returns the system time of when the sound was last "started".
int	getTotalChannels() Query total number of channels available for sound rendering for this audio device.
boolean	initialize() Code to initialize the device
void	muteSample(int index) Makes the sample 'play silently'.
void	pause() Pauses audio device engine without closing the device and associated threads.
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.
int	prepareSound(int soundType, MediaContainer soundData) Code to load sound data into a channel of device channel Load sound as one or mores sample into the Java Sound Mixer: a) as either a STREAM or CLIP based on whether cached is enabled b) positional and directional sounds use THREE samples per sound so index return for the first sample associated with prepared sound is incremented by 2.
void	resume() Resumes audio device engine (if previously paused) without reinitializing * the device.
void	setDirection(int index, Vector3d direction) Sets this sound's direction from the local coordinate vector provided.
void	setFrequencyScaleFactor(float scaleFactor) Set frequency scale factor for current aural attribute applied to all samples.
void	setGain(float scaleFactor) Set overall gain control of all sounds playing on the audio device.
void	setLoop(int index, int count) Sets a sound's loop count.
void	setPosition(int index, Point3d position) Sets this sound's location (in Local coordinates) from specified Point.
void	setRateScaleFactor(int index, float rateScaleFactor) Set scale factor applied to sample playback rate for a particular sound associated with the audio device.
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.
void	setReverbDelay(float reverbDelay) Sets the reverberation delay time.
void	setReverbOrder(int reverbOrder) Sets the reverberation order of reflections.
void	setRolloff(float rolloff) Set rolloff value for current aural attribute applied to all samples.
void	setVelocityScaleFactor(float scaleFactor) Set velocity scale factor for current aural attribute applied to all samples when Doppler is calculated.
void	setVworldXfrm(int index, Transform3D trans) Save a reference to the local to virtual world coordinate space
int	startSample(int index) Begins a sound playing on the AudioDevice.
int	stopSample(int index) Stops the sound on the AudioDevice.
void	unmuteSample(int index) Makes a silently playing sample audible.
void	unpauseSample(int index) Restarts the paused sample from the location in the sample where paused.
void	updateSample(int index) Explicitly updates a Sample.

Methods inherited from class com.sun.j3d.audioengines.AudioEngine3DL2

setDecayFilter, setDecayTime, setDensity, setDiffusion, setObstructionFilter, setObstructionGain, setOcclusionFilter, setOcclusionGain, setReflectionDelay, setReverbCoefficient

Methods inherited from class com.sun.j3d.audioengines.AudioEngine3D

getAuralParameters, getSample, getSampleList, getSampleListSize, getView, setAngularAttenuation, setDistanceFilter, setDistanceGain, setSampleGain, setView

Methods inherited from class com.sun.j3d.audioengines.AudioEngine

getAngleOffsetToSpeaker, getAudioPlaybackType, getCenterEarToSpeaker, getChannelsAvailable, getChannelsUsedForSound, setAngleOffsetToSpeaker, setAudioPlaybackType, setCenterEarToSpeaker

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface javax.media.j3d.AudioDevice3D

setAngularAttenuation, setDistanceFilter, setDistanceGain, setSampleGain, setView

Methods inherited from interface javax.media.j3d.AudioDevice

getAngleOffsetToSpeaker, getAudioPlaybackType, getCenterEarToSpeaker, getChannelsAvailable, getChannelsUsedForSound, setAngleOffsetToSpeaker, setAudioPlaybackType, setCenterEarToSpeaker

Field Detail

deviceGain

protected float deviceGain

NOT_PAUSED

protected static final int NOT_PAUSED

See Also:

Constant Field Values

PAUSE_PENDING

protected static final int PAUSE_PENDING

See Also:

Constant Field Values

PAUSED

protected static final int PAUSED

See Also:

Constant Field Values

RESUME_PENDING

protected static final int RESUME_PENDING

See Also:

Constant Field Values

pause

protected int pause

Constructor Detail

HeadspaceMixer

public HeadspaceMixer(PhysicalEnvironment physicalEnvironment)

Method Detail

getTotalChannels

public int getTotalChannels()

Query total number of channels available for sound rendering for this audio device.

Specified by:

getTotalChannels in interface AudioDevice

Overrides:

getTotalChannels in class com.sun.j3d.audioengines.AudioEngine

Returns:

number of maximum voices play simultaneously on Headspace Mixer.

initialize

public boolean initialize()

Code to initialize the device

Specified by:

initialize in interface AudioDevice

Overrides:

initialize in class com.sun.j3d.audioengines.AudioEngine

Returns:

flag: true is initialized sucessfully, false if error

close

public boolean close()

Code to close the device

Specified by:

close in interface AudioDevice

Overrides:

close in class com.sun.j3d.audioengines.AudioEngine

Returns:

flag: true is closed sucessfully, false if error

prepareSound

public int prepareSound(int soundType,
                        MediaContainer soundData)

Code to load sound data into a channel of device channel Load sound as one or mores sample into the Java Sound Mixer: a) as either a STREAM or CLIP based on whether cached is enabled b) positional and directional sounds use THREE samples per sound so index return for the first sample associated with prepared sound is incremented by 2.

Specified by:

prepareSound in interface AudioDevice3D

Overrides:

prepareSound in class com.sun.j3d.audioengines.AudioEngine3D

Parameters:

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

soundData - reference to MediaContainer sound data and cached flag

Returns:

index to the (first or only) sample.

clearSound

public void clearSound(int index)

Clears the fields associated with sample data for this sound.

Specified by:

clearSound in interface AudioDevice3D

Overrides:

clearSound in class com.sun.j3d.audioengines.AudioEngine3D

Parameters:

index - device specific reference number to device driver sample

setVworldXfrm

public void setVworldXfrm(int index,
                          Transform3D trans)

Save a reference to the local to virtual world coordinate space

Specified by:

setVworldXfrm in interface AudioDevice3D

Overrides:

setVworldXfrm in class com.sun.j3d.audioengines.AudioEngine3D

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)

Description copied from interface: AudioDevice3D

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.

Specified by:

setPosition in interface AudioDevice3D

Overrides:

setPosition in class com.sun.j3d.audioengines.AudioEngine3D

Parameters:

index - device specific reference number to device driver sample

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

See Also:

PointSound.setPosition(float x, float y, float z), PointSound.setPosition(Point3f position)

setDirection

public void setDirection(int index,
                         Vector3d direction)

Description copied from interface: AudioDevice3D

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.

Specified by:

setDirection in interface AudioDevice3D

Overrides:

setDirection in class com.sun.j3d.audioengines.AudioEngine3D

Parameters:

index - device specific reference number to device driver sample

direction - the new direction vector in local coordinates

See Also:

ConeSound.setDirection(float x, float y, float z), ConeSound.setDirection(Vector3f direction)

setReflectionCoefficient

public void setReflectionCoefficient(float coefficient)

Description copied from interface: AudioDevice3D

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.

Specified by:

setReflectionCoefficient in interface AudioDevice3D

Overrides:

setReflectionCoefficient in class com.sun.j3d.audioengines.AudioEngine3D

Parameters:

coefficient - reflection/absorption factor applied to reverb

See Also:

AuralAttributes.setReflectionCoefficient(float)

setReverbDelay

public void setReverbDelay(float reverbDelay)

Description copied from interface: AudioDevice3D

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.

Specified by:

setReverbDelay in interface AudioDevice3D

Overrides:

setReverbDelay in class com.sun.j3d.audioengines.AudioEngine3D

Parameters:

reverbDelay - time between each order of late reflection

See Also:

AuralAttributes.setReverbDelay(float reverbDelay)

setReverbOrder

public void setReverbOrder(int reverbOrder)

Description copied from interface: AudioDevice3D

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.

Specified by:

setReverbOrder in interface AudioDevice3D

Overrides:

setReverbOrder in class com.sun.j3d.audioengines.AudioEngine3D

Parameters:

reverbOrder - number of times reflections added to reverb signal

See Also:

AuralAttributes.setReverbOrder(int)

startSample

public int startSample(int index)

Description copied from interface: AudioDevice3D

Begins a sound playing on the AudioDevice.

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

Specified by:

startSample in interface AudioDevice3D

Overrides:

startSample in class com.sun.j3d.audioengines.AudioEngine3D

Parameters:

index - device specific reference number to device driver sample

Returns:

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

stopSample

public int stopSample(int index)

Description copied from interface: AudioDevice3D

Stops the sound on the AudioDevice.

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

Specified by:

stopSample in interface AudioDevice3D

Overrides:

stopSample in class com.sun.j3d.audioengines.AudioEngine3D

Parameters:

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

Returns:

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

pauseSample

public void pauseSample(int index)

Description copied from interface: AudioDevice3D

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.

Specified by:

pauseSample in interface AudioDevice3D

Overrides:

pauseSample in class com.sun.j3d.audioengines.AudioEngine3D

Parameters:

index - device specific reference number to device driver sample

unpauseSample

public void unpauseSample(int index)

Description copied from interface: AudioDevice3D

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.

Specified by:

unpauseSample in interface AudioDevice3D

Overrides:

unpauseSample in class com.sun.j3d.audioengines.AudioEngine3D

Parameters:

index - device specific reference number to device driver sample

updateSample

public void updateSample(int index)

Description copied from interface: AudioDevice3D

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.

Specified by:

updateSample in interface AudioDevice3D

Overrides:

updateSample in class com.sun.j3d.audioengines.AudioEngine3D

Parameters:

index - device specific reference number to device driver sample

muteSample

public void muteSample(int index)

Description copied from interface: AudioDevice3D

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.

Specified by:

muteSample in interface AudioDevice3D

Overrides:

muteSample in class com.sun.j3d.audioengines.AudioEngine3D

Parameters:

index - device specific reference number to device driver sample

unmuteSample

public void unmuteSample(int index)

Description copied from interface: AudioDevice3D

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.

Specified by:

unmuteSample in interface AudioDevice3D

Overrides:

unmuteSample in class com.sun.j3d.audioengines.AudioEngine3D

Parameters:

index - device specific reference number to device driver sample

getSampleDuration

public long getSampleDuration(int index)

Description copied from interface: AudioDevice3D

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.

Specified by:

getSampleDuration in interface AudioDevice3D

Overrides:

getSampleDuration in class com.sun.j3d.audioengines.AudioEngine3D

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)

Description copied from interface: AudioDevice3D

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.

Specified by:

getNumberOfChannelsUsed in interface AudioDevice3D

Overrides:

getNumberOfChannelsUsed in class com.sun.j3d.audioengines.AudioEngine3D

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)

Description copied from interface: AudioDevice3D

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.

Specified by:

getNumberOfChannelsUsed in interface AudioDevice3D

Overrides:

getNumberOfChannelsUsed in class com.sun.j3d.audioengines.AudioEngine3D

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

getStartTime

public long getStartTime(int index)

Description copied from interface: AudioDevice3D

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.

Specified by:

getStartTime in interface AudioDevice3D

Overrides:

getStartTime in class com.sun.j3d.audioengines.AudioEngine3D

Parameters:

index - device specific reference number to device driver sample

Returns:

system time in milliseconds of the last time sound was started

setLoop

public void setLoop(int index,
                    int count)

Description copied from interface: AudioDevice3D

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.

Specified by:

setLoop in interface AudioDevice3D

Overrides:

setLoop in class com.sun.j3d.audioengines.AudioEngine3D

Parameters:

index - device specific reference number to device driver sample

See Also:

Sound.setLoop(int)

setGain

public void setGain(float scaleFactor)

Description copied from class: com.sun.j3d.audioengines.AudioEngine3DL2

Set overall gain control of all sounds playing on the audio device.

Specified by:

setGain in interface AudioDevice3DL2

Overrides:

setGain in class com.sun.j3d.audioengines.AudioEngine3DL2

Parameters:

scaleFactor - scale factor applied to calculated amplitudes for all sounds playing on this device

pause

public void pause()

Pauses audio device engine without closing the device and associated threads. Causes all cached sounds to be paused and all streaming sounds to be stopped.

Specified by:

pause in interface AudioDevice3DL2

Overrides:

pause in class com.sun.j3d.audioengines.AudioEngine3DL2

resume

public void resume()

Resumes audio device engine (if previously paused) without reinitializing * the device. Causes all paused cached sounds to be resumed and all streaming sounds restarted.

Specified by:

resume in interface AudioDevice3DL2

Overrides:

resume in class com.sun.j3d.audioengines.AudioEngine3DL2

setRateScaleFactor

public void setRateScaleFactor(int index,
                               float rateScaleFactor)

Description copied from class: com.sun.j3d.audioengines.AudioEngine3DL2

Set scale factor applied to sample playback rate for a particular sound associated with the audio device. Changing the device sample rate affects both the pitch and speed. This scale factor is applied to ALL sound types. Changes (scales) the playback rate of a sound independent of Doppler rate changes.

Specified by:

setRateScaleFactor in interface AudioDevice3DL2

Overrides:

setRateScaleFactor in class com.sun.j3d.audioengines.AudioEngine3DL2

Parameters:

index - device specific reference to device driver sample

rateScaleFactor - non-negative factor applied to calculated amplitudes for all sounds playing on this device

See Also:

Sound.setRateScaleFactor(float)

setRolloff

public void setRolloff(float rolloff)

Set rolloff value for current aural attribute applied to all samples. For each sample, recalculate rate and force this new rate to be applied.

Specified by:

setRolloff in interface AudioDevice3D

Overrides:

setRolloff in class com.sun.j3d.audioengines.AudioEngine3D

Parameters:

rolloff - scale factor applied to standard speed of sound.

See Also:

AuralAttributes.setRolloff(float)

setFrequencyScaleFactor

public void setFrequencyScaleFactor(float scaleFactor)

Set frequency scale factor for current aural attribute applied to all samples. For each sample, recalculate rate and force this new rate to be applied.

Specified by:

setFrequencyScaleFactor in interface AudioDevice3D

Overrides:

setFrequencyScaleFactor in class com.sun.j3d.audioengines.AudioEngine3D

Parameters:

scaleFactor - frequency scale factor applied to samples normal playback rate.

See Also:

AuralAttributes.setFrequencyScaleFactor(float)

setVelocityScaleFactor

public void setVelocityScaleFactor(float scaleFactor)

Set velocity scale factor for current aural attribute applied to all samples when Doppler is calculated. For each sample, recalculate rate and force this new rate to be applied.

Specified by:

setVelocityScaleFactor in interface AudioDevice3D

Overrides:

setVelocityScaleFactor in class com.sun.j3d.audioengines.AudioEngine3D

Parameters:

scaleFactor - scale factor applied to postional samples' listener-to-soundSource velocity. playback rate.

See Also:

AuralAttributes.setVelocityScaleFactor(float)