synfig-core/src/synfig/importer.h

   1 /* === S Y N F I G ========================================================= */
   2 /*!     \file importer.h
   3 **      \brief It is the base class for all the importers.
   4 **
   5 **      $Id$
   6 **
   7 **      \legal
   8 **      Copyright (c) 2002-2005 Robert B. Quattlebaum Jr., Adrian Bentley
   9 **
  10 **      This package is free software; you can redistribute it and/or
  11 **      modify it under the terms of the GNU General Public License as
  12 **      published by the Free Software Foundation; either version 2 of
  13 **      the License, or (at your option) any later version.
  14 **
  15 **      This package is distributed in the hope that it will be useful,
  16 **      but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 **      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18 **      General Public License for more details.
  19 **      \endlegal
  20 */
  21 /* ========================================================================= */
  22
  23 /* === S T A R T =========================================================== */
  24
  25 #ifndef __SYNFIG_IMPORTER_H
  26 #define __SYNFIG_IMPORTER_H
  27
  28 /* === H E A D E R S ======================================================= */
  29
  30 #include <cstdio>
  31 #include <map>
  32 #include <ETL/handle>
  33 #include "string.h"
  34 #include "time.h"
  35 #include "gamma.h"
  36 #include "renddesc.h"
  37
  38 /* === M A C R O S ========================================================= */
  39
  40 //! Defines various variables and the create method, common for all importers.
  41 //! To be used in the private part of the importer class definition.
  42 #define SYNFIG_IMPORTER_MODULE_EXT \
  43                 public: static const char name__[], version__[], ext__[],cvs_id__[]; \
  44                 static Importer *create(const char *filename);
  45
  46 //! Sets the name of the importer.
  47 #define SYNFIG_IMPORTER_SET_NAME(class,x) const char class::name__[]=x
  48
  49 //! Sets the primary file extension of the importer.
  50 #define SYNFIG_IMPORTER_SET_EXT(class,x) const char class::ext__[]=x
  51
  52 //! Sets the version of the importer.
  53 #define SYNFIG_IMPORTER_SET_VERSION(class,x) const char class::version__[]=x
  54
  55 //! Sets the CVS ID of the importer.
  56 #define SYNFIG_IMPORTER_SET_CVS_ID(class,x) const char class::cvs_id__[]=x
  57
  58 //! Defines de implementation of the create method for the importer
  59 //! \param filename The file name to be imported by the importer.
  60 #define SYNFIG_IMPORTER_INIT(class) synfig::Importer* class::create(const char *filename) { return new class(filename); }
  61
  62 /* === T Y P E D E F S ===================================================== */
  63
  64 /* === C L A S S E S & S T R U C T S ======================================= */
  65
  66 namespace synfig {
  67
  68 class Surface;
  69 class ProgressCallback;
  70
  71 /*!     \class Importer
  72 **      \brief Used for importing bitmaps of various formats, including animations.
  73 *
  74 *       It is the base class for all the importers. It defines the has a static Book
  75 *       pointer class that is a map for the importers factory creators and the strings
  76 *       of the extension that the importer can understand. It allows to create the a
  77 *       pointer to a particular importer just by using the extension of the name of file
  78 *       to import. Also it creates a virtual member get_frame that must be declared in
  79 *       the inherited classes.
  80 *       \see module.h
  81 **      \
  82 */
  83 class Importer : public etl::shared_object
  84 {
  85 public:
  86         //! Type that represents a pointer to a Importer's constructor.
  87         //! As a pointer to the constructor, it represents a "factory" of importers.
  88         typedef Importer* (*Factory)(const char *filename);
  89         typedef std::map<String,Factory> Book;
  90         static Book* book_;
  91
  92         static Book& book();
  93
  94         //! Initializes the Import module by creating a book of importers names
  95         //! and its creators and the list of open importers
  96         static bool subsys_init();
  97         //! Stops the Import module by deleting the book and the list of open
  98         //! importers
  99         static bool subsys_stop();
 100
 101         typedef etl::handle<Importer> Handle;
 102         typedef etl::loose_handle<Importer> LooseHandle;
 103         typedef etl::handle<const Importer> ConstHandle;
 104
 105 private:
 106         //! Gamma of the importer.
 107         //! \todo Do not hardcode the gamma to 2.2
 108         Gamma gamma_;
 109
 110 protected:
 111         Importer();
 112
 113 public:
 114
 115         Gamma& gamma() { return gamma_; }
 116         const Gamma& gamma()const { return gamma_; }
 117
 118         virtual ~Importer();
 119
 120         //! Gets a frame and puts it into \a surface
 121         /*!     \param  surface Reference to surface to put frame into
 122         **      \param  time    For animated importers, determines which frame to get.
 123         **              For static importers, this parameter is unused.
 124         **      \param  callback Pointer to callback class for progress, errors, etc.
 125         **      \return \c true on success, \c false on error
 126         **      \see ProgressCallback, Surface
 127         */
 128         virtual bool get_frame(Surface &surface, const RendDesc &renddesc, Time time, ProgressCallback *callback=NULL)=0;
 129         virtual bool get_frame(Surface &surface, const RendDesc &renddesc,Time time,
 130                                                    bool &trimmed __attribute__ ((unused)),
 131                                                    unsigned int &width __attribute__ ((unused)),
 132                                                    unsigned int &height __attribute__ ((unused)),
 133                                                    unsigned int &top __attribute__ ((unused)),
 134                                                    unsigned int &left __attribute__ ((unused)),
 135                                                    ProgressCallback *callback=NULL)
 136         {
 137                 return get_frame(surface,renddesc,time,callback);
 138         }
 139
 140         //! Returns \c true if the importer pays attention to the \a time parameter of get_frame()
 141         virtual bool is_animated() { return false; }
 142
 143         //! Attempts to open \a filename, and returns a handle to the associated Importer
 144         static Handle open(const String &filename);
 145 };
 146
 147 }; // END of namespace synfig
 148
 149 /* === E N D =============================================================== */
 150
 151 #endif