1 /* === S Y N F I G ========================================================= */
3 ** \brief Layer Class Header
8 ** Copyright (c) 2002-2005 Robert B. Quattlebaum Jr., Adrian Bentley
9 ** Copyright (c) 2008 Chris Moore
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.
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.
22 /* ========================================================================= */
24 /* === S T A R T =========================================================== */
26 #ifndef __SYNFIG_LAYER_H
27 #define __SYNFIG_LAYER_H
29 /* === H E A D E R S ======================================================= */
31 #include "string_decl.h"
36 #include <sigc++/signal.h>
37 #include <sigc++/connection.h>
42 /* === M A C R O S ========================================================= */
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 \
48 static const char name__[], version__[], cvs_id__[], local_name__[], category__[]; \
49 static Layer *create();
51 //! Sets the name of the layer
52 #define SYNFIG_LAYER_SET_NAME(class,x) \
53 const char class::name__[]=x
55 //! Sets the local name of the layer
56 #define SYNFIG_LAYER_SET_LOCAL_NAME(class,x) \
57 const char class::local_name__[]=x;
59 //! Sets the category of the layer
60 #define SYNFIG_LAYER_SET_CATEGORY(class,x) \
61 const char class::category__[]=x
63 //! Sets the version string for the layer
64 #define SYNFIG_LAYER_SET_VERSION(class,x) \
65 const char class::version__[]=x
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
71 //! Defines de implementation of the create method for the importer
72 #define SYNFIG_LAYER_INIT(class) \
73 synfig::Layer* class::create() \
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)) \
84 set_param_static(#x,value.get_static()); \
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)) \
96 set_param_static(y,value.get_static()); \
100 //! Imports a parameter if it is of the same type as param
104 //! Exports a parameter 'x' if param is same type as given 'y'
105 #define EXPORT_AS(x,y) \
108 synfig::ValueBase ret(x); \
109 ret.set_static(get_param_static(y)); \
113 //! Exports a parameter if it is the same type as value
117 //! Exports the name or the local name of the layer
118 #define EXPORT_NAME() \
119 if (param=="Name" || param=="name" || param=="name__") \
121 else if (param=="local_name__") \
122 return dgettext("synfig",local_name__);
124 //! Exports the version of the layer
125 #define EXPORT_VERSION() \
126 if (param=="Version" || param=="version" || param=="version__") \
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"
133 //! x=variable name, y=static bool value
134 #define SET_STATIC(x,y) \
135 if(param==#x && x ## _static != y) \
141 #define GET_STATIC(x) \
143 return x ## _static; \
146 /* === T Y P E D E F S ===================================================== */
148 /* === C L A S S E S & S T R U C T S ======================================= */
154 typedef Vector Point;
163 class ProgressCallback;
175 class Layer : public Node
177 friend class ValueNode;
178 friend class Context;
181 -- ** -- T Y P E S -----------------------------------------------------------
186 //! Type that represents a pointer to a Layer's constructor.
187 /*! As a pointer to the constructor, it represents a "factory" of layers.
189 typedef Layer* (*Factory)();
200 BookEntry(Factory factory,
202 const String &local_name,
203 const String &category,
204 const String &cvs_id,
205 const String &version):
208 local_name(local_name),
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
219 ** \sa Layer::Factory
221 typedef std::map<String,BookEntry> Book;
223 static void register_in_book(const BookEntry &);
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
231 static bool subsys_init();
233 //! Stops the layer system by deleting the book of registered layers
234 static bool subsys_stop();
236 //! Map of Value Base parameters indexed by name
237 typedef std::map<String,ValueBase> ParamList;
239 typedef etl::handle<Layer> Handle;
241 typedef etl::loose_handle<Layer> LooseHandle;
243 typedef etl::handle<const Layer> ConstHandle;
245 //! Map of parameters that are animated Value Nodes indexed by the param name
246 typedef std::map<String,etl::rhandle<ValueNode> > DynamicParamList;
248 //! A list type which describes all the parameters that a layer has.
249 /*! \see get_param_vocab() */
250 typedef ParamVocab Vocab;
253 -- ** -- D A T A -------------------------------------------------------------
258 /*! \c true if the layer is visible, \c false if it is to be skipped
259 ** \see set_active(), enable(), disable, active()
263 //! Handle to the canvas to which this layer belongs
264 etl::loose_handle<Canvas> canvas_;
266 //! Map of parameter with animated value nodes
267 DynamicParamList dynamic_param_list_;
269 //! A description of what this layer does
272 //! The depth parameter of the layer in the layer stack
275 //! True if zdepth is not affected when in animation mode
276 typedef std::map<String, bool> Sparams;
277 Sparams static_params;
280 mutable Time dirty_time_;
282 //! Contains the name of the group that this layer belongs to
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_;
292 -- ** -- S I G N A L S -------------------------------------------------------
298 sigc::signal<void> signal_status_changed_;
300 //! Parameter changed
301 sigc::signal<void,String> signal_param_changed_;
303 //! Description Changed
304 sigc::signal<void> signal_description_changed_;
307 sigc::signal<void, int, etl::handle<Canvas> > signal_moved_;
309 sigc::signal<void, String> signal_added_to_group_;
311 sigc::signal<void, String> signal_removed_from_group_;
314 -- ** -- S I G N A L I N T E R F A C E -------------------------------------
320 sigc::signal<void>& signal_status_changed() { return signal_status_changed_; }
322 //! Parameter changed
323 sigc::signal<void,String>& signal_param_changed() { return signal_param_changed_; }
325 //! Description Changed
326 sigc::signal<void>& signal_description_changed() { return signal_description_changed_;}
329 sigc::signal<void, int, etl::handle<Canvas> >& signal_moved() { return signal_moved_; }
331 sigc::signal<void, String>& signal_added_to_group() { return signal_added_to_group_; }
333 sigc::signal<void, String>& signal_removed_from_group() { return signal_removed_from_group_; }
336 -- ** -- C O N S T R U C T O R S ---------------------------------------------
347 -- ** -- M E M B E R F U N C T I O N S -------------------------------------
352 virtual void on_canvas_set();
354 //! Adds this layer to the given layer group
355 void add_to_group(const String&);
357 //! Removes this layer from the given layer group
358 void remove_from_group(const String&);
360 //! Removes this layer from all layer groups
361 void remove_from_all_groups();
363 //! Gets the name of the group that this layer belongs to
364 String get_group()const;
366 //! Retrieves the dynamic param list member
367 //! \see DynamicParamList
368 const DynamicParamList &dynamic_param_list()const { return dynamic_param_list_; }
370 //! Connects the parameter to another Value Node
371 bool connect_dynamic_param(const String& param, etl::loose_handle<ValueNode>);
373 //! Disconnects the parameter from any Value Node
374 bool disconnect_dynamic_param(const String& param);
376 //! Enables the layer for rendering (Making it \em active)
377 void enable() { set_active(true); }
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); }
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);
389 //! Returns that status of the 'active' flag
390 bool active()const { return active_; }
392 //! Returns the position of the layer in the canvas.
393 /*! Returns negative on error */
394 int get_depth()const;
396 //! Gets the non animated z depth of the layer
397 float get_z_depth()const { return z_depth; }
399 //! Gets the z depth of the layer at a time t
400 float get_z_depth(const synfig::Time& t)const;
402 //! Sets the z depth of the layer (non animated)
403 void set_z_depth(float x) { z_depth=x; }
405 //! Sets the Canvas that this Layer is a part of
406 void set_canvas(etl::loose_handle<Canvas> canvas);
408 //! Returns a handle to the Canvas to which this Layer belongs
409 etl::loose_handle<Canvas> get_canvas()const;
411 //! Returns the description of the layer
412 const String& get_description()const { return description_; }
414 //! Sets the description of the layer
415 void set_description(const String& x);
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(); }
420 //! Returns the localised version of the given layer parameter
421 const String get_param_local_name(const String ¶m_name)const;
424 -- ** -- V I R T U A L F U N C T I O N S -----------------------------------
428 //! Returns the rectangle that includes the layer
429 //! \see synfig::Rect
430 virtual Rect get_bounding_rect()const;
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;
436 //! Returns a string containing the name of the Layer
437 virtual String get_name()const;
439 //! Returns a string containing the localized name of the Layer
440 virtual String get_local_name()const;
442 //! Gets the parameter vocabulary
443 virtual Vocab get_param_vocab()const;
445 //! Gets the version string for this layer
446 virtual String get_version()const;
448 //! Returns a handle to the Transform class of the layer
449 //! \see synfig::Transform
450 virtual etl::handle<Transform> get_transform()const;
452 //! Sets the virtual version to use for backwards-compatibility
454 ** \see reset_version() */
455 virtual bool set_version(const String &ver);
457 //! Resets the virtual version
459 ** \see set_version() */
460 virtual void reset_version();
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.
468 ** \todo \a param should be of the type <tt>const String \¶m</tt>
470 virtual bool set_param(const String ¶m, const ValueBase &value);
472 virtual bool set_param_static(const String ¶m, const bool x);
473 virtual bool get_param_static(const String ¶m) const;
474 virtual void fill_static(Vocab vocab);
476 //! Sets a list of parameters
477 virtual bool set_param_list(const ParamList &);
479 //! Get the value of the specified parameter.
480 /*! \return The requested parameter value, or (upon failure) a NIL ValueBase.
482 ** \todo \a param should be of the type <tt>const String \&</tt>
484 virtual ValueBase get_param(const String ¶m)const;
486 //! Get a list of all of the parameters and their values
487 virtual ParamList get_param_list()const;
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()
494 virtual void set_time(Context context, Time time)const;
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;
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()
509 virtual Color get_color(Context context, const Point &pos)const;
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()
520 virtual bool accelerated_render(Context context,Surface *surface,int quality, const RendDesc &renddesc, ProgressCallback *cb)const;
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
529 virtual Handle hit_check(Context context, const Point &point)const;
531 //! Duplicates the Layer
532 virtual Handle clone(const GUID& deriv_guid=GUID())const;
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;
542 //! Duplicates the Layer without duplicating the value nodes
543 virtual Handle simple_clone()const;
547 //! This is called whenever a parameter is changed
548 virtual void on_changed();
550 //! Called to figure out the animation time information
551 virtual void get_times_vfunc(Node::time_set &set) const;
554 -- ** -- S T A T I C F U N C T I O N S --------------------------------------
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.
565 static Layer::LooseHandle create(const String &type);
567 }; // END of class Layer
569 }; // END of namespace synfig
572 /* === E N D =============================================================== */