Public Types | Public Member Functions | Protected Member Functions

gnash::sound::sound_handler Class Reference

Sound mixer. More...

#include <sound_handler.h>

Inheritance diagram for gnash::sound::sound_handler:
Inheritance graph
[legend]
Collaboration diagram for gnash::sound::sound_handler:
Collaboration graph
[legend]

List of all members.

Public Types

typedef unsigned long StreamBlockId
 Identifier of a streaming sound block.

Public Member Functions

virtual int create_sound (std::auto_ptr< SimpleBuffer > data, std::auto_ptr< media::SoundInfo > sinfo)
 Create a sound buffer slot, for on-demand playback.
virtual StreamBlockId addSoundBlock (unsigned char *data, unsigned int dataBytes, unsigned int sampleCount, int streamId)
 Append data to an existing sound buffer slot.
virtual media::SoundInfoget_sound_info (int soundHandle)
 Returns a pointer to the SoundInfo object for the sound with the given id.
void startSound (int id, int loops, const SoundEnvelopes *env, bool allowMultiple, unsigned int inPoint=0, unsigned int outPoint=std::numeric_limits< unsigned int >::max())
 Start playback of an event sound.
void playStream (int id, StreamBlockId blockId)
 Start playback of a streaming sound, if not playing already.
virtual void stop_all_sounds ()
 Remove all scheduled request for playback of sound buffer slots.
virtual int get_volume (int sound_handle)
 Gets the volume for a given sound buffer slot.
int getFinalVolume ()
 Get the volume to apply to mixed output.
virtual void set_volume (int sound_handle, int volume)
 Sets the volume for a given sound buffer slot.
void setFinalVolume (int v)
 Set the volume to apply to mixed output.
virtual void stop_sound (int sound_handle)
 Remove scheduled requests to play the specified sound buffer slot.
virtual void delete_sound (int sound_handle)
 Discard a sound buffer slot.
virtual void delete_all_sounds ()
virtual void reset ()
 Discard all sound inputs (slots and aux streamers) and clear scheduling.
virtual void mute ()
 Call this to mute audio.
virtual void unmute ()
 Call this to unmute audio.
virtual bool is_muted () const
 Returns whether or not sound is muted.
virtual void pause ()
 gnash calls this to pause audio
virtual void unpause ()
 gnash calls this to unpause audio
bool isPaused () const
 gnash calls this to unpause audio
virtual InputStreamattach_aux_streamer (aux_streamer_ptr ptr, void *udata)
 Plug an external InputStream into the mixer.
virtual void unplugInputStream (InputStream *id)
 Unplug an external InputStream from the mixer.
virtual ~sound_handler ()
virtual unsigned int get_duration (int sound_handle)
 Gets the duration in milliseconds of an event sound connected to an AS Sound obejct.
virtual unsigned int tell (int sound_handle)
 Gets the playhead position in milliseconds of an event sound connected to an AS Sound obejct.
size_t numSoundsStarted () const
 Special test-fuction. Reports how many times a sound has been started.
size_t numSoundsStopped () const
 Special test-fuction. Reports how many times a sound has been stopped.
virtual void fetchSamples (boost::int16_t *to, unsigned int nSamples)
 Fetch mixed samples.

Protected Member Functions

 sound_handler (media::MediaHandler *m)
virtual void plugInputStream (std::auto_ptr< InputStream > in)
 Plug an InputStream to the mixer.
virtual void unplugAllInputStreams ()
 Unplug all input streams.
bool hasInputStreams () const
 Does the mixer have input streams ?
virtual void mix (boost::int16_t *outSamples, boost::int16_t *inSamples, unsigned int nSamples, float volume)
 Mix nSamples from inSamples to outSamples, with given volume.

Detailed Description

Sound mixer.

Stores the audio found by the parser and plays on demand. Also allows plugging auxiliary streamers for ActionScript driven sound (Sound, NetStream).

The main interface this class exposes to hosting application is fetching of sound samples, in couples of signed 16bit integers (left channel, right channel) in PCM. See fetchSamples.

Implementations of this class willing to allow hosting application to use a thread for fetching audio should make sure to take care about mutex protecting the relevant datastores. The default implementation uses NO locking.

Todo:
rename to gnash::sound::Mixer ?

Member Typedef Documentation

Identifier of a streaming sound block.

Use coupled with a soundId for fully qualified identifier


Constructor & Destructor Documentation

virtual gnash::sound::sound_handler::~sound_handler (  )  [inline, virtual]
gnash::sound::sound_handler::sound_handler ( media::MediaHandler m  )  [inline, protected]

Member Function Documentation

sound_handler::StreamBlockId gnash::sound::sound_handler::addSoundBlock ( unsigned char *  data,
unsigned int  dataBytes,
unsigned int  sampleCount,
int  streamId 
) [virtual]

Append data to an existing sound buffer slot.

Gnash's parser calls this to fill up soundstreams data. TODO: the current code uses memory reallocation to grow the sound, which is suboptimal; instead, we should maintain sound sources as a list of buffers, to avoid reallocations.

Parameters:
data The sound data to be saved, allocated by new[]. Ownership is transferred. TODO: use SimpleBuffer ?
dataBytes Size of the data in bytes
sampleCount Number of samples in the data
streamId The soundhandlers id of the sound we want to add data to
Returns:
an identifier for the new block for use in playSound
Exceptions:
SoundException on error

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::Mkit_sound_handler, and gnash::sound::SDL_sound_handler.

References gnash::sound::EmbedSound::append(), and gnash::sound::EmbedSound::size().

Referenced by gnash::SWF::StreamSoundBlockTag::loader().

InputStream * gnash::sound::sound_handler::attach_aux_streamer ( aux_streamer_ptr  ptr,
void *  udata 
) [virtual]

Plug an external InputStream into the mixer.

This is called by AS classes NetStream or Sound to attach callback, so that audio from the classes will be played through the soundhandler.

This is actually only used by the SDL sound_handler. It uses these "auxiliary" streamers to fetch decoded audio data to mix and send to the output channel.

The "aux streamer" will be called with the 'udata' pointer as first argument, then will be passed a pointer to buffer of samples as second argument and the number of samples to fetch as third.

The callbacks should fill the given buffer if possible, and return the number of samples actually fetched and an eof flag (last argument). The callback will be detached if it sets the 'eof' output parameter to true.

Parameters:
ptr The pointer to the callback function
udata User data pointer, passed as first argument to the registered callback.
Returns:
an InputStream pointer, for passing to unplugInputStream. Callers do not own the InputStream, and should NOT realy on it to be point to allocated memory! It is meant to be used as an identifier for the newly created mixer channel.
Todo:
change to plugInputStream(InputStream* str), implement in base class
See also:
unplugInputStream

References plugInputStream().

Referenced by gnash::BufferedAudioStreamer::attachAuxStreamer().

int gnash::sound::sound_handler::create_sound ( std::auto_ptr< SimpleBuffer data,
std::auto_ptr< media::SoundInfo sinfo 
) [virtual]

Create a sound buffer slot, for on-demand playback.

Parameters:
data The data to be stored. For soundstream this is NULL. The data is in encoded format, with format specified with the sinfo parameter, this is to allow on-demand decoding (if the sound is never played, it's never decoded).
sinfo A SoundInfo object contained in an auto_ptr, which contains info about samplerate, samplecount, stereo and more. The SoundObject must be not-NULL!
Returns:
the id given by the soundhandler for later identification.

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::Mkit_sound_handler, and gnash::sound::SDL_sound_handler.

References gnash::media::MediaHandler::getInputPaddingSize().

void gnash::sound::sound_handler::delete_all_sounds (  )  [virtual]
void gnash::sound::sound_handler::delete_sound ( int  sound_handle  )  [virtual]

Discard a sound buffer slot.

Parameters:
sound_handle The sound_handlers id for the sound to be deleted

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::Mkit_sound_handler, and gnash::sound::SDL_sound_handler.

Referenced by gnash::sound_sample::~sound_sample().

void gnash::sound::sound_handler::fetchSamples ( boost::int16_t *  to,
unsigned int  nSamples 
) [virtual]

Fetch mixed samples.

We run through all the plugged InputStreams fetching decoded audio blocks and mixing them into the given output stream.

Parameters:
to The buffer to write mixed samples to. Buffer must be big enough to hold nSamples samples.
nSamples The amount of samples to fetch. NOTE: this number currently refers to "mono" samples due to some bad design decision. It is so expected that the user fetches 44100 * 2 samples which has to be interpreted as series of left,right channel couples. TODO: use actual number of samples so that it's expected to fetch 44100 per second and let expose a function to give interpretation of what comes back (how many bytes per channel, which format).

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::Mkit_sound_handler, and gnash::sound::SDL_sound_handler.

References s2x::end, gnash::sound::InputStream::fetchSamples(), getFinalVolume(), is_muted(), isPaused(), mix(), and gnash::sound::InputStream::samplesFetched().

unsigned int gnash::sound::sound_handler::get_duration ( int  sound_handle  )  [virtual]

Gets the duration in milliseconds of an event sound connected to an AS Sound obejct.

Parameters:
sound_handle The id of the event sound
Returns:
the duration of the sound in milliseconds

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::Mkit_sound_handler, and gnash::sound::SDL_sound_handler.

References gnash::sound::EmbedSound::soundinfo.

media::SoundInfo * gnash::sound::sound_handler::get_sound_info ( int  soundHandle  )  [virtual]

Returns a pointer to the SoundInfo object for the sound with the given id.

The SoundInfo object is still owned by the soundhandler.

Parameters:
soundHandle The soundhandlers id of the sound we want some info about.
Returns:
a pointer to the SoundInfo object for the sound with the given id.

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::Mkit_sound_handler, and gnash::sound::SDL_sound_handler.

Referenced by gnash::SWF::StreamSoundBlockTag::loader().

int gnash::sound::sound_handler::get_volume ( int  sound_handle  )  [virtual]

Gets the volume for a given sound buffer slot.

Only used by the AS Sound class

Parameters:
sound_handle The sound_handlers id for the sound to be deleted
Returns:
the sound volume level as an integer from 0 to 100, where 0 is off and 100 is full volume. The default setting is 100.

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::Mkit_sound_handler, and gnash::sound::SDL_sound_handler.

int gnash::sound::sound_handler::getFinalVolume (  )  [inline]

Get the volume to apply to mixed output.

Returns:
percent value. 100 is full, 0 is none. Can be negative or over 100 too.

Referenced by fetchSamples().

bool gnash::sound::sound_handler::hasInputStreams (  )  const [protected]
bool gnash::sound::sound_handler::is_muted (  )  const [virtual]

Returns whether or not sound is muted.

Returns:
true if muted, false if not

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::Mkit_sound_handler, and gnash::sound::SDL_sound_handler.

Referenced by fetchSamples(), and gnash::Gui::toggleSound().

bool gnash::sound::sound_handler::isPaused (  )  const [inline]

gnash calls this to unpause audio

Referenced by gnash::sound::AOS4_sound_handler::audioTask(), and fetchSamples().

void gnash::sound::sound_handler::mix ( boost::int16_t *  outSamples,
boost::int16_t *  inSamples,
unsigned int  nSamples,
float  volume 
) [protected, virtual]

Mix nSamples from inSamples to outSamples, with given volume.

Parameters:
outSamples The output samples buffer, to mix to. Must be big enough to contain nSamples. Can be larger.
inSamples The input samples buffer, to mix in. It is non-const as this method *is* allowed to mess with content, for example to apply volume. TODO: why not applying volume upstream ?!
nSamples The amount of samples to mix in.
volume The volume to apply to input samples, as a fraction (0..1)

TODO: this interface says nothing about how many channels we're going to mix. It should, to be a sane interface. Maybe, a Mixer instance should be created, initialized with number of channels, at each fetching.

Todo:
implement a better mixer !

Referenced by fetchSamples().

void gnash::sound::sound_handler::mute (  )  [virtual]
size_t gnash::sound::sound_handler::numSoundsStarted (  )  const [inline]

Special test-fuction. Reports how many times a sound has been started.

Deprecated:
Use a TestingSoundHanlder !
size_t gnash::sound::sound_handler::numSoundsStopped (  )  const [inline]

Special test-fuction. Reports how many times a sound has been stopped.

Deprecated:
Use a TestingSoundHanlder !
virtual void gnash::sound::sound_handler::pause (  )  [inline, virtual]
void gnash::sound::sound_handler::playStream ( int  id,
StreamBlockId  blockId 
)

Start playback of a streaming sound, if not playing already.

Parameters:
streamId Id of the sound buffer slot schedule playback of. It is assumed to refer to a straming sound
blockId Identifier of the block to start decoding from.

Referenced by gnash::SWF::StreamSoundBlockTag::executeActions().

void gnash::sound::sound_handler::plugInputStream ( std::auto_ptr< InputStream in  )  [protected, virtual]

Plug an InputStream to the mixer.

Parameters:
in The InputStream to plug, ownership transferred

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::Mkit_sound_handler, and gnash::sound::SDL_sound_handler.

References second.

Referenced by attach_aux_streamer().

void gnash::sound::sound_handler::reset (  )  [virtual]

Discard all sound inputs (slots and aux streamers) and clear scheduling.

Gnash calls this on movie restart.

The function should stop all sounds and get ready for a "parse from scratch" operation.

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::Mkit_sound_handler, and gnash::sound::SDL_sound_handler.

References stop_all_sounds().

void gnash::sound::sound_handler::set_volume ( int  sound_handle,
int  volume 
) [virtual]

Sets the volume for a given sound buffer slot.

Only used by the AS Sound class

Parameters:
sound_handle The sound_handlers id for the sound to be deleted
volume A number from 0 to 100 representing a volume level. 100 is full volume and 0 is no volume. The default setting is 100.

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::Mkit_sound_handler, and gnash::sound::SDL_sound_handler.

void gnash::sound::sound_handler::setFinalVolume ( int  v  )  [inline]

Set the volume to apply to mixed output.

Parameters:
v percent value. 100 is full, 0 is none. Can be negative or over 100 too.
void gnash::sound::sound_handler::startSound ( int  id,
int  loops,
const SoundEnvelopes env,
bool  allowMultiple,
unsigned int  inPoint = 0,
unsigned int  outPoint = std::numeric_limits<unsigned int>::max() 
)

Start playback of an event sound.

All scheduled sounds will be played on next output flush.

Parameters:
id Id of the sound buffer slot schedule playback of.
loops loops == 0 means play the sound once (1 means play it twice, etc)
inPoint Offset in output samples this instance should start playing from. These are post-resampling samples (44100 for one second of samples).
outPoint Offset in output samples this instance should stop playing at. These are post-resampling samples (44100 for one second of samples). Use std::numeric_limits<unsigned int>::max() for no limit (default if missing)
env Some eventsounds have some volume control mechanism called envelopes. They basically tells that from sample X the volume should be Y.
allowMultiple If false, the sound will not be scheduled if there's another instance of it already playing.

References gnash::media::SoundInfo::getDelaySeek(), LOG_ONCE, and gnash::sound::EmbedSound::soundinfo.

Referenced by gnash::SWF::StartSoundTag::executeActions(), and gnash::Button::mouseEvent().

void gnash::sound::sound_handler::stop_all_sounds (  )  [virtual]

Remove all scheduled request for playback of sound buffer slots.

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::Mkit_sound_handler, and gnash::sound::SDL_sound_handler.

References gnash::key::e, and gnash::key::i.

Referenced by reset().

void gnash::sound::sound_handler::stop_sound ( int  sound_handle  )  [virtual]

Remove scheduled requests to play the specified sound buffer slot.

Stop the specified sound if it's playing. (Normally a full-featured sound API would take a handle specifying the *instance* of a playing sample, but SWF is not expressive that way.)

Parameters:
sound_handle The sound_handlers id for the sound to be deleted

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::Mkit_sound_handler, and gnash::sound::SDL_sound_handler.

Referenced by gnash::SWF::StartSoundTag::executeActions(), and gnash::Button::mouseEvent().

unsigned int gnash::sound::sound_handler::tell ( int  sound_handle  )  [virtual]

Gets the playhead position in milliseconds of an event sound connected to an AS Sound obejct.

Parameters:
sound_handle The id of the event sound
Returns:
the duration of the sound in milliseconds

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::Mkit_sound_handler, and gnash::sound::SDL_sound_handler.

References gnash::sound::EmbedSound::firstPlayingInstance(), gnash::sound::EmbedSound::isPlaying(), and gnash::sound::InputStream::samplesFetched().

void gnash::sound::sound_handler::unmute (  )  [virtual]
virtual void gnash::sound::sound_handler::unpause (  )  [inline, virtual]
void gnash::sound::sound_handler::unplugAllInputStreams (  )  [protected, virtual]
void gnash::sound::sound_handler::unplugInputStream ( InputStream id  )  [virtual]

Unplug an external InputStream from the mixer.

This is called by AS classes NetStream or Sound to dettach callback, so that audio from the classes no longer will be played through the soundhandler.

Parameters:
id The key identifying the auxiliary streamer, as returned by attach_aux_streamer.

Referenced by gnash::BufferedAudioStreamer::attachAuxStreamer(), and gnash::BufferedAudioStreamer::detachAuxStreamer().


The documentation for this class was generated from the following files: