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