libsound/EmbedSound.h

   1 // EmbedSound.h - embedded sound definition, for gnash
   2 //
   3 //   Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010,
   4 //   2011 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 "SimpleBuffer.h" // for composition
  24 #include "SoundInfo.h" // for composition
  25 #include "SoundEnvelope.h" // for SoundEnvelopes define
  26
  27 #include <vector>
  28 #include <map> // for composition (m_frame_size)
  29 #include <memory> // for auto_ptr (composition)
  30 #include <set> // for composition (_soundInstances)
  31 #include <cassert>
  32 #include <boost/thread/mutex.hpp>
  33
  34
  35 // Forward declarations
  36 namespace gnash {
  37     namespace sound {
  38         class EmbedSoundInst;
  39         class InputStream;
  40     }
  41     namespace media {
  42         class MediaHandler;
  43     }
  44 }
  45
  46 namespace gnash {
  47 namespace sound {
  48
  49 /// Definition of an embedded sound
  50 class EmbedSound
  51 {
  52     /// The undecoded data
  53     std::auto_ptr<SimpleBuffer> _buf;
  54
  55     void ensureBufferPadding();
  56
  57 public:
  58
  59     /// Construct a sound with given data, info and volume.
  60     //
  61     /// @param data The encoded sound data.
  62     ///     May be the NULL pointer for streaming sounds,
  63     ///     in which case data will be appended later using ::append()
  64     ///
  65     /// @param info encoding info
  66     ///
  67     /// @param nVolume initial volume (0..100). Optional, defaults to 100.
  68     ///
  69     EmbedSound(std::auto_ptr<SimpleBuffer> data,
  70             std::auto_ptr<media::SoundInfo> info, int nVolume,
  71             size_t paddingBytes);
  72
  73     ~EmbedSound();
  74
  75     /// Object holding information about the sound
  76     std::auto_ptr<media::SoundInfo> soundinfo;
  77
  78     typedef std::map<boost::uint32_t,boost::uint32_t> FrameSizeMap;
  79
  80     /// Maps frame sizes to start-of-frame offsets
  81     FrameSizeMap m_frames_size;
  82
  83     /// Append size bytes to this sound
  84     //
  85     /// @param data
  86     /// Data bytes, allocated with new[]. Ownership transferred.
  87     ///
  88     /// @param size
  89     /// Size of the 'data' buffer.
  90     ///
  91     void append(boost::uint8_t* data, unsigned int size);
  92
  93     /// Return size of the data buffer
  94     size_t size() const
  95     {
  96         return _buf->size();
  97     }
  98
  99     /// Is the data buffer empty ?
 100     bool empty() const
 101     {
 102         return _buf->empty();
 103     }
 104
 105     /// Return a pointer to the underlying buffer
 106     const boost::uint8_t* data() const {
 107         return _buf->data();
 108     }
 109
 110     /// Return a pointer to the underlying buffer
 111     boost::uint8_t* data() {
 112         return _buf->data();
 113     }
 114
 115     /// Return a pointer to an offset in the underlying buffer
 116     //
 117     /// @param pos The offset value.
 118     ///     An assertion will fail if pos > size()
 119     ///
 120     const boost::uint8_t* data(size_t pos) const {
 121         assert(pos < _buf->size());
 122         return _buf->data()+pos;
 123     }
 124
 125     /// Return a pointer to an offset in the underlying buffer
 126     //
 127     /// @param pos The offset value.
 128     ///     An assertion will fail if pos > size()
 129     ///
 130     boost::uint8_t* data(size_t pos) {
 131         assert(pos < _buf->size());
 132         return _buf->data()+pos;
 133     }
 134
 135     /// Are there known playing instances of this sound ?
 136     //
 137     /// Locks _soundInstancesMutex
 138     ///
 139     bool isPlaying() const;
 140
 141     /// Return number of playing instances of this sound
 142     //
 143     /// Locks _soundInstancesMutex
 144     ///
 145     size_t numPlayingInstances() const;
 146
 147     /// Append to the given vector all playing instances of this sound def
 148     void getPlayingInstances(std::vector<InputStream*>& to) const;
 149
 150     /// Return the first created instance of this sound
 151     //
 152     /// Locks _soundInstancesMutex
 153     ///
 154     EmbedSoundInst* firstPlayingInstance() const;
 155
 156     /// Create an instance of this sound
 157     //
 158     /// The returned instance ownership is transferred
 159     ///
 160     /// @param mh
 161     ///     The MediaHandler to use for on-demand decoding
 162     ///
 163     /// @param blockOffset
 164     ///     Byte offset in the immutable (encoded) data this
 165     ///     instance should start decoding.
 166     ///     This is currently used for streaming embedded sounds
 167     ///     to refer to a specific StreamSoundBlock.
 168     ///     @see gnash::swf::StreamSoundBlockTag
 169     ///
 170     /// @param inPoint
 171     ///     Offset in output samples this instance should start
 172     ///     playing from. These are post-resampling samples from
 173     ///     the start of the specified blockId.
 174     ///
 175     ///
 176     /// @param outPoint
 177     ///     Offset in output samples this instance should stop
 178     ///     playing at. These are post-resampling samples from
 179     ///     the start of the specified blockId.
 180     ///
 181     /// @param envelopes
 182     ///     SoundEnvelopes to apply to this sound. May be 0 for none.
 183     ///
 184     /// @param loopCount
 185     ///     Number of times this instance should loop over the defined sound.
 186     ///     @todo document if every loop starts at secsOffset !
 187     ///
 188     /// @todo split this in createEventSoundInstance
 189     ///                 and createStreamingSoundInstance
 190     ///
 191     ///
 192     /// Locks the _soundInstancesMutex when pushing to it
 193     ///
 194     std::auto_ptr<EmbedSoundInst> createInstance( media::MediaHandler& mh,
 195             unsigned long blockOffset,
 196             unsigned int inPoint, unsigned int outPoint,
 197             const SoundEnvelopes* envelopes, unsigned int loopCount);
 198
 199     /// Volume for AS-sounds, range: 0-100.
 200     /// It's the SWF range that is represented here.
 201     int volume;
 202
 203     /// Vector containing the active instances of this sounds being played
 204     //
 205     /// NOTE: This class does NOT own the active sounds
 206     ///
 207     typedef std::list<EmbedSoundInst*> Instances;
 208
 209     /// Playing instances of this sound definition
 210     //
 211     /// Multithread access to this member is protected
 212     /// by the _soundInstancesMutex mutex
 213     ///
 214     /// @todo make private
 215     ///
 216     Instances _soundInstances;
 217
 218     /// Mutex protecting access to _soundInstances
 219     //
 220     /// @todo make private
 221     ///
 222     mutable boost::mutex _soundInstancesMutex;
 223
 224     /// Drop all active sounds
 225     //
 226     /// Locks _soundInstancesMutex
 227     ///
 228     void clearInstances();
 229
 230     /// Drop an active sound (by iterator)
 231     //
 232     /// Does *NOT* lock the _soundInstancesMutex
 233     ///
 234     /// @return iterator after the one being erased
 235     ///
 236     Instances::iterator eraseActiveSound(Instances::iterator i);
 237
 238     /// Drop an active sound (by pointer)
 239     //
 240     /// @param inst The active sound instance to unregister
 241     ///
 242     /// This is intended to be called by EmbedSoundInst
 243     /// destructor, which may be called by a separate thread
 244     /// so MUST be thread-safe
 245     ///
 246     /// Does lock the _soundInstancesMutex
 247     ///
 248     /// @todo make private and mark EmbedSoundInst as friend ?
 249     ///
 250     void eraseActiveSound(EmbedSoundInst* inst);
 251
 252     const size_t _paddingBytes;
 253 };
 254
 255 } // gnash.sound namespace
 256 } // namespace gnash
 257
 258 #endif // SOUND_EMBEDSOUND_H