libmedia/MediaHandler.h

   1 // MediaHandler.h: Base class for media handlers
   2 //
   3 //   Copyright (C) 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
   4 //
   5 // This program is free software; you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation; either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // This program is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with this program; if not, write to the Free Software
  17 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  18
  19
  20 #ifndef GNASH_MEDIAHANDLER_H
  21 #define GNASH_MEDIAHANDLER_H
  22
  23 #include "MediaParser.h" // for videoCodecType and audioCodecType enums
  24 #include "dsodefs.h" // DSOEXPORT
  25 #include "VideoConverter.h"
  26 #include "GnashFactory.h"
  27
  28 #include <vector>
  29 #include <memory>
  30 #include <map>
  31 #include <string>
  32
  33 // Forward declarations
  34 namespace gnash {
  35     class IOChannel;
  36     namespace media {
  37         class VideoDecoder;
  38         class AudioDecoder;
  39         class AudioInfo;
  40         class VideoInfo;
  41         class VideoInput;
  42         class AudioInput;
  43         class MediaHandler;
  44     }
  45 }
  46
  47 namespace gnash {
  48
  49 /// Gnash %media handling subsystem (libmedia)
  50 //
  51 /// The core Gnash lib will delegate any parsing decoding and encoding
  52 /// of %media files to the %media subsystem.
  53 ///
  54 /// The subsystem's entry point is a MediaHandler instance, which acts
  55 /// as a factory for parsers, decoders and encoders.
  56 ///
  57 /// @todo fix http://wiki.gnashdev.org/wiki/index.php/Libmedia, is obsoleted
  58 namespace media {
  59
  60 struct DSOEXPORT RegisterAllHandlers
  61 {
  62     RegisterAllHandlers();
  63 };
  64
  65 typedef GnashFactory<MediaHandler, RegisterAllHandlers> MediaFactory;
  66
  67 /// The MediaHandler class acts as a factory to provide parser and decoders
  68 class DSOEXPORT MediaHandler
  69 {
  70 public:
  71
  72     virtual ~MediaHandler() {}
  73
  74     /// Return a description of this media handler.
  75     virtual std::string description() const = 0;
  76
  77     /// Return an appropriate MediaParser for given input
  78     //
  79     /// @param stream
  80     ///    Input stream, ownership transferred
  81     ///
  82     /// @return 0 if no parser could be created for the input
  83     ///
  84     /// NOTE: the default implementation returns an FLVParser for FLV input
  85     ///       or 0 for others.
  86     ///
  87     virtual std::auto_ptr<MediaParser>
  88         createMediaParser(std::auto_ptr<IOChannel> stream);
  89
  90     /// Create a VideoDecoder for decoding what's specified in the VideoInfo
  91     //
  92     /// @param info VideoInfo class with all the info needed to decode
  93     ///             the image stream correctly.
  94     /// @return     Will always return a valid VideoDecoder or throw a
  95     ///             gnash::MediaException if a fatal error occurs.
  96     virtual std::auto_ptr<VideoDecoder>
  97         createVideoDecoder(const VideoInfo& info)=0;
  98
  99     /// Create an AudioDecoder for decoding what's specified in the AudioInfo
 100     //
 101     /// @param info AudioInfo class with all the info needed to decode
 102     ///             the sound correctly.
 103     /// @return     Will always return a valid AudioDecoder or throw a
 104     ///             gnash::MediaException if a fatal error occurs.
 105     virtual std::auto_ptr<AudioDecoder>
 106         createAudioDecoder(const AudioInfo& info)=0;
 107
 108     /// Create an VideoConverter for converting between color spaces.
 109     //
 110     /// @param srcFormat The source image color space
 111     /// @param dstFormat The destination image color space
 112     ///
 113     /// @return A valid VideoConverter or a NULL auto_ptr if a fatal error
 114     ///         occurs.
 115     virtual std::auto_ptr<VideoConverter>
 116         createVideoConverter(ImgBuf::Type4CC srcFormat,
 117                 ImgBuf::Type4CC dstFormat)=0;
 118
 119     /// Return a VideoInput
 120     //
 121     /// This is always owned by the MediaHandler, but will remain alive
 122     /// as long as it is referenced by a Camera object.
 123     //
 124     /// @param index    The index of the VideoInput to return.
 125     /// @return         A Video Input corresponding to the specified index
 126     ///                 or null if it is not available.
 127     virtual VideoInput* getVideoInput(size_t index) = 0;
 128
 129     virtual AudioInput* getAudioInput(size_t index) = 0;
 130
 131     /// Return a list of available cameras.
 132     //
 133     /// This is re-generated every time the function is called.
 134     virtual void cameraNames(std::vector<std::string>& names) const = 0;
 135
 136     /// Return the number of bytes padding needed for input buffers
 137     //
 138     /// Bitstream readers are optimized to read several bytes at a time,
 139     /// and this should be used to allocate a large enough input buffer.
 140     virtual size_t getInputPaddingSize() const { return 0; }
 141
 142 protected:
 143
 144     /// Base constructor
 145     //
 146     /// This is an abstract base class, so not instantiable anyway.
 147     MediaHandler() {}
 148
 149     /// Create an AudioDecoder for CODEC_TYPE_FLASH codecs
 150     //
 151     /// This method is attempted as a fallback in case
 152     /// a mediahandler-specific audio decoder couldn't be created
 153     /// for a CODEC_TYPE_FLASH codec.
 154     ///
 155     /// @throws a MediaException if it can't create a decoder
 156     ///
 157     /// @param info
 158     ///     Informations about the audio. It is *required*
 159     ///     for info.type to be media::CODEC_TYPE_FLASH (caller should check
 160     ///     that before calling this).
 161     ///
 162     std::auto_ptr<AudioDecoder> createFlashAudioDecoder(const AudioInfo& info);
 163
 164     /// Return true if input stream is an FLV
 165     //
 166     /// If this cannot read the necessary 3 bytes, it throws an IOException.
 167     bool isFLV(IOChannel& stream) throw (IOException);
 168
 169 };
 170
 171
 172 } // gnash.media namespace
 173 } // namespace gnash
 174
 175 #endif