Documentation updates

Original commit message from CVS:
Documentation updates
Make spider forward bufferpools
Remove some old registry code

gst/autoplug/gstspideridentity.c

@@ -128,17 +128,16 @@ gst_spider_identity_class_init (GstSpiderIdentityClass *klass)
   gstelement_class->change_state = GST_DEBUG_FUNCPTR(gst_spider_identity_change_state);
   gstelement_class->request_new_pad = GST_DEBUG_FUNCPTR(gst_spider_identity_request_new_pad);
 }
-/* defined but not used
+
 static GstBufferPool*
 gst_spider_identity_get_bufferpool (GstPad *pad)
-{*/
-  /* fix me */
-/*  GstSpiderIdentity *spider_identity;
+{
+  GstSpiderIdentity *ident;
 
-  spider_identity = GST_SPIDER_IDENTITY (gst_pad_get_parent (pad));
+  ident = GST_SPIDER_IDENTITY (gst_pad_get_parent (pad));
 
-  return gst_pad_get_bufferpool (spider_identity->src);
-}*/
+  return gst_pad_get_bufferpool (ident->src);
+}
 
 static void 
 gst_spider_identity_init (GstSpiderIdentity *ident) 
@@ -148,6 +147,7 @@ gst_spider_identity_init (GstSpiderIdentity *ident)
   gst_element_add_pad (GST_ELEMENT (ident), ident->sink);
   gst_pad_set_connect_function (ident->sink, GST_DEBUG_FUNCPTR (gst_spider_identity_connect));
   gst_pad_set_getcaps_function (ident->sink, GST_DEBUG_FUNCPTR (gst_spider_identity_getcaps));
+  gst_pad_set_bufferpool_function (ident->sink, GST_DEBUG_FUNCPTR (gst_spider_identity_get_bufferpool));
   /* src */
   ident->src = gst_pad_new_from_template (GST_PAD_TEMPLATE_GET (spider_src_factory), "src");
   gst_element_add_pad (GST_ELEMENT (ident), ident->src);
@@ -288,6 +288,7 @@ gst_spider_identity_request_new_pad  (GstElement *element, GstPadTemplate *templ
       gst_element_add_pad (GST_ELEMENT (ident), ident->sink);
       gst_pad_set_connect_function (ident->sink, GST_DEBUG_FUNCPTR (gst_spider_identity_connect));
       gst_pad_set_getcaps_function (ident->sink, GST_DEBUG_FUNCPTR (gst_spider_identity_getcaps));
+      gst_pad_set_bufferpool_function (ident->sink, GST_DEBUG_FUNCPTR (gst_spider_identity_get_bufferpool));
       return ident->sink;
     case GST_PAD_SRC:
       /* src */

gst/elements/gstfilesrc.c

@@ -453,7 +453,7 @@ gst_filesrc_get (GstPad *pad)
     src->seek_happened = FALSE;
     GST_DEBUG (GST_CAT_EVENT, "filesrc sending discont\n");
     event = gst_event_new_discontinuous (FALSE, GST_FORMAT_BYTES, src->curoffset, NULL);
-    GST_EVENT_DISCONT_FLUSH (event) = src->need_flush;
+    GST_EVENT_DISCONT_NEW_MEDIA (event) = FALSE;
     src->need_flush = FALSE;
     return GST_BUFFER (event);
   }

gst/gstcaps.h

@@ -97,7 +97,7 @@ void		gst_caps_destroy			(GstCaps *caps);
 void		gst_caps_debug				(GstCaps *caps, const gchar *label);
 
 GstCaps*	gst_caps_copy				(GstCaps *caps);
-GstCaps*	gst_caps_copy_first			(GstCaps *caps);
+GstCaps*	gst_caps_copy_1				(GstCaps *caps);
 GstCaps*	gst_caps_copy_on_write			(GstCaps *caps);
 
 const gchar*	gst_caps_get_name			(GstCaps *caps);

gst/gstclock.c

@@ -288,6 +288,17 @@ gst_clock_is_active (GstClock *clock)
   return clock->active;
 }
 
+/**
+ * gst_clock_handle_discont
+ * @clock: a #GstClock to notify of the discontinuity
+ * @time: The new time
+ *
+ * Notifies the clock of a discontinuity in time.
+ * 
+ * Returns: TRUE if the clock was updated. It is possible that
+ * the clock was not updated by this call because only the first
+ * discontinuitity in the pipeline is honoured.
+ */
 gboolean
 gst_clock_handle_discont (GstClock *clock, guint64 time)
 {
@@ -384,8 +395,12 @@ gst_clock_wait_async_func (GstClock *clock, GstClockTime time,
  * gst_clock_wait
  * @clock: a #GstClock to wait on
  * @time: The #GstClockTime to wait for
+ * @jitter: The jitter 
  *
  * Wait and block till the clock reaches the specified time.
+ * The jitter value contains the difference between the requested time and
+ * the actual time, negative values indicate that the requested time
+ * was allready passed when this call was made.
  *
  * Returns: the #GstClockReturn result of the operation.
  */
@@ -489,8 +504,10 @@ gst_clock_unlock_func (GstClock *clock, GstClockTime time, GstClockID id, gpoint
  * gst_clock_wait_id
  * @clock: The clock to wait on
  * @id: The clock id to wait on
+ * @jitter: The jitter 
  *
  * Wait and block on the clockid obtained with gst_clock_wait_async.
+ * The jitter value is described in gst_clock_wait().
  *
  * Returns: result of the operation.
  */

gst/gstelement.c

@@ -584,6 +584,14 @@ gst_element_request_pad (GstElement *element, GstPadTemplate *templ, const gchar
   return newpad;
 }
 
+/**
+ * gst_element_release_request_pad:
+ * @element: a #GstElement to release the request pad of
+ * @pad: The pad to release
+ *
+ * Make the element free the previously requested pad as obtained
+ * with gst_element_get_request_pad().
+ */
 void
 gst_element_release_request_pad (GstElement *element, GstPad *pad)
 {
@@ -713,6 +721,7 @@ gst_element_get_clock (GstElement *element)
  * @element: a #GstElement
  * @clock: the #GstClock to use
  * @time: the #GstClockTime to wait for on the clock
+ * @jitter: The difference between requested time and actual time
  *
  * Waits for a specific time on the clock.
  *
@@ -740,7 +749,7 @@ gst_element_clock_wait (GstElement *element, GstClock *clock, GstClockTime time,
  * gst_element_release_locks:
  * @element: an element 
  *
- * Instruct the element to release all the locks it is holding, ex
+ * Instruct the element to release all the locks it is holding, such as
  * blocking reads, waiting for the clock, ...
  *
  * Returns: TRUE if the locks could be released.
@@ -1125,7 +1134,7 @@ gst_element_get_pad_template (GstElement *element, const guchar *name)
 /**
  * gst_element_get_compatible_pad_template:
  * @element: element to get padtemplate of
- * @templ: a template to find a compatible template for
+ * @compattempl: a template to find a compatible template for
  *
  * Generate a padtemplate for this element compatible with the given
  * template, ie able to link to it.
@@ -1649,6 +1658,17 @@ gst_element_send_event_default (GstElement *element, GstEvent *event)
   return res;
 }
 
+/**
+ * gst_element_send_event:
+ * @element: The element to send the event to.
+ * @event: The event to send to the object.
+ *
+ * Sends an event to an element. If the element doesn't 
+ * implement an event handler, the event will be forwarded
+ * to a random sinkpad.
+ * 
+ * Returns: TRUE if the event was handled.
+ */
 gboolean
 gst_element_send_event (GstElement *element, GstEvent *event)
 {
@@ -1682,6 +1702,21 @@ gst_element_query_default (GstElement *element, GstPadQueryType type,
   return res;
 }
 
+/**
+ * gst_element_query:
+ * @element: The element to perform the query on.
+ * @type: The query type
+ * @format: a pointer to hold the format of the result
+ * @value: a pointer to the value of the result
+ *
+ * Perform a query on the given element. If the format is set
+ * to GST_FORMAT_DEFAULT and this function returns TRUE, the 
+ * format pointer will hold the default format.
+ * For element that don't implement a query handler, this function
+ * forwards the query to a random connected sinkpad of this element.
+ * 
+ * Returns: TRUE if the query could be performed.
+ */
 gboolean
 gst_element_query (GstElement *element, GstPadQueryType type,
 		   GstFormat *format, gint64 *value)
@@ -1696,8 +1731,6 @@ gst_element_query (GstElement *element, GstPadQueryType type,
   return FALSE;
 }
 
-
-
 /**
  * gst_element_error:
  * @element: Element with the error

gst/gstevent.c

@@ -149,7 +149,6 @@ gst_event_free (GstEvent* event)
  * gst_event_new_seek:
  * @type: The type of the seek event
  * @offset: The offset of the seek
- * @flush: A boolean indicating a flush has to be performed as well
  *
  * Allocate a new seek event with the given parameters.
  *
@@ -167,15 +166,25 @@ gst_event_new_seek (GstSeekType type, gint64 offset)
   return event;
 }
 
+/**
+ * gst_event_new_discontinuous:
+ * @new_media: A flag indicating a new media type starts
+ * @format1: The format of the discont value
+ * @...: more discont values and formats
+ *
+ * Allocate a new discontinuous event with the geven format/value pairs.
+ *
+ * Returns: A new discontinuous event.
+ */
 GstEvent*
-gst_event_new_discontinuous (gboolean flush, GstSeekType format1, ...)
+gst_event_new_discontinuous (gboolean new_media, GstSeekType format1, ...)
 {
   va_list var_args;
   GstEvent *event;
   gint count = 0;
 
   event = gst_event_new (GST_EVENT_DISCONTINUOUS);
-  GST_EVENT_DISCONT_FLUSH (event) = flush;
+  GST_EVENT_DISCONT_NEW_MEDIA (event) = new_media;
 
   va_start (var_args, format1);
 	        
@@ -195,8 +204,18 @@ gst_event_new_discontinuous (gboolean flush, GstSeekType format1, ...)
   return event;
 }
 
+/**
+ * gst_event_discont_get_value:
+ * @event: The event to query
+ * @format: The format of the discont value
+ * @value: A pointer to the value
+ *
+ * Get the value for the given format in the dicont event.
+ *
+ * Returns: TRUE if the discont event caries the specified format/value pair.
+ */
 gboolean
-gst_event_discont_get_value (GstEvent *event, GstSeekType type, gint64 *value)
+gst_event_discont_get_value (GstEvent *event, GstFormat format, gint64 *value)
 {
   gint i, n;
 
@@ -206,7 +225,7 @@ gst_event_discont_get_value (GstEvent *event, GstSeekType type, gint64 *value)
   n = GST_EVENT_DISCONT_OFFSET_LEN (event);
 
   for (i = 0; i < n; i++) {
-    if (GST_EVENT_DISCONT_OFFSET(event,i).format == type) {
+    if (GST_EVENT_DISCONT_OFFSET(event,i).format == format) {
       *value = GST_EVENT_DISCONT_OFFSET(event,i).value;
       return TRUE;
     }

gst/gstevent.h

@@ -89,7 +89,7 @@ typedef struct
 #define GST_EVENT_SEEK_OFFSET(event)		(GST_EVENT(event)->event_data.seek.offset)
 #define GST_EVENT_SEEK_ACCURACY(event)		(GST_EVENT(event)->event_data.seek.accuracy)
 
-#define GST_EVENT_DISCONT_FLUSH(event)		(GST_EVENT(event)->event_data.discont.flush)
+#define GST_EVENT_DISCONT_NEW_MEDIA(event)	(GST_EVENT(event)->event_data.discont.new_media)
 #define GST_EVENT_DISCONT_OFFSET(event,i)	(GST_EVENT(event)->event_data.discont.offsets[i])
 #define GST_EVENT_DISCONT_OFFSET_LEN(event)	(GST_EVENT(event)->event_data.discont.noffsets)
 
@@ -109,7 +109,7 @@ struct _GstEvent {
     struct {
       GstFormatValue 	offsets[8];
       gint      	noffsets;
-      gboolean		flush;
+      gboolean		new_media;
     } discont;
   } event_data;
 };

gst/gstpad.c

@@ -502,6 +502,23 @@ gst_pad_set_query_function (GstPad *pad, GstPadQueryFunction query)
              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (query));
 }
 
+/**
+ * gst_pad_set_internal_connection_function:
+ * @pad: the pad to set the internal connection function for
+ * @intconn: the internal connection function
+ *
+ * Set the given internal connection function for the pad.
+ */
+void
+gst_pad_set_internal_connection_function (GstPad *pad, GstPadIntConnFunction intconn)
+{
+  g_return_if_fail (pad != NULL);
+  g_return_if_fail (GST_IS_REAL_PAD (pad));
+
+  GST_RPAD_INTCONNFUNC(pad) = intconn;
+  GST_DEBUG (GST_CAT_PADS, "internal connection for %s:%s  set to %s",
+             GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (intconn));
+}
 
 /**
  * gst_pad_set_connect_function:

gst/gstparse.c

@@ -439,10 +439,12 @@ pipeline_from_graph (graph_t *g, GError **error)
 /**
  * gst_parse_launchv:
  * @argv: null-terminated array of arguments
+ * @error: pointer to GError
  *
  * Create a new pipeline based on command line syntax.
  *
- * Returns: a new pipeline on success, NULL on failure
+ * Returns: a new pipeline on success, NULL on failure and error
+ * will contain the error message.
  */
 GstBin *
 gst_parse_launchv (const gchar **argv, GError **error)
@@ -511,6 +513,7 @@ void _gst_parse_unescape (gchar *str)
 /**
  * gst_parse_launch:
  * @pipeline_description: the command line describing the pipeline
+ * @error: the error message in case of a failure
  *
  * Create a new pipeline based on command line syntax.
  *

gst/gstplugin.c

@@ -116,6 +116,14 @@ gst_plugin_register_func (GstPluginDesc *desc, GstPlugin *plugin, GModule *modul
   return plugin;
 }
 
+/**
+ * gst_plugin_new:
+ * @filename: The filename of the plugin
+ *
+ * Creates a plugin from the given filename
+ *
+ * Returns: A new GstPlugin object
+ */
 GstPlugin*
 gst_plugin_new (const gchar *filename)
 {
@@ -331,6 +339,16 @@ gst_plugin_is_loaded (GstPlugin *plugin)
   return (plugin->module != NULL);
 }
 
+/**
+ * gst_plugin_find_feature:
+ * @plugin: plugin to get the feature from
+ * @name: The name of the feature to find
+ * @type: The type of the feature to find
+ *
+ * Find a feature of the given name and type in the given plugin.
+ *
+ * Returns: a GstPluginFeature or NULL if the feature was not found.
+ */
 GstPluginFeature*
 gst_plugin_find_feature (GstPlugin *plugin, const gchar *name, GType type)
 {

gst/gstregistry.c

@@ -194,6 +194,7 @@ gst_registry_unload (GstRegistry *registry)
 /**
  * gst_registry_add_path:
  * @registry: the registry to add the path to
+ * @path: the path to add to the registry 
  *
  * Add the given path to the registry. The syntax of the
  * path is specific to the registry. If the path has already been
@@ -664,119 +665,3 @@ gst_registry_pool_get_prefered (GstRegistryFlags flags)
   return NULL;
 }
 
-
-
-static gchar *gst_registry_option = NULL;
-
-/* save the registry specified as an option */
-void
-gst_registry_option_set (const gchar *registry)
-{
-  gst_registry_option = g_strdup (registry);
-  return;
-}
-
-/* decide if we're going to use the global registry or not 
- * - if root, use global
- * - if not root :
- *   - if user can write to global, use global
- *   - else use local
- */
-gboolean
-gst_registry_use_global (void)
-{
-  /* struct stat reg_stat; */
-  FILE *reg;
-  
-  if (getuid () == 0) return TRUE; 	/* root always uses global */
-
-  /* check if we can write to the global registry somehow */
-  reg = fopen (GLOBAL_REGISTRY_FILE, "a");
-  if (reg == NULL) { return FALSE; }
-  else
-  {
-    /* we can write to it, do so for kicks */
-    fclose (reg);
-  }
-  
-  /* we can write to it, so now see if we can write in the dir as well */ 
-  if (access (GLOBAL_REGISTRY_DIR, W_OK) == 0) return TRUE;
-
-  return FALSE;
-}
-
-/* get the data that tells us where we can write the registry
- * Allocate, fill in the GstRegistryWrite struct according to 
- * current situation, and return it */
-GstRegistryWrite *
-gst_registry_write_get ()
-{
-  GstRegistryWrite *gst_reg = g_malloc (sizeof (GstRegistryWrite));
-  
-  /* if a registry is specified on command line, use that one */
-  if (gst_registry_option)
-  {
-    /* FIXME: maybe parse the dir from file ? */
-    gst_reg->dir = NULL;
-    gst_reg->file = gst_registry_option;
-    /* we cannot use the temp dir since the move needs to be on same device */
-    gst_reg->tmp_file = g_strdup_printf ("%s.tmp", gst_registry_option);
-  }
-  else if (g_getenv ("GST_REGISTRY"))
-  {
-    gst_reg->dir = NULL;
-    gst_reg->file = g_strdup (g_getenv ("GST_REGISTRY"));
-    gst_reg->tmp_file = g_strdup_printf ("%s.tmp", g_getenv ("GST_REGISTRY"));
-  }
-  else
-  {
-    if (gst_registry_use_global ())
-    {
-      gst_reg->dir      = g_strdup (GLOBAL_REGISTRY_DIR);
-      gst_reg->file     = g_strdup (GLOBAL_REGISTRY_FILE);
-      gst_reg->tmp_file = g_strdup (GLOBAL_REGISTRY_FILE_TMP);
-    }
-    else
-    {
-      gchar *homedir = (gchar *) g_get_home_dir ();
-      
-      gst_reg->dir = g_strjoin ("/", homedir, LOCAL_REGISTRY_DIR, NULL);
-      gst_reg->file = g_strjoin ("/", homedir, LOCAL_REGISTRY_FILE, NULL);
-      gst_reg->tmp_file = g_strjoin ("/", homedir, LOCAL_REGISTRY_FILE_TMP, NULL);
-    }
-  } 
-  return gst_reg;
-}
-
-/* fill in the GstRegistryRead struct according to current situation */
-GstRegistryRead *
-gst_registry_read_get ()
-{
-  GstRegistryRead *gst_reg = g_new0 (GstRegistryRead, 1);
-  
-  /* if a registry is specified on command line, use that one */
-  if (gst_registry_option)
-  {
-    /* FIXME: maybe parse the dir from file ? */
-    gst_reg->local_reg = NULL;
-    gst_reg->global_reg = gst_registry_option;
-  } 
-  else if (g_getenv ("GST_REGISTRY"))
-  {
-    gst_reg->local_reg = NULL;
-    gst_reg->global_reg = g_strdup (g_getenv ("GST_REGISTRY"));
-  }
-  else
-  {
-    gchar *homedir = (gchar *) g_get_home_dir ();
-    gst_reg->local_reg = g_strjoin ("/", homedir, LOCAL_REGISTRY_FILE, NULL);
-    if (g_file_test (gst_reg->local_reg, G_FILE_TEST_EXISTS) == FALSE)
-    {
-      /* it does not exist, so don't read from it */
-      g_free (gst_reg->local_reg);
-      gst_reg->local_reg = NULL;
-    }
-    gst_reg->global_reg = g_strdup (GLOBAL_REGISTRY_FILE);
-  }
-  return gst_reg;
-}

gst/gstregistry.h

@@ -45,24 +45,6 @@
 
 G_BEGIN_DECLS
 
-typedef struct _GstRegistryWrite GstRegistryWrite;
-struct _GstRegistryWrite {
-  gchar *dir;
-  gchar *file;
-  gchar *tmp_file;
-};
-
-typedef struct _GstRegistryRead GstRegistryRead;
-struct _GstRegistryRead {
-  gchar *global_reg;
-  gchar *local_reg;
-};
-
-GstRegistryWrite 	*gst_registry_write_get  	(void);
-GstRegistryRead 	*gst_registry_read_get  	(void);
-void 			gst_registry_option_set 	(const gchar *registry);
-
-
 typedef enum {
   GST_REGISTRY_OK			= (0),
   GST_REGISTRY_LOAD_ERROR		= (1 << 1),

gst/gstscheduler.c

@@ -549,6 +549,7 @@ gst_scheduler_auto_clock (GstScheduler *sched)
  * @element: the element that wants to wait
  * @clock: the clock to use
  * @time: the time to wait for
+ * @jitter: the time difference between requested time and actual time
  *
  * Wait till the clock reaches a specific time
  *

plugins/elements/gstfilesrc.c

@@ -453,7 +453,7 @@ gst_filesrc_get (GstPad *pad)
     src->seek_happened = FALSE;
     GST_DEBUG (GST_CAT_EVENT, "filesrc sending discont\n");
     event = gst_event_new_discontinuous (FALSE, GST_FORMAT_BYTES, src->curoffset, NULL);
-    GST_EVENT_DISCONT_FLUSH (event) = src->need_flush;
+    GST_EVENT_DISCONT_NEW_MEDIA (event) = FALSE;
     src->need_flush = FALSE;
     return GST_BUFFER (event);
   }