From 31b92d5ef4513376bc617fb30fcf78fdf6f4fc4e Mon Sep 17 00:00:00 2001
From: Thibault Saunier <thibault.saunier@collabora.co.uk>
Date: Tue, 25 Jan 2011 19:53:36 +0100
Subject: [PATCH] Specs: Add a description of the GESEffect class

---
 docs/design/effects.txt | 49 +++++++++++++++++++++++++++++++++--------
 1 file changed, 40 insertions(+), 9 deletions(-)

diff --git a/docs/design/effects.txt b/docs/design/effects.txt
index cb43b7ee35..7be99b9f05 100644
--- a/docs/design/effects.txt
+++ b/docs/design/effects.txt
@@ -124,11 +124,11 @@ C. Keyframes
       *
       * @object: The origin #GESTrackObject
       *
-      * Get all the usefull configurable properties of the GstElement contained
-      * in @object.
+      * A convenience method that lists all the usefull configurable properties
+      * of the GstElement-s contained in @object.
       *
       * Returns: an array of GParamSpec of the configurable properties of the
-      * GstElement-s contained in @object
+      * GstElement-s contained in @object or %NULL if a problem occurred.
       */
       GParamSpec **
       ges_track_object_list_children_properties (GESTrackObject *object);
@@ -164,6 +164,19 @@ C. Keyframes
                                               const gchar *property_name,
                                               GValue * value);
 
+      /**
+      * ges_track_object_get_material:
+      *
+      * @object: The origin #GESTrackObject
+      *
+      * This is a convenience method to get the #GESMaterial
+      * from which @object has been made.
+      *
+      * Returns: The material from which @object has been made or %NULL
+      * if @object has been made by another mean
+      */
+      GESMaterial *ges_track_object_get_material (GESTrackObject *object);
+
   B. GESTimelineObject new API
 
       signals:
@@ -176,17 +189,18 @@ C. Keyframes
       * ges_timeline_object_add_effect:
       *
       * @object: The origin #GESTimelineObject
-      * @effect_material: The #GESMaterial from which to create the effect
+      * @effect_material: The #GESEffect from which to create the effect
       * @position: The top position you want to give to the effect,
       * -1 if you want it to be added at the end of effects.
       *
-      * Adds a new effect corresponding to @material to the #GESTimelineObject
+      * Adds a new effect corresponding to @effect_material to the
+      * #GESTimelineObject
       *
       * Returns: The newly created #GESTrackEffect, or %NULL if there was an
       * error.
       */
       GESTrackEffect *ges_timeline_object_add_effect (GESTimelineObject *object,
-                                                  GESMaterial *effect_material,
+                                                  GESEffect *effect_material,
                                                   gint position);
 
       /**
@@ -222,15 +236,16 @@ C. Keyframes
       /**
       * ges_track_effect_new_from_material:
       *
-      * @material: The #GESMaterial from which to create this GESTrackEffect
+      * @effect_material: The #GESEffect from which to create this
+      * #GESTrackEffect
       *
-      * Creates a new #GESTrackEffect from a #GESMaterial
+      * Creates a new #GESTrackEffect from a #GESEffect
       *
       * Returns: a newly created #GESTrackEffect, or %NULL if something went
       * wrong.
       */
     GESTrackEffect *ges_track_effect_new_from_material(GESTrackEffect *effect,
-                                                       GESMaterial *material);
+                                                   GESEffect *effect_material);
 
       /**
       * ges_track_effect_new_from_bin_desc:
@@ -256,6 +271,22 @@ C. Keyframes
                  to had an effect to a segment of the timeline without caring
                  bout what clip it is applied on.
 
+  E - The GESEffect:
+
+  The GESEffect class is a subclass of GESMaterial, it is used to describe 
+  effects independently of the usage which is made of it in the timeline.
+
+  A GESEffect can specify a GESTrackOperation class to use in a 
+  TimelineObject.
+
+  All important properties are inherited from GESMaterial such as:
+      * Name
+      * Description
+      * Tags
+      * ...
+
+  We should also be able to list properties of the effect from the GESMaterial.
+  
 =================
   TODO GESRegistry API:
       This should be a singleton since we don't want an app to instanciate more