synfig-core/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 //! Defines various variables and the create method, common for all importers.
  45 //! To be used in the private part of the importer class definition.
  46 #define SYNFIG_LAYER_MODULE_EXT                                                                                                                 \
  47         public:                                                                                                                                                         \
  48         static const char name__[], version__[], cvs_id__[], local_name__[], category__[];      \
  49         static Layer *create();
  50
  51 //! Sets the name of the layer
  52 #define SYNFIG_LAYER_SET_NAME(class,x)                                                                                                  \
  53         const char class::name__[]=x
  54
  55 //! Sets the local name of the layer
  56 #define SYNFIG_LAYER_SET_LOCAL_NAME(class,x)                                                                                    \
  57         const char class::local_name__[]=x;
  58
  59 //! Sets the category of the layer
  60 #define SYNFIG_LAYER_SET_CATEGORY(class,x)                                                                                              \
  61         const char class::category__[]=x
  62
  63 //! Sets the version string for the layer
  64 #define SYNFIG_LAYER_SET_VERSION(class,x)                                                                                               \
  65         const char class::version__[]=x
  66
  67 //! Sets the CVS ID string for the layer
  68 #define SYNFIG_LAYER_SET_CVS_ID(class,x)                                                                                                \
  69         const char class::cvs_id__[]=x
  70
  71 //! Defines de implementation of the create method for the importer
  72 #define SYNFIG_LAYER_INIT(class)                                                                                                                \
  73         synfig::Layer* class::create()                                                                                                          \
  74         {                                                                                                                                                                       \
  75                 return new class();                                                                                                                             \
  76         }
  77
  78 //! Imports a parameter 'x' and perform an action based usually based on
  79 //! some condition 'y'
  80 #define IMPORT_PLUS(x,y)                                                                                                                                \
  81         if (param==#x && value.same_type_as(x))                                                                                         \
  82         {                                                                                                                                                                       \
  83                 value.put(&x);                                                                                                                                  \
  84                 set_param_static(#x,value.get_static());                                                                                \
  85                 {                                                                                                                                                               \
  86                         y;                                                                                                                                                      \
  87                 }                                                                                                                                                               \
  88                 return true;                                                                                                                                    \
  89         }
  90
  91 //! Imports a parameter 'y' if it has the same type than 'x'
  92 #define IMPORT_AS(x,y)                                                                                                                                  \
  93         if (param==y && value.same_type_as(x))                                                                                          \
  94         {                                                                                                                                                                       \
  95                 value.put(&x);                                                                                                                                  \
  96                 set_param_static(y,value.get_static());                                                                         \
  97                 return true;                                                                                                                                    \
  98         }
  99
 100 //! Imports a parameter if it is of the same type as param
 101 #define IMPORT(x)                                                                                                                                               \
 102         IMPORT_AS(x,#x)
 103
 104 //! Exports a parameter 'x' if param is same type as given 'y'
 105 #define EXPORT_AS(x,y)                                                                                                                                  \
 106         if (param==y)                                                                                                                                           \
 107         {                                                                                                                                                                       \
 108                 synfig::ValueBase ret(x);                                                                                                               \
 109                 ret.set_static(get_param_static(y));                                                                                    \
 110                 return ret;                                                                                                                                             \
 111         }
 112
 113 //! Exports a parameter if it is the same type as value
 114 #define EXPORT(x)                                                                                                                                               \
 115         EXPORT_AS(x,#x)
 116
 117 //! Exports the name or the local name of the layer
 118 #define EXPORT_NAME()                                                                                                                                   \
 119         if (param=="Name" || param=="name" || param=="name__")                                                          \
 120                 return name__;                                                                                                                                  \
 121         else if (param=="local_name__")                                                                                                         \
 122                 return dgettext("synfig",local_name__);
 123
 124 //! Exports the version of the layer
 125 #define EXPORT_VERSION()                                                                                                                                \
 126         if (param=="Version" || param=="version" || param=="version__")                                         \
 127                 return version__;
 128
 129 //! This is used as the category for layer book entries which represent aliases of layers.
 130 //! It prevents these layers showing up in the menu.
 131 #define CATEGORY_DO_NOT_USE "Do Not Use"
 132 /*
 133 //! x=variable name, y=static bool value
 134 #define SET_STATIC(x,y)                                                                                                                                 \
 135         if(param==#x && x ## _static != y)                                                                                                      \
 136         {                                                                                                                                                                       \
 137                 x ## _static = y;                                                                                                                               \
 138                 return true;                                                                                                                                    \
 139         }
 140
 141 #define GET_STATIC(x)                                                                                                                                   \
 142         if(param==#x)                                                                                                                                           \
 143                 return x ## _static;                                                                                                                    \
 144 */
 145
 146 /* === T Y P E D E F S ===================================================== */
 147
 148 /* === C L A S S E S & S T R U C T S ======================================= */
 149
 150 namespace synfig {
 151
 152 class Canvas;
 153 class Vector;
 154 typedef Vector Point;
 155 class Canvas;
 156 class ParamDesc;
 157 class ParamVocab;
 158 class ValueNode;
 159 class ValueBase;
 160 class Time;
 161 class Surface;
 162 class RendDesc;
 163 class ProgressCallback;
 164 class Context;
 165 class Color;
 166 class Transform;
 167 class Rect;
 168 class GUID;
 169
 170
 171 /*!     \class Layer
 172 **      \todo writeme
 173 **      \see Canvas
 174 */
 175 class Layer : public Node
 176 {
 177         friend class ValueNode;
 178         friend class Context;
 179
 180         /*
 181  --     ** -- T Y P E S -----------------------------------------------------------
 182         */
 183
 184 public:
 185
 186         //! Type that represents a pointer to a Layer's constructor.
 187         /*! As a pointer to the constructor, it represents a "factory" of layers.
 188         */
 189         typedef Layer* (*Factory)();
 190
 191         struct BookEntry
 192         {
 193                 Factory factory;
 194                 String name;
 195                 String local_name;
 196                 String category;
 197                 String cvs_id;
 198                 String version;
 199                 BookEntry() { }
 200                 BookEntry(Factory                factory,
 201                                   const String  &name,
 202                                   const String  &local_name,
 203                                   const String  &category,
 204                                   const String  &cvs_id,
 205                                   const String  &version):
 206                         factory(factory),
 207                         name(name),
 208                         local_name(local_name),
 209                         category(category),
 210                         cvs_id(cvs_id),
 211                         version(version) { }
 212         };
 213
 214         //! Book of types of layers indexed by layer type name.
 215         /*! While the sifz file is read, each time a new layer entry is found,
 216         **  the factory constructor that the "factory" pointer member of the
 217         **  "BookEntry" struct points to, is called, and a new layer of that type
 218         **  is created.
 219         **  \sa Layer::Factory
 220         */
 221         typedef std::map<String,BookEntry> Book;
 222
 223         static void register_in_book(const BookEntry &);
 224
 225         static Book& book();
 226
 227         //! Inits the book of layers and inserts in it the basic layers that
 228         //! doesn't depend on modules
 229         /*! \todo motionblur should be in the mod_filter module
 230         */
 231         static bool subsys_init();
 232
 233         //! Stops the layer system by deleting the book of registered layers
 234         static bool subsys_stop();
 235
 236         //! Map of Value Base parameters indexed by name
 237         typedef std::map<String,ValueBase> ParamList;
 238
 239         typedef etl::handle<Layer> Handle;
 240
 241         typedef etl::loose_handle<Layer> LooseHandle;
 242
 243         typedef etl::handle<const Layer> ConstHandle;
 244
 245         //! Map of parameters that are animated Value Nodes indexed by the param name
 246         typedef std::map<String,etl::rhandle<ValueNode> > DynamicParamList;
 247
 248         //! A list type which describes all the parameters that a layer has.
 249         /*! \see get_param_vocab() */
 250         typedef ParamVocab Vocab;
 251
 252         /*
 253  --     ** -- D A T A -------------------------------------------------------------
 254         */
 255
 256 private:
 257
 258         /*! \c true if the layer is visible, \c false if it is to be skipped
 259         **      \see set_active(), enable(), disable, active()
 260         */
 261         bool active_;
 262
 263         //! Handle to the canvas to which this layer belongs
 264         etl::loose_handle<Canvas> canvas_;
 265
 266         //! Map of parameter with animated value nodes
 267         DynamicParamList dynamic_param_list_;
 268
 269         //! A description of what this layer does
 270         String description_;
 271
 272         //! The depth parameter of the layer in the layer stack
 273         float z_depth;
 274
 275         //! True if zdepth is not affected when in animation mode
 276         typedef std::map<String, bool> Sparams;
 277         Sparams static_params;
 278
 279         //! \writeme
 280         mutable Time dirty_time_;
 281
 282         //! Contains the name of the group that this layer belongs to
 283         String group_;
 284
 285         //! Signal to connect to the signal_deleted canvas's member
 286         //! Used to do let a layer with a canvas parent that doesn't exists
 287         //! Instead of that it connects to a zero canvas
 288         //! \see Layer::set_canvas()
 289         sigc::connection parent_death_connect_;
 290
 291         /*
 292  -- ** -- S I G N A L S -------------------------------------------------------
 293         */
 294
 295 private:
 296
 297         //!     Status Changed
 298         sigc::signal<void> signal_status_changed_;
 299
 300         //!     Parameter changed
 301         sigc::signal<void,String> signal_param_changed_;
 302
 303         //!     Description Changed
 304         sigc::signal<void> signal_description_changed_;
 305
 306         //!     Moved
 307         sigc::signal<void, int, etl::handle<Canvas> > signal_moved_;
 308
 309         sigc::signal<void, String> signal_added_to_group_;
 310
 311         sigc::signal<void, String> signal_removed_from_group_;
 312
 313         /*
 314  -- ** -- S I G N A L   I N T E R F A C E -------------------------------------
 315         */
 316
 317 public:
 318
 319         //!     Status Changed
 320         sigc::signal<void>& signal_status_changed() { return signal_status_changed_; }
 321
 322         //!     Parameter changed
 323         sigc::signal<void,String>& signal_param_changed() { return signal_param_changed_; }
 324
 325         //!     Description Changed
 326         sigc::signal<void>& signal_description_changed() { return signal_description_changed_;}
 327
 328         //!     Moved
 329         sigc::signal<void, int, etl::handle<Canvas> >& signal_moved() { return signal_moved_; }
 330
 331         sigc::signal<void, String>& signal_added_to_group() { return signal_added_to_group_; }
 332
 333         sigc::signal<void, String>& signal_removed_from_group() { return signal_removed_from_group_; }
 334
 335         /*
 336  --     ** -- C O N S T R U C T O R S ---------------------------------------------
 337         */
 338
 339 protected:
 340
 341         Layer();
 342
 343 public:
 344         virtual ~Layer();
 345
 346         /*
 347  --     ** -- M E M B E R   F U N C T I O N S -------------------------------------
 348         */
 349
 350 public:
 351
 352         virtual void on_canvas_set();
 353
 354         //! Adds this layer to the given layer group
 355         void add_to_group(const String&);
 356
 357         //! Removes this layer from the given layer group
 358         void remove_from_group(const String&);
 359
 360         //! Removes this layer from all layer groups
 361         void remove_from_all_groups();
 362
 363         //! Gets the name of the group that this layer belongs to
 364         String get_group()const;
 365
 366         //! Retrieves the dynamic param list member
 367         //! \see DynamicParamList
 368         const DynamicParamList &dynamic_param_list()const { return dynamic_param_list_; }
 369
 370         //! Connects the parameter to another Value Node
 371         bool connect_dynamic_param(const String& param, etl::loose_handle<ValueNode>);
 372
 373         //! Disconnects the parameter from any Value Node
 374         bool disconnect_dynamic_param(const String& param);
 375
 376         //! Enables the layer for rendering (Making it \em active)
 377         void enable() { set_active(true); }
 378
 379         //! Disables the layer for rendering. (Making it \em inactive)
 380         /*! When a layer is disabled, it will be skipped when the
 381         **      canvas is rendered. */
 382         void disable() { set_active(false); }
 383
 384         //! Sets the 'active' flag for the Layer to the state described by \a x
 385         /*! When a layer is disabled, it will be skipped when the
 386         **      canvas is rendered. */
 387         void set_active(bool x);
 388
 389         //! Returns that status of the 'active' flag
 390         bool active()const { return active_; }
 391
 392         //! Returns the position of the layer in the canvas.
 393         /*! Returns negative on error */
 394         int get_depth()const;
 395
 396         //! Gets the non animated z depth of the layer
 397         float get_z_depth()const { return z_depth; }
 398
 399         //! Gets the z depth of the layer at a time t
 400         float get_z_depth(const synfig::Time& t)const;
 401
 402         //! Sets the z depth of the layer (non animated)
 403         void set_z_depth(float x) { z_depth=x; }
 404
 405         //! Sets the Canvas that this Layer is a part of
 406         void set_canvas(etl::loose_handle<Canvas> canvas);
 407
 408         //! Returns a handle to the Canvas to which this Layer belongs
 409         etl::loose_handle<Canvas> get_canvas()const;
 410
 411         //! Returns the description of the layer
 412         const String& get_description()const { return description_; }
 413
 414         //! Sets the description of the layer
 415         void set_description(const String& x);
 416
 417         //! Returns the layer's description if it's not empty, else its local name
 418         const String get_non_empty_description()const { return get_description().empty() ? get_local_name() : get_description(); }
 419
 420         //! Returns the localised version of the given layer parameter
 421         const String get_param_local_name(const String &param_name)const;
 422
 423         /*
 424  --     ** -- V I R T U A L   F U N C T I O N S -----------------------------------
 425         */
 426
 427 public:
 428         //! Returns the rectangle that includes the layer
 429         //! \see synfig::Rect
 430         virtual Rect get_bounding_rect()const;
 431
 432         //!Returns the rectangle that includes the context of the layer
 433         //!\see synfig::Rect synfig::Context
 434         virtual Rect get_full_bounding_rect(Context context)const;
 435
 436         //! Returns a string containing the name of the Layer
 437         virtual String get_name()const;
 438
 439         //! Returns a string containing the localized name of the Layer
 440         virtual String get_local_name()const;
 441
 442         //! Gets the parameter vocabulary
 443         virtual Vocab get_param_vocab()const;
 444
 445         //! Gets the version string for this layer
 446         virtual String get_version()const;
 447
 448         //! Returns a handle to the Transform class of the layer
 449         //! \see synfig::Transform
 450         virtual etl::handle<Transform> get_transform()const;
 451
 452         //! Sets the virtual version to use for backwards-compatibility
 453         /*!
 454         **      \see reset_version() */
 455         virtual bool set_version(const String &ver);
 456
 457         //! Resets the virtual version
 458         /*!
 459         **      \see set_version() */
 460         virtual void reset_version();
 461
 462         //!     Sets the parameter described by \a param to \a value.
 463         /*!     \param param The name of the parameter to set
 464         **      \param value What the parameter is to be set to.
 465         **      \return \c true on success, \c false upon rejection or failure.
 466         **              If it returns \c false, then the Layer is assumed to remain unchanged.
 467         **      \sa get_param()
 468         **      \todo \a param should be of the type <tt>const String \&param</tt>
 469         */
 470         virtual bool set_param(const String &param, const ValueBase &value);
 471
 472         virtual bool set_param_static(const String &param, const bool x);
 473         virtual bool get_param_static(const String &param) const;
 474         virtual void fill_static(Vocab vocab);
 475
 476         //!     Sets a list of parameters
 477         virtual bool set_param_list(const ParamList &);
 478
 479         //! Get the value of the specified parameter.
 480         /*!     \return The requested parameter value, or (upon failure) a NIL ValueBase.
 481         **      \sa set_param()
 482         **      \todo \a param should be of the type <tt>const String \&</tt>
 483         */
 484         virtual ValueBase get_param(const String &param)const;
 485
 486         //! Get a list of all of the parameters and their values
 487         virtual ParamList get_param_list()const;
 488
 489         //! Sets the \a time for the Layer and those under it
 490         /*!     \param context          Context iterator referring to next Layer.
 491         **      \param time                     writeme
 492         **      \see Context::set_time()
 493         */
 494         virtual void set_time(Context context, Time time)const;
 495
 496         //! Sets the \a time for the selected Layer and those under it for a specific \a point
 497         /*!     \param context          Context iterator referring to next Layer.
 498         **      \param time                     writeme
 499         **      \param point            writeme
 500         **      \see Context::set_time()
 501         **      \todo \a point should be of the type <tt>const Point \&</tt> */
 502         virtual void set_time(Context context, Time time, const Point &point)const;
 503
 504         //! Gets the blend color of the Layer in the context at \a pos
 505         /*!     \param context          Context iterator referring to next Layer.
 506         **      \param pos              Point which indicates where the Color should come from
 507         **      \see Context::get_color()
 508         */
 509         virtual Color get_color(Context context, const Point &pos)const;
 510
 511         //! Renders the Canvas to the given Surface in an accelerated manner
 512         /*!     \param context          Context iterator referring to next Layer.
 513         **      \param surface          Pointer to Surface to render to.
 514         **      \param quality          The requested quality-level to render at.
 515         **      \param renddesc         The associated RendDesc.
 516         **      \param cb                       Pointer to callback object. May be NULL if there is no callback.
 517         **      \return \c true on success, \c false on failure
 518         **      \see Context::accelerated_render()
 519         */
 520         virtual bool accelerated_render(Context context,Surface *surface,int quality, const RendDesc &renddesc, ProgressCallback *cb)const;
 521
 522         //! Checks to see if a part of the layer is directly under \a point
 523         /*!     \param context          Context iterator referring to next Layer.
 524         **      \param point            The point to check
 525         **      \return         The handle of the layer under \a point. If there is not
 526         **                              a layer under \a point, then returns an empty handle.
 527         **      \see Context::hit_check
 528         */
 529         virtual Handle hit_check(Context context, const Point &point)const;
 530
 531         //! Duplicates the Layer
 532         virtual Handle clone(const GUID& deriv_guid=GUID())const;
 533
 534         //! Returns true if the layer needs to be able to examine its context.
 535         /*! context to render itself, other than for simple blending.  For
 536         **  example, the blur layer will return true - it can't do its job
 537         **  if it can't see its context, and the circle layer will return
 538         **  false - rendering a circle doesn't depend on the underlying
 539         **  context until the final blend operation. */
 540         virtual bool reads_context()const;
 541
 542         //! Duplicates the Layer without duplicating the value nodes
 543         virtual Handle simple_clone()const;
 544
 545 protected:
 546
 547         //! This is called whenever a parameter is changed
 548         virtual void on_changed();
 549
 550         //! Called to figure out the animation time information
 551         virtual void get_times_vfunc(Node::time_set &set) const;
 552
 553         /*
 554  --     ** -- S T A T I C  F U N C T I O N S --------------------------------------
 555         */
 556
 557 public:
 558
 559         //! Creates a Layer of type \a type
 560         /*!     If the Layer type is unknown, then a Mime layer is created in its place.
 561         **      \param type     A string describing the name of the layer to construct.
 562         **      \return Always returns a handle to a new Layer.
 563         **      \see Mime
 564         */
 565         static Layer::LooseHandle create(const String &type);
 566
 567 }; // END of class Layer
 568
 569 }; // END of namespace synfig
 570
 571
 572 /* === E N D =============================================================== */
 573
 574 #endif