Interface spatialAudio.SoundSource

All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface spatialAudio.SoundSource

public interface SoundSource
extends Object

The SoundSource interface controls the properties of a sound source in a 3D audio environment. This interface provides methods for controlling the position, orientation, and properties of the sound source.

See Also:: CachedSoundSource, StreamingSoundSource, RenderOptions

BUFFER_EVENT: Event id for buffer events generated when a streaming sound source has finished with a buffer and the buffer is free for reuse.
PLAYBACK_EVENT: Event id for cached sound source playback events generated when playback of a cached sound source is completed.

getCpuBudget(): Retrieves a RenderOptions value specifying the CPU budget for this SoundSource.
getInfo(): Retrieves the info value set by the application.
getMediaState(): Queries the state of the sound source and returns an instance of the MediaState class.
getModel(): Retrieves the sound source model which defines the extent, directionality, and intensity of the sound source.
getMuteState(): Retrieves the mute state of the SoundSource.
getOrientation(): Retrieves the 3D vector that defines the sound source's orientation.
getPitch(): Retrieves the pitch adjustment of the SoundSource.
getPosition(): Retrieves the X,Y,Z coordinates of the sound source's position.
move(float, float, float): Moves the position of the sound source by the X,Y,Z offsets provided.
move(Vector3D): Moves the position of the sound source by the X,Y,Z offsets provided.
release(): Requests that any resources associated with the SoundSource object be freed.
setCpuBudget(int): Sets the CPU budget for this sound source, overriding the environment CPU budget for the sound source.
setInfo(Object): Sets the info value for the SoundSource.
setModel(SoundSourceModel): Sets the sound source model.
setMuteState(boolean): Sets the mute state of the SoundSource.
setOrientation(float, float, float): Sets the orientation of the SoundSource.
setOrientation(Vector3D): Sets the 3D vector that defines the SoundSource's orientation.
setPitch(float): Specifies the pitch adjustment of the sound source.
setPosition(float, float, float): Sets the X,Y,Z coordinates of the sound source's position.
setPosition(Vector3D): Sets the X,Y,Z coordinates of the sound source's position.

BUFFER_EVENT

  public final static int BUFFER_EVENT

Event id for buffer events generated when a streaming sound source has finished with a buffer and the buffer is free for reuse.

PLAYBACK_EVENT

  public final static int PLAYBACK_EVENT

Event id for cached sound source playback events generated when playback of a cached sound source is completed.

getModel

  public abstract SoundSourceModel getModel() throws SpatialAudioException

Retrieves the sound source model which defines the extent, directionality, and intensity of the sound source.

Returns:: An instance of the SoundSourceModel class describing the sound source. If the call fails, a SpatialAudioException is thrown.

setModel

  public abstract boolean setModel(SoundSourceModel model)

Sets the sound source model. The sound source model defines the extent, directionality, and intensity of the sound source.

Parameters:: model - An instance of the SoundSourceModel class describing the sound source.
Returns:: true if the call succeeded, or false if it failed.

getOrientation

  public abstract Vector3D getOrientation() throws SpatialAudioException

Retrieves the 3D vector that defines the sound source's orientation.

Returns:: An instance of the Vector3D class describing the orientation of the sound source. If the call fails, a SpatialAudioException is thrown.

setOrientation

  public abstract boolean setOrientation(Vector3D orientation)

Sets the 3D vector that defines the SoundSource's orientation.

Parameters:: orientation - A three dimensional vector describing the "forward" direction of the Sound Source.
Returns:: true if the call succeeded, or false if it failed.

setOrientation

  public abstract boolean setOrientation(float x,
                                         float y,
                                         float z)

Sets the orientation of the SoundSource.

Parameters:: x - The X component of the orientation.; y - The Y component of the orientation.; z - The Z component of the orientation.
Returns:: true if the call succeeded, or false if it failed.

getPosition

  public abstract Vector3D getPosition() throws SpatialAudioException

Retrieves the X,Y,Z coordinates of the sound source's position.

Returns:: An instance of the Vector3D class describing the position of the sound source. If the call fails, a SpatialAudioException is thrown.

setPosition

  public abstract boolean setPosition(Vector3D position)

Sets the X,Y,Z coordinates of the sound source's position.

Parameters:: position - Position of the sound source in 3D space.
Returns:: true if the call succeeded, or false if it failed.

setPosition

  public abstract boolean setPosition(float x,
                                      float y,
                                      float z)

Sets the X,Y,Z coordinates of the sound source's position.

Parameters:: x - The X component of the position.; y - The Y component of the position.; z - The Z component of the position.
Returns:: true if the call succeeded, or false if it failed.

move

  public abstract boolean move(Vector3D distance)

Moves the position of the sound source by the X,Y,Z offsets provided.

Parameters:: position - A 3D vector containing the requested X, Y, and Z position changes of the sound source.
Returns:: true if the call succeeded, or false if it failed.

move

  public abstract boolean move(float x,
                               float y,
                               float z)

Moves the position of the sound source by the X,Y,Z offsets provided.

Parameters:: position - The requested X, Y, and Z position changes of the sound source.
Returns:: true if the call succeeded, or false if it failed.

getCpuBudget

  public abstract int getCpuBudget() throws SpatialAudioException

Retrieves a RenderOptions value specifying the CPU budget for this SoundSource. If the default CPU budget value has not been overridden for this sound source, this method returns the default CPU budget for the environment.

Returns:: a RenderOptions value specifying the CPU budget for this SoundSource. If the call fails, a SpatialAudioException is thrown.

setCpuBudget

  public abstract boolean setCpuBudget(int cpuBudget)

Sets the CPU budget for this sound source, overriding the environment CPU budget for the sound source.

Parameters:

cpuBudget - A RenderOptions value specifying the CPU budget for localization quality on this specific sound source. The higher the budget, the better the localization quality. Valid choices are:

NO_SPATIALIZE for no localization
LOW_SPATIALIZE for low localization
MODERATE_SPATIALIZATION for the best available localization.

Returns:

true if the call succeeded, or false if it failed.

getMediaState

  public abstract MediaState getMediaState() throws SpatialAudioException

Queries the state of the sound source and returns an instance of the MediaState class.

Returns:: An instance of the MediaState class describing the state of sound source. If the call fails, a SpatialAudioException is thrown.

getMuteState

  public abstract boolean getMuteState()

Retrieves the mute state of the SoundSource.

Returns:: true if the sound source is muted, or false if it is not. This call also returns false if it failed.

setMuteState

  public abstract boolean setMuteState(boolean muteState)

Sets the mute state of the SoundSource.

Parameters:: muteState - This value should be true to mute the sound source or false to allow the sound source to play.
Comments: When an SoundSource is muted, it maintains the correct play position. To freeze the current play position for a cached sound source, use ControlMedia() instead.
Returns:: true if the call succeeded, or false if it failed.

getPitch

  public abstract float getPitch()

Retrieves the pitch adjustment of the SoundSource. Pitch adjustments are valid in the range 1/8 to 8, where 1 indicates normal pitch.

Returns:: The pitch adjustment of the sound source, or zero if the call failed.

setPitch

  public abstract boolean setPitch(float pitch)

Specifies the pitch adjustment of the sound source.

Parameters:: pitch - Specifies the pitch adjustment for the sound source. A factor of 1.0 plays the sound source at the normal pitch. The valid range is from 1/8 to 8.
Returns:: true if the call succeeded, or false if it failed.

setInfo

  public abstract void setInfo(Object info)

Sets the info value for the SoundSource.

Parameters:: The - info value set by the application.

getInfo

  public abstract Object getInfo()

Retrieves the info value set by the application.

Returns:: The info value set by the application. Returns null if the call fails, or if the info value has not been set.

release

  public abstract void release()

Requests that any resources associated with the SoundSource object be freed. The object may or may not continue to exist, but application must not attempt to use it after release() has been called.

All Packages  Class Hierarchy  This Package  Previous  Next  Index