libmedia/MediaHandler.h

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