Gnash 0.8.9
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:
gnash::sound::AOS4_sound_handler gnash::sound::Mkit_sound_handler gnash::sound::NullSoundHandler gnash::sound::SDL_sound_handler

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
 return true if audio is paused
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.
virtual void mix (boost::int16_t *outSamples, boost::int16_t *inSamples, unsigned int nSamples, float volume)=0
 Mix nSamples from inSamples to outSamples, with given volume.
void setAudioDump (const std::string &wavefile)
 Request to dump audio to the given filename.

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 ?

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:
dataThe sound data to be saved, allocated by new[]. Ownership is transferred. TODO: use SimpleBuffer ?
dataBytesSize of the data in bytes
sampleCountNumber of samples in the data
streamIdThe soundhandlers id of the sound we want to add data to
Returns:
an identifier for the new block for use in playSound
Exceptions:
SoundExceptionon error

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

References gnash::sound::EmbedSound::append(), data, 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:
ptrThe pointer to the callback function
udataUser 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(), and setAudioDump().

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:
dataThe 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).
sinfoA 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().

Referenced by gnash::SWF::define_sound_loader(), and gnash::SWF::sound_stream_head_loader().

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_handleThe 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:
toThe buffer to write mixed samples to. Buffer must be big enough to hold nSamples samples.
nSamplesThe 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 gnash::image::end(), gnash::sound::InputStream::fetchSamples(), getFinalVolume(), is_muted(), isPaused(), mix(), and gnash::sound::InputStream::samplesFetched().

Referenced by gnash::DumpGui::writeSamples().

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_handleThe 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:
soundHandleThe 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_handleThe 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]

return true if audio is paused

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

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

Mix nSamples from inSamples to outSamples, with given volume.

Parameters:
outSamplesThe output samples buffer, to mix to. Must be big enough to contain nSamples. Can be larger.
inSamplesThe 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 ?!
nSamplesThe amount of samples to mix in.
volumeThe 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.

Implemented in gnash::sound::NullSoundHandler.

Referenced by fetchSamples(), and gnash::sound::NullSoundHandler::mix().

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:
streamIdId of the sound buffer slot schedule playback of. It is assumed to refer to a straming sound
blockIdIdentifier 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:
inThe InputStream to plug, ownership transferred

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

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_handleThe sound_handlers id for the sound to be deleted
volumeA 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.

References volume.

void gnash::sound::sound_handler::setAudioDump ( const std::string &  wavefile)

Request to dump audio to the given filename.

Every call to this function starts recording to a new file, closing any existing other dump.

References attach_aux_streamer().

Referenced by gnash::Gui::start().

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

Set the volume to apply to mixed output.

Parameters:
vpercent value. 100 is full, 0 is none. Can be negative or over 100 too.

References gnash::key::v.

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:
idId of the sound buffer slot schedule playback of.
loopsloops == 0 means play the sound once (1 means play it twice, etc)
inPointOffset in output samples this instance should start playing from. These are post-resampling samples (44100 for one second of samples).
outPointOffset 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)
envSome eventsounds have some volume control mechanism called envelopes. They basically tells that from sample X the volume should be Y.
allowMultipleIf 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_handleThe 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_handleThe 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:
idThe key identifying the auxiliary streamer, as returned by attach_aux_streamer.

Reimplemented in gnash::sound::SDL_sound_handler.

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


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