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