com.threerings.openal
Class SoundManager

java.lang.Object
  com.threerings.openal.SoundManager

Direct Known Subclasses:

OpenALSoundPlayer.MediaALSoundManager

public class SoundManager
extends Object

An interface to the OpenAL library that provides a number of additional services:

• an object oriented interface to the OpenAL system
• a mechanism for loading a group of sounds and freeing their resources all at once
• a mechanism for loading sounds in a background thread and preloading sounds that are likely to be needed soon

Note: the sound manager is not thread safe (other than during its interactions with its internal background loading thread). It assumes that all sound loading and play requests will be made from a single thread.

Field Summary

protected float	_baseGain A base gain that is multiplied by the individual gain assigned to sounds.
protected LRUHashMap<String,ClipBuffer>	_clips Contains a mapping of all loaded clips.
protected int[]	_finalizedBuffers The list of buffers to be deleted.
protected int[]	_finalizedSources The list of sources to be deleted.
protected List<SoundGroup>	_groups The list of active groups.
protected Listener	_listener The listener object.
protected Thread	_loader The thread that loads up sound clips in the background.
protected HashMap<String,ClipBuffer>	_loading Contains a mapping of all currently-loading clips.
protected RunQueue	_rqueue Used to get back from the background thread to our "main" thread.
protected static LRUHashMap.ItemSizer<ClipBuffer>	_sizer Used to compute the in-memory size of sound samples.
protected static SoundManager	_soundmgr The one and only sound manager, here for an exclusive performance by special request.
protected ArrayList<Stream>	_streams The list of active streams.
protected Queue<ClipBuffer>	_toLoad Contains a queue of clip buffers waiting to be loaded.
protected static int	DEFAULT_CACHE_SIZE Default to a cache size of one megabyte.

Constructor Summary

protected

SoundManager(RunQueue rqueue) Creates a sound manager and initializes the OpenAL sound subsystem.

Method Summary

protected void	addGroup(SoundGroup group) Adds a group to the list maintained by the manager.
protected void	addStream(Stream stream) Adds a stream to the list maintained by the manager.
protected void	bufferFinalized(int id) Called when a buffer has been finalized.
SoundGroup	createGroup(ClipProvider provider, int sources) Creates an object that can be used to manage and play a group of sounds.
static SoundManager	createSoundManager(RunQueue rqueue) Creates, initializes and returns the singleton sound manager instance.
protected void	deleteFinalizedObjects() Deletes all finalized objects.
float	getBaseGain() Returns the base gain used for sound effects (not music).
protected ClipBuffer	getClip(ClipProvider provider, String path) Creates a clip buffer for the sound clip loaded via the specified provider with the specified path.
protected ClipBuffer	getClip(ClipProvider provider, String path, ClipBuffer.Observer observer) Creates a clip buffer for the sound clip loaded via the specified provider with the specified path.
Listener	getListener() Returns a reference to the listener object.
ArrayList<Stream>	getStreams() Returns a reference to the list of active streams.
boolean	isInitialized() Returns true if we were able to initialize the sound system.
void	loadClip(ClipProvider provider, String path) Loads a clip buffer for the sound clip loaded via the specified provider with the specified path.
void	loadClip(ClipProvider provider, String path, ClipBuffer.Observer observer) Loads a clip buffer for the sound clip loaded via the specified provider with the specified path.
protected void	queueClipFailure(ClipBuffer buffer) Queues the supplied clip buffer up using our RunQueue to notify its observers that it failed to load.
protected void	queueClipLoad(ClipBuffer buffer) Queues the supplied clip buffer up for resolution.
protected void	removeGroup(SoundGroup group) Removes a group from the list maintained by the manager.
protected void	removeStream(Stream stream) Removes a stream from the list maintained by the manager.
protected void	restoreClip(ClipBuffer buffer) Adds the supplied clip buffer back to the cache after it has been marked for disposal and subsequently re-requested.
void	setBaseGain(float gain) Configures the base gain (which must be a value between 0 and 1.0) which is multiplied to the individual gain assigned to sound effects (but not music).
void	setCacheSize(int bytes) Configures the size of our sound cache.
void	shutdown() Shuts down the sound manager.
protected void	sourceFinalized(int id) Called when a source has been finalized.
void	updateStreams(float time) Updates all of the streams controlled by the manager.

Methods inherited from class java.lang.Object

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

Field Detail

_loader

protected Thread _loader

The thread that loads up sound clips in the background.

_rqueue

protected RunQueue _rqueue

Used to get back from the background thread to our "main" thread.

_listener

protected Listener _listener

The listener object.

_baseGain

protected float _baseGain

A base gain that is multiplied by the individual gain assigned to sounds.

_loading

protected HashMap<String,ClipBuffer> _loading

Contains a mapping of all currently-loading clips.

_clips

protected LRUHashMap<String,ClipBuffer> _clips

Contains a mapping of all loaded clips.

_toLoad

protected Queue<ClipBuffer> _toLoad

Contains a queue of clip buffers waiting to be loaded.

_streams

protected ArrayList<Stream> _streams

The list of active streams.

_groups

protected List<SoundGroup> _groups

The list of active groups.

_finalizedSources

protected int[] _finalizedSources

The list of sources to be deleted.

_finalizedBuffers

protected int[] _finalizedBuffers

The list of buffers to be deleted.

_soundmgr

protected static SoundManager _soundmgr

The one and only sound manager, here for an exclusive performance by special request. Available for all your sound playing needs.

_sizer

protected static LRUHashMap.ItemSizer<ClipBuffer> _sizer

Used to compute the in-memory size of sound samples.

DEFAULT_CACHE_SIZE

protected static final int DEFAULT_CACHE_SIZE

Default to a cache size of one megabyte.

See Also:

Constant Field Values

Constructor Detail

SoundManager

protected SoundManager(RunQueue rqueue)

Creates a sound manager and initializes the OpenAL sound subsystem.

Method Detail

createSoundManager

public static SoundManager createSoundManager(RunQueue rqueue)

Creates, initializes and returns the singleton sound manager instance.

Parameters:

rqueue - a queue that the sound manager can use to post short runnables that must be executed on the same thread from which all other sound methods will be called.

shutdown

public void shutdown()

Shuts down the sound manager.

isInitialized

public boolean isInitialized()

Returns true if we were able to initialize the sound system.

setCacheSize

public void setCacheSize(int bytes)

Configures the size of our sound cache. If this value is larger than memory available to the underlying sound system, it will be reduced when OpenAL first tells us we're out of memory.

getListener

public Listener getListener()

Returns a reference to the listener object.

setBaseGain

public void setBaseGain(float gain)

Configures the base gain (which must be a value between 0 and 1.0) which is multiplied to the individual gain assigned to sound effects (but not music).

getBaseGain

public float getBaseGain()

Returns the base gain used for sound effects (not music).

createGroup

public SoundGroup createGroup(ClipProvider provider,
                              int sources)

Creates an object that can be used to manage and play a group of sounds. Note: the sound group must be disposed when it is no longer needed via a call to SoundGroup.dispose().

Parameters:

provider - indicates from where the sound group will load its sounds.

sources - indicates the maximum number of simultaneous sounds that can play in this group.

getStreams

public ArrayList<Stream> getStreams()

Returns a reference to the list of active streams.

updateStreams

public void updateStreams(float time)

Updates all of the streams controlled by the manager. This should be called once per frame by the application.

Parameters:

time - the number of seconds elapsed since the last update

loadClip

public void loadClip(ClipProvider provider,
                     String path)

Loads a clip buffer for the sound clip loaded via the specified provider with the specified path. The loaded clip is placed in the cache.

loadClip

public void loadClip(ClipProvider provider,
                     String path,
                     ClipBuffer.Observer observer)

Loads a clip buffer for the sound clip loaded via the specified provider with the specified path. The loaded clip is placed in the cache.

getClip

protected ClipBuffer getClip(ClipProvider provider,
                             String path)

Creates a clip buffer for the sound clip loaded via the specified provider with the specified path. The clip buffer may come from the cache, and it will immediately be queued for loading if it is not already loaded.

getClip

protected ClipBuffer getClip(ClipProvider provider,
                             String path,
                             ClipBuffer.Observer observer)

Creates a clip buffer for the sound clip loaded via the specified provider with the specified path. The clip buffer may come from the cache, and it will immediately be queued for loading if it is not already loaded.

queueClipLoad

protected void queueClipLoad(ClipBuffer buffer)

Queues the supplied clip buffer up for resolution. The Clip will be loaded into memory and then bound into OpenAL on the background thread.

queueClipFailure

protected void queueClipFailure(ClipBuffer buffer)

Queues the supplied clip buffer up using our RunQueue to notify its observers that it failed to load.

restoreClip

protected void restoreClip(ClipBuffer buffer)

Adds the supplied clip buffer back to the cache after it has been marked for disposal and subsequently re-requested.

addStream

protected void addStream(Stream stream)

Adds a stream to the list maintained by the manager. Called by streams when they are created.

removeStream

protected void removeStream(Stream stream)

Removes a stream from the list maintained by the manager. Called by streams when they are disposed.

addGroup

protected void addGroup(SoundGroup group)

Adds a group to the list maintained by the manager. Called by groups when they are created.

removeGroup

protected void removeGroup(SoundGroup group)

Removes a group from the list maintained by the manager. Called by groups when they are disposed.

sourceFinalized

protected void sourceFinalized(int id)

Called when a source has been finalized.

bufferFinalized

protected void bufferFinalized(int id)

Called when a buffer has been finalized.

deleteFinalizedObjects

protected void deleteFinalizedObjects()

Deletes all finalized objects.