synfig-core/trunk/src/synfig/layer.h

   1 /* === S Y N F I G ========================================================= */
   2 /*!     \file layer.h
   3 **      \brief Layer Class Header
   4 **
   5 **      $Id$
   6 **
   7 **      \legal
   8 **      Copyright (c) 2002-2005 Robert B. Quattlebaum Jr., Adrian Bentley
   9 **      Copyright (c) 2008 Chris Moore
  10 **
  11 **      This package is free software; you can redistribute it and/or
  12 **      modify it under the terms of the GNU General Public License as
  13 **      published by the Free Software Foundation; either version 2 of
  14 **      the License, or (at your option) any later version.
  15 **
  16 **      This package is distributed in the hope that it will be useful,
  17 **      but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 **      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  19 **      General Public License for more details.
  20 **      \endlegal
  21 */
  22 /* ========================================================================= */
  23
  24 /* === S T A R T =========================================================== */
  25
  26 #ifndef __SYNFIG_LAYER_H
  27 #define __SYNFIG_LAYER_H
  28
  29 /* === H E A D E R S ======================================================= */
  30
  31 #include "string_decl.h"
  32 #include <map>
  33 #include <ETL/handle>
  34 #include "real.h"
  35 #include "string.h"
  36 #include <sigc++/signal.h>
  37 #include <sigc++/connection.h>
  38 #include "node.h"
  39 #include "time.h"
  40 #include "guid.h"
  41
  42 /* === M A C R O S ========================================================= */
  43
  44 //! \writeme
  45 #define SYNFIG_LAYER_MODULE_EXT public: static const char name__[], version__[], cvs_id__[], local_name__[], category__[]; static Layer *create();
  46
  47 //! Sets the name of the layer
  48 #define SYNFIG_LAYER_SET_NAME(class,x) const char class::name__[]=x
  49
  50 //! Sets the local name of the layer
  51 #define SYNFIG_LAYER_SET_LOCAL_NAME(class,x) const char class::local_name__[]=x;
  52
  53 //! Sets the category of the layer
  54 #define SYNFIG_LAYER_SET_CATEGORY(class,x) const char class::category__[]=x
  55
  56 //! Sets the version string for the layer
  57 #define SYNFIG_LAYER_SET_VERSION(class,x) const char class::version__[]=x
  58
  59 //! Sets the CVS ID string for the layer
  60 #define SYNFIG_LAYER_SET_CVS_ID(class,x) const char class::cvs_id__[]=x
  61
  62 //! \writeme
  63 #define SYNFIG_LAYER_INIT(class) synfig::Layer* class::create() { return new class(); }
  64
  65 //! \writeme
  66 #define IMPORT_PLUS(x,y) if(param==#x && value.same_type_as(x)) { value.put(&x);{y;}return true;}
  67
  68 //! \writeme
  69 #define IMPORT_AS(x,y) if(param==y && value.same_type_as(x)) { value.put(&x); return true;}
  70
  71 //! \writeme
  72 #define IMPORT(x) IMPORT_AS(x,#x)
  73
  74 //! \writeme
  75 #define EXPORT_AS(x,y) if(param==y) { return ValueBase(x); }
  76
  77 //! \writeme
  78 #define EXPORT(x)                                       EXPORT_AS(x,#x)
  79
  80 //! \writeme
  81 #define EXPORT_NAME()   if(param=="Name" || param=="name" || param=="name__") { return name__; } if(param=="local_name__") { return dgettext("synfig",local_name__); }
  82
  83 //! \writeme
  84 #define EXPORT_VERSION()        if(param=="Version" || param=="version" || param=="version__") { return version__; }
  85
  86 //! This is used as the category for layer book entries which represent aliases of layers.
  87 //! It prevents these layers showing up in the menu.
  88 #define CATEGORY_DO_NOT_USE "Do Not Use"
  89
  90 /* === T Y P E D E F S ===================================================== */
  91
  92 /* === C L A S S E S & S T R U C T S ======================================= */
  93
  94 namespace synfig {
  95
  96 class Canvas;
  97 class Vector;
  98 typedef Vector Point;
  99 class Canvas;
 100 class ParamDesc;
 101 class ParamVocab;
 102 class ValueNode;
 103 class ValueBase;
 104 class Time;
 105 class Surface;
 106 class RendDesc;
 107 class ProgressCallback;
 108 class Context;
 109 class Color;
 110 class Transform;
 111 class Rect;
 112 class GUID;
 113
 114
 115 /*!     \class Layer
 116 **      \todo writeme
 117 **      \see Canvas
 118 */
 119 class Layer : public Node
 120 {
 121         friend class ValueNode;
 122         friend class Context;
 123
 124         /*
 125  --     ** -- T Y P E S -----------------------------------------------------------
 126         */
 127
 128 public:
 129
 130         //! Type that represents a pointer to a layer's constructor
 131         typedef Layer* (*Factory)();
 132
 133         struct BookEntry
 134         {
 135                 Factory factory;
 136                 String name;
 137                 String local_name;
 138                 String category;
 139                 String cvs_id;
 140                 String version;
 141                 BookEntry() { }
 142                 BookEntry(Factory factory, const String& name,const String& local_name,const String& category,const String& cvs_id,const String& version):
 143                         factory(factory),name(name),local_name(local_name),category(category),cvs_id(cvs_id),version(version) { }
 144         };
 145
 146         typedef std::map<String,BookEntry> Book;
 147
 148         static void register_in_book(const BookEntry &);
 149
 150         static Book& book();
 151
 152         static bool subsys_init();
 153
 154         static bool subsys_stop();
 155
 156         typedef std::map<String,ValueBase> ParamList;
 157
 158         typedef etl::handle<Layer> Handle;
 159
 160         typedef etl::loose_handle<Layer> LooseHandle;
 161
 162         typedef etl::handle<const Layer> ConstHandle;
 163
 164         typedef std::map<String,etl::rhandle<ValueNode> > DynamicParamList;
 165
 166         //! A list type which describes all the parameters that a layer has.
 167         /*! \see get_param_vocab() */
 168         typedef ParamVocab Vocab;
 169
 170         /*
 171  --     ** -- D A T A -------------------------------------------------------------
 172         */
 173
 174 private:
 175
 176         /*! \c true if the layer is visible, \c false if it is to be skipped
 177         **      \see set_active(), enable(), disable, active()
 178         */
 179         bool active_;
 180
 181         //! Handle to the canvas to which this layer belongs
 182         etl::loose_handle<Canvas> canvas_;
 183
 184         DynamicParamList dynamic_param_list_;
 185
 186         //! A description of what this layer does
 187         String description_;
 188
 189         //! \writeme
 190         float z_depth_;
 191
 192         //! \writeme
 193         mutable Time dirty_time_;
 194
 195         //! Contains the name of the group that this layer belongs to
 196         String group_;
 197
 198         //! \writeme
 199         sigc::connection parent_death_connect_;
 200
 201         /*
 202  -- ** -- S I G N A L S -------------------------------------------------------
 203         */
 204
 205 private:
 206
 207         //!     Status Changed
 208         sigc::signal<void> signal_status_changed_;
 209
 210         //!     Parameter changed
 211         sigc::signal<void,String> signal_param_changed_;
 212
 213         //!     Description Changed
 214         sigc::signal<void> signal_description_changed_;
 215
 216         //!     Moved
 217         sigc::signal<void, int, etl::handle<Canvas> > signal_moved_;
 218
 219         sigc::signal<void, String> signal_added_to_group_;
 220
 221         sigc::signal<void, String> signal_removed_from_group_;
 222
 223         /*
 224  -- ** -- S I G N A L   I N T E R F A C E -------------------------------------
 225         */
 226
 227 public:
 228
 229         //!     Status Changed
 230         sigc::signal<void>& signal_status_changed() { return signal_status_changed_; }
 231
 232         //!     Parameter changed
 233         sigc::signal<void,String>& signal_param_changed() { return signal_param_changed_; }
 234
 235         //!     Description Changed
 236         sigc::signal<void>& signal_description_changed() { return signal_description_changed_;}
 237
 238         //!     Moved
 239         sigc::signal<void, int, etl::handle<Canvas> >& signal_moved() { return signal_moved_; }
 240
 241         sigc::signal<void, String>& signal_added_to_group() { return signal_added_to_group_; }
 242
 243         sigc::signal<void, String>& signal_removed_from_group() { return signal_removed_from_group_; }
 244
 245         /*
 246  --     ** -- C O N S T R U C T O R S ---------------------------------------------
 247         */
 248
 249 protected:
 250
 251         Layer();
 252
 253 public:
 254         virtual ~Layer();
 255
 256         /*
 257  --     ** -- M E M B E R   F U N C T I O N S -------------------------------------
 258         */
 259
 260 public:
 261
 262         virtual void on_canvas_set();
 263
 264         //! Adds this layer to the given layer group
 265         void add_to_group(const String&);
 266
 267         //! Removes this layer from the given layer group
 268         void remove_from_group(const String&);
 269
 270         //! Removes this layer from all layer groups
 271         void remove_from_all_groups();
 272
 273         //! Gets the name of the group that this layer belongs to
 274         String get_group()const;
 275
 276         //! writeme
 277         //DynamicParamList &dynamic_param_list() { return dynamic_param_list_; }
 278
 279         //! \todo writeme
 280         const DynamicParamList &dynamic_param_list()const { return dynamic_param_list_; }
 281
 282         bool connect_dynamic_param(const String& param, etl::loose_handle<ValueNode>);
 283         bool disconnect_dynamic_param(const String& param);
 284
 285         //! Enables the layer for rendering (Making it \em active)
 286         void enable() { set_active(true); }
 287
 288         //! Disables the layer for rendering. (Making it \em inactive)
 289         /*! When a layer is disabled, it will be skipped when the
 290         **      canvas is rendered. */
 291         void disable() { set_active(false); }
 292
 293         //! Sets the 'active' flag for the Layer to the state described by \a x
 294         /*! When a layer is disabled, it will be skipped when the
 295         **      canvas is rendered. */
 296         void set_active(bool x);
 297
 298         //! Returns that status of the 'active' flag
 299         bool active()const { return active_; }
 300
 301         //! Returns the position of the layer in the canvas.
 302         /*! Returns negative on error */
 303         int get_depth()const;
 304
 305         //! \writeme
 306         float get_z_depth()const { return z_depth_; }
 307
 308         //! \writeme
 309         float get_z_depth(const synfig::Time& t)const;
 310
 311         //! \writeme
 312         void set_z_depth(float x) { z_depth_=x; }
 313
 314         //! Sets the Canvas that this Layer is a part of
 315         void set_canvas(etl::loose_handle<Canvas> canvas);
 316
 317         //! Returns a handle to the Canvas to which this Layer belongs
 318         etl::loose_handle<Canvas> get_canvas()const;
 319
 320         //! \writeme
 321         const String& get_description()const { return description_; }
 322
 323         //! \writeme
 324         void set_description(const String& x);
 325
 326         //! Returns the layer's description if it's not empty, else its local name
 327         const String get_non_empty_description()const { return get_description().empty() ? get_local_name() : get_description(); }
 328
 329         //! Returns the localised version of the given layer parameter
 330         const String get_param_local_name(const String &param_name)const;
 331
 332         /*
 333  --     ** -- V I R T U A L   F U N C T I O N S -----------------------------------
 334         */
 335
 336 public:
 337         virtual Rect get_bounding_rect()const;
 338
 339         virtual Rect get_full_bounding_rect(Context context)const;
 340
 341         //! Returns a string containing the name of the Layer
 342         virtual String get_name()const;
 343
 344         //! Returns a string containing the localized name of the Layer
 345         virtual String get_local_name()const;
 346
 347         //! Gets the parameter vocabulary
 348         virtual Vocab get_param_vocab()const;
 349
 350         //! Gets the version string for this layer
 351         virtual String get_version()const;
 352
 353         //! \writeme
 354         virtual etl::handle<Transform> get_transform()const;
 355
 356         //! Sets the virtual version to use for backwards-compatibility
 357         /*!
 358         **      \see reset_version() */
 359         virtual bool set_version(const String &ver);
 360
 361         //! Resets the virtual version
 362         /*!
 363         **      \see set_version() */
 364         virtual void reset_version();
 365
 366         //!     Sets the parameter described by \a param to \a value.
 367         /*!     \param param The name of the parameter to set
 368         **      \param value What the parameter is to be set to.
 369         **      \return \c true on success, \c false upon rejection or failure.
 370         **              If it returns \c false, then the Layer is assumed to remain unchanged.
 371         **      \sa get_param()
 372         **      \todo \a param should be of the type <tt>const String \&param</tt>
 373         */
 374         virtual bool set_param(const String &param, const ValueBase &value);
 375
 376         //!     Sets a list of parameters
 377         virtual bool set_param_list(const ParamList &);
 378
 379         //! Get the value of the specified parameter.
 380         /*!     \return The requested parameter value, or (upon failure) a NIL ValueBase.
 381         **      \sa set_param()
 382         **      \todo \a param should be of the type <tt>const String \&</tt>
 383         */
 384         virtual ValueBase get_param(const String &param)const;
 385
 386         //! Get a list of all of the parameters and their values
 387         virtual ParamList get_param_list()const;
 388
 389         //! Sets the \a time for the selected Layer and those under it
 390         /*!     \param context          Context iterator referring to next Layer.
 391         **      \param time                     writeme
 392         **      \see Handle::set_time()
 393         */
 394         virtual void set_time(Context context, Time time)const;
 395
 396         //! Sets the \a time for the selected Layer and those under it for a specific \a point
 397         /*!     \param context          Context iterator referring to next Layer.
 398         **      \param time                     writeme
 399         **      \param point            writeme
 400         **      \see Handle::set_time()
 401         **      \todo \a point should be of the type <tt>const Point \&</tt> */
 402         virtual void set_time(Context context, Time time, const Point &point)const;
 403
 404         //! Gets the color of the Canvas at \a pos
 405         /*!     \param context          Context iterator referring to next Layer.
 406         **      \param pos              Point which indicates where the Color should come from
 407         **      \see Handle::get_color()
 408         */
 409         virtual Color get_color(Context context, const Point &pos)const;
 410
 411         //! Renders the Canvas to the given Surface in an accelerated manner
 412         /*!     \param context          Context iterator referring to next Layer.
 413         **      \param surface          Pointer to Surface to render to.
 414         **      \param quality          The requested quality-level to render at.
 415         **      \param renddesc         The associated RendDesc.
 416         **      \param cb                       Pointer to callback object. May be NULL if there is no callback.
 417         **      \return \c true on success, \c false on failure
 418         **      \see Handle::accelerated_render()
 419         */
 420         virtual bool accelerated_render(Context context,Surface *surface,int quality, const RendDesc &renddesc, ProgressCallback *cb)const;
 421
 422         //! Checks to see if a part of the layer is directly under \a point
 423         /*!     \param context          Context iterator referring to next Layer.
 424         **      \param point            The point to check
 425         **      \return         The handle of the layer under \a point. If there is not
 426         **                              a layer under \a point, then returns an empty handle. */
 427         virtual Handle hit_check(Context context, const Point &point)const;
 428
 429         //! Duplicates the Layer
 430         virtual Handle clone(const GUID& deriv_guid=GUID())const;
 431
 432         //! Returns true if the layer needs to be able to examine its context.
 433         /*! context to render itself, other than for simple blending.  For
 434         **  example, the blur layer will return true - it can't do its job
 435         **  if it can't see its context, and the circle layer will return
 436         **  false - rendering a circle doesn't depend on the underlying
 437         **  context until the final blend operation. */
 438         virtual bool reads_context()const;
 439
 440 #ifdef THIS_CODE_IS_NOT_USED
 441         //! Duplicates the Layer without duplicating the value nodes
 442         virtual Layer *simple_clone()const;
 443 #endif /* THIS_CODE_IS_NOT_USED */
 444
 445 protected:
 446
 447         //! This is called whenever a parameter is changed
 448         virtual void on_changed();
 449
 450         //! Called to figure out the animation time information
 451         virtual void get_times_vfunc(Node::time_set &set) const;
 452
 453         /*
 454  --     ** -- S T A T I C  F U N C T I O N S --------------------------------------
 455         */
 456
 457 public:
 458
 459         //! Creates a Layer of type \a type
 460         /*!     If the Layer type is unknown, then a Mime layer is created in its place.
 461         **      \param type     A string describing the name of the layer to construct.
 462         **      \return Always returns a handle to a new Layer.
 463         **      \see Mime
 464         */
 465         static Layer::LooseHandle create(const String &type);
 466
 467 }; // END of class Layer
 468
 469 }; // END of namespace synfig
 470
 471
 472 /* === E N D =============================================================== */
 473
 474 #endif