[Synfig-devl] Carlos Lopez : Documentation for the layer composite

[Genete <ge...@us...>]

Module: synfig
Branch: genete_core_review
Commit: 5ea9ef7d86014471a8ce355a27d225828131d849
URL:    http://synfig.git.sourceforge.net/git/gitweb.cgi?p=synfig;a=commit;h=5ea9ef7d86014471a8ce355a27d225828131d849

Author: Carlos Lopez <gen...@gm...>
Date:   Sun Jul 18 20:48:01 2010 +0200

Documentation for the layer composite

---

 synfig-core/src/synfig/layer_composite.cpp |   16 +++++++++---
 synfig-core/src/synfig/layer_composite.h   |   35 ++++++++++++++++------------
 2 files changed, 32 insertions(+), 19 deletions(-)

diff --git a/synfig-core/src/synfig/layer_composite.cpp b/synfig-core/src/synfig/layer_composite.cpp
index 6a25efc..5d03787 100644
--- a/synfig-core/src/synfig/layer_composite.cpp
+++ b/synfig-core/src/synfig/layer_composite.cpp
@@ -92,18 +92,22 @@ Layer_Composite::accelerated_render(Context context,Surface *surface,int quality
 
 	image.push_back(0);	// Alpha black
 
-	// Render the backdrop
+	// Render the backdrop on the surface layer's surface.
 	if(!context.accelerated_render(&surfacelayer->surface,quality,renddesc,&stageone))
 		return false;
-
+	// Sets up the interpolation of the context (now the surface layer is the first one)
+	// depending on the quality
 	if(quality<=4)surfacelayer->c=3;else
 	if(quality<=5)surfacelayer->c=2;
 	else if(quality<=6)surfacelayer->c=1;
 	else surfacelayer->c=0;
 	surfacelayer->tl=renddesc.get_tl();
 	surfacelayer->br=renddesc.get_br();
+	// Sets the blend method to straight. See below
 	surfacelayer->set_blend_method(Color::BLEND_STRAIGHT);
-
+	// Push this layer on the image. The blending result is only this layer
+	// adn the surface layer. The rest of the context is ignored by the straight
+	// blend method of surface layer
 	image.push_front(const_cast<synfig::Layer_Composite*>(this));
 
 	// Set up a surface target
@@ -136,8 +140,9 @@ Layer_Composite::get_full_bounding_rect(Context context)const
 Layer::Vocab
 Layer_Composite::get_param_vocab()const
 {
+	//! First fills the returning vocabulary with the ancestor class
 	Layer::Vocab ret(Layer::get_param_vocab());
-
+	//! Now inserts the two parameters that this layer knows.
 	ret.push_back(ParamDesc(amount_,"amount")
 		.set_local_name(_("Amount"))
 	);
@@ -200,9 +205,12 @@ Layer_Composite::set_param(const String & param, const ValueBase &value)
 ValueBase
 Layer_Composite::get_param(const String & param)const
 {
+	//! First check if the parameter's string is known.
 	if(param=="amount")
 		return get_amount();
 	if(param=="blend_method")
 		return static_cast<int>(get_blend_method());
+	//! If it is unknown then call the ancestor's get param member
+	//! to see if it can handle that parameter's string.
 	return Layer::get_param(param);
 }
diff --git a/synfig-core/src/synfig/layer_composite.h b/synfig-core/src/synfig/layer_composite.h
index cb9497d..458bae7 100644
--- a/synfig-core/src/synfig/layer_composite.h
+++ b/synfig-core/src/synfig/layer_composite.h
@@ -48,13 +48,13 @@ class Layer_NoDeform {};
 class Layer_Composite : public Layer
 {
 private:
-
+	//! The amount of composite
 	float amount_;
-
+	//! The blend method for the composition
 	Color::BlendMethod blend_method_;
 
 protected:
-
+	//! Default constructor. Not used directly.
 	Layer_Composite(
 		float 	amount=1.0,
 		Color::BlendMethod 	blend_method=Color::BLEND_COMPOSITE
@@ -64,32 +64,37 @@ protected:
 		converted_blend_	(false),
 		transparent_color_	(false)
 	{ }
-
+	//! Converted blend is used to check if an old version of canvas
+	//! is used in the composition. Old Straight was used as new Composite
+	//! \todo verify this
 	bool converted_blend_;
+	//! Transparent color is used for old canvas versions.
+	//!Old Straight plus transparent color seems to be the same new than alpha over.
 	bool transparent_color_;
 
 public:
-
+	//! Gets the amount of the layer
 	float get_amount()const { return amount_; }
-
+	//! Sets the amount of the layer and returns this layer
 	Layer_Composite& set_amount(float x) { amount_=x; return *this; }
-
+	//! Gets the blend method of the layer
 	Color::BlendMethod get_blend_method()const { return blend_method_; }
-
+	//! Sets the blend method of the layer and returns this layer
 	Layer_Composite& set_blend_method(Color::BlendMethod x) { blend_method_=x; return *this; }
-
+	//! Returns true is amount is 1 and blend method is straight
 	virtual bool is_solid_color()const { return amount_==1.0f && blend_method_==Color::BLEND_STRAIGHT; }
-
+	//! Returns true if the amount is zero.
 	bool is_disabled()const { return amount_==0.0f; }
-
+	//! Gets the parameter vocabulary. To be overrided by the derived.
 	virtual Vocab get_param_vocab()const;
-
+	//! Sets the value for the given parameter.
 	virtual bool set_param(const String &param, const ValueBase &value);
-
+	//! Gets the value of the given parameter
 	virtual ValueBase get_param(const String &param)const;
-
+	//!Returns the rectangle that includes the context of the layer and
+	//! the intersection of the layer in case it is active and not onto
 	virtual Rect get_full_bounding_rect(Context context)const;
-
+	//! Renders the layer composited on the context and puts it on the target surface.
 	virtual bool accelerated_render(Context context,Surface *surface,int quality, const RendDesc &renddesc, ProgressCallback *cb)const;
 }; // END of class Layer_Composite