libsound/EmbedSound.h

   1 // EmbedSound.h - embedded sound definition, for gnash
   2 //
   3 //   Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012
   4 //   Free Software Foundation, Inc
   5 //
   6 // This program is free software; you can redistribute it and/or modify
   7 // it under the terms of the GNU General Public License as published by
   8 // the Free Software Foundation; either version 3 of the License, or
   9 // (at your option) any later version.
  10 //
  11 // This program is distributed in the hope that it will be useful,
  12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 // GNU General Public License for more details.
  15 //
  16 // You should have received a copy of the GNU General Public License
  17 // along with this program; if not, write to the Free Software
  18 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  19
  20 #ifndef SOUND_EMBEDSOUND_H
  21 #define SOUND_EMBEDSOUND_H
  22
  23 #include <vector>
  24 #include <memory> // for auto_ptr (composition)
  25 #include <set> // for composition (_soundInstances)
  26 #include <cassert>
  27 #include <boost/thread/mutex.hpp>
  28 #include <boost/scoped_ptr.hpp>
  29
  30 #include "SimpleBuffer.h" // for composition
  31 #include "SoundInfo.h" // for composition
  32 #include "SoundEnvelope.h" // for SoundEnvelopes define
  33
  34 // Forward declarations
  35 namespace gnash {
  36     namespace sound {
  37         class EmbedSoundInst;
  38         class InputStream;
  39     }
  40     namespace media {
  41         class MediaHandler;
  42     }
  43 }
  44
  45 namespace gnash {
  46 namespace sound {
  47
  48 /// Definition of an embedded sound
  49 class EmbedSound
  50 {
  51 public:
  52
  53     /// Vector containing the active instances of this sounds being played
  54     //
  55     /// NOTE: This class does NOT own the active sounds
  56     typedef std::list<EmbedSoundInst*> Instances;
  57
  58     /// Construct a sound with given data, info and volume.
  59     //
  60     /// @param data The encoded sound data.
  61     /// @param info encoding info
  62     /// @param volume initial volume (0..100). Optional, defaults to 100.
  63     EmbedSound(std::auto_ptr<SimpleBuffer> data, const media::SoundInfo& info,
  64             int volume);
  65
  66     ~EmbedSound();
  67
  68     /// Return size of the data buffer
  69     size_t size() const {
  70         return _buf->size();
  71     }
  72
  73     /// Is the data buffer empty ?
  74     bool empty() const {
  75         return _buf->empty();
  76     }
  77
  78     /// Return a pointer to the underlying buffer
  79     const boost::uint8_t* data() const {
  80         return _buf->data();
  81     }
  82
  83     /// Return a pointer to an offset in the underlying buffer
  84     //
  85     /// @param pos The offset value.
  86     ///     An assertion will fail if pos > size()
  87     ///
  88     const boost::uint8_t* data(size_t pos) const {
  89         assert(pos < _buf->size());
  90         return _buf->data()+pos;
  91     }
  92
  93     /// Are there known playing instances of this sound ?
  94     //
  95     /// Locks _soundInstancesMutex
  96     ///
  97     bool isPlaying() const;
  98
  99     /// Return number of playing instances of this sound
 100     //
 101     /// Locks _soundInstancesMutex
 102     ///
 103     size_t numPlayingInstances() const;
 104
 105     /// Append to the given vector all playing instances of this sound def
 106     void getPlayingInstances(std::vector<InputStream*>& to) const;
 107
 108     /// Return the first created instance of this sound
 109     //
 110     /// Locks _soundInstancesMutex
 111     ///
 112     EmbedSoundInst* firstPlayingInstance() const;
 113
 114     /// Create an instance of this sound
 115     //
 116     /// The returned instance ownership is transferred
 117     ///
 118     /// @param mh
 119     ///     The MediaHandler to use for on-demand decoding
 120     ///
 121     /// @param inPoint
 122     ///     Offset in output samples this instance should start
 123     ///     playing from. These are post-resampling samples from
 124     ///     the start of the specified blockId.
 125     ///
 126     ///
 127     /// @param outPoint
 128     ///     Offset in output samples this instance should stop
 129     ///     playing at. These are post-resampling samples from
 130     ///     the start of the specified blockId.
 131     ///
 132     /// @param envelopes
 133     ///     SoundEnvelopes to apply to this sound. May be 0 for none.
 134     ///
 135     /// @param loopCount
 136     ///     Number of times this instance should loop over the defined sound.
 137     ///     @todo document if every loop starts at secsOffset !
 138     /// Locks the _soundInstancesMutex when pushing to it
 139     ///
 140     std::auto_ptr<EmbedSoundInst> createInstance(media::MediaHandler& mh,
 141             unsigned int inPoint, unsigned int outPoint,
 142             const SoundEnvelopes* envelopes, unsigned int loopCount);
 143
 144     /// Drop all active sounds
 145     //
 146     /// Locks _soundInstancesMutex
 147     void clearInstances();
 148
 149     /// Drop an active sound (by iterator)
 150     //
 151     /// Does *NOT* lock the _soundInstancesMutex
 152     ///
 153     /// @return iterator after the one being erased
 154     Instances::iterator eraseActiveSound(Instances::iterator i);
 155
 156     /// Drop an active sound (by pointer)
 157     //
 158     /// @param inst The active sound instance to unregister
 159     ///
 160     /// This is intended to be called by EmbedSoundInst
 161     /// destructor, which may be called by a separate thread
 162     /// so MUST be thread-safe
 163     ///
 164     /// Does lock the _soundInstancesMutex
 165     ///
 166     /// @todo make private and mark EmbedSoundInst as friend ?
 167     ///
 168     void eraseActiveSound(EmbedSoundInst* inst);
 169
 170     /// Object holding information about the sound
 171     media::SoundInfo soundinfo;
 172
 173     /// Volume for AS-sounds, range: 0-100.
 174     /// It's the SWF range that is represented here.
 175     int volume;
 176
 177 private:
 178
 179     /// The undecoded data
 180     boost::scoped_ptr<SimpleBuffer> _buf;
 181
 182     /// Playing instances of this sound definition
 183     //
 184     /// Multithread access to this member is protected
 185     /// by the _soundInstancesMutex mutex
 186     Instances _soundInstances;
 187
 188     /// Mutex protecting access to _soundInstances
 189     //
 190     mutable boost::mutex _soundInstancesMutex;
 191 };
 192
 193 } // gnash.sound namespace
 194 } // namespace gnash
 195
 196 #endif // SOUND_EMBEDSOUND_H