Delete svn tags. We don't need them in git
[synfig.git] / 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                                                                                                                 \
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         //! Duplicates the Layer without duplicating the value nodes
486         virtual Handle simple_clone()const;
487
488 protected:
489
490         //! This is called whenever a parameter is changed
491         virtual void on_changed();
492
493         //! Called to figure out the animation time information
494         virtual void get_times_vfunc(Node::time_set &set) const;
495
496         /*
497  --     ** -- S T A T I C  F U N C T I O N S --------------------------------------
498         */
499
500 public:
501
502         //! Creates a Layer of type \a type
503         /*!     If the Layer type is unknown, then a Mime layer is created in its place.
504         **      \param type     A string describing the name of the layer to construct.
505         **      \return Always returns a handle to a new Layer.
506         **      \see Mime
507         */
508         static Layer::LooseHandle create(const String &type);
509
510 }; // END of class Layer
511
512 }; // END of namespace synfig
513
514
515 /* === E N D =============================================================== */
516
517 #endif