gst/gstpad.*: Lots of comments and docs added to the pad functions.

Original commit message from CVS:
* gst/gstpad.c: (gst_pad_chain_unchecked), (gst_pad_chain),
(gst_pad_push), (gst_pad_check_pull_range), (gst_pad_get_range),
(gst_pad_pull_range):
* gst/gstpad.h:
Lots of comments and docs added to the pad functions.
Flesh out the expected behaviour of the get_range() functions.

ChangeLog

@@ -1,3 +1,12 @@
+2006-07-06  Wim Taymans  <wim@fluendo.com>
+
+	* gst/gstpad.c: (gst_pad_chain_unchecked), (gst_pad_chain),
+	(gst_pad_push), (gst_pad_check_pull_range), (gst_pad_get_range),
+	(gst_pad_pull_range):
+	* gst/gstpad.h:
+	Lots of comments and docs added to the pad functions.
+	Flesh out the expected behaviour of the get_range() functions.
+
 2006-07-06  Wim Taymans  <wim@fluendo.com>
 
 	* gst/gstbus.h:

gst/gstpad.c

@@ -54,10 +54,10 @@
  * GstElements will use gst_pad_push() and gst_pad_pull_range() to push out
  * or pull in a buffer.
  *
- * To send a #GstEvent on a pad, use gst_pad_send_event().
+ * To send a #GstEvent on a pad, use gst_pad_send_event() and
- *
+ * gst_pad_push_event().
- * Last reviewed on 2005-11-23 (0.9.5)
  *
+ * Last reviewed on 2006-07-06 (0.10.9)
  */
 
 #include "gst_private.h"
@@ -1003,12 +1003,12 @@ gst_pad_is_blocked (GstPad * pad)
 
 /**
  * gst_pad_set_activate_function:
- * @pad: a sink #GstPad.
+ * @pad: a #GstPad.
  * @activate: the #GstPadActivateFunction to set.
  *
- * Sets the given activate function for the pad. The activate function will
+ * Sets the given activate function for @pad. The activate function will
- * dispatch to activate_push or activate_pull to perform the actual activation.
+ * dispatch to gst_pad_activate_push() or gst_pad_activate_pull() to perform
- * Only makes sense to set on sink pads.
+ * the actual activation. Only makes sense to set on sink pads.
  *
  * Call this function if your sink pad can start a pull-based task.
  */
@@ -1024,7 +1024,7 @@ gst_pad_set_activate_function (GstPad * pad, GstPadActivateFunction activate)
 
 /**
  * gst_pad_set_activatepull_function:
- * @pad: a sink #GstPad.
+ * @pad: a #GstPad.
  * @activatepull: the #GstPadActivateModeFunction to set.
  *
  * Sets the given activate_pull function for the pad. An activate_pull function
@@ -1044,7 +1044,7 @@ gst_pad_set_activatepull_function (GstPad * pad,
 
 /**
  * gst_pad_set_activatepush_function:
- * @pad: a sink #GstPad.
+ * @pad: a #GstPad.
  * @activatepush: the #GstPadActivateModeFunction to set.
  *
  * Sets the given activate_push function for the pad. An activate_push function
@@ -1067,7 +1067,7 @@ gst_pad_set_activatepush_function (GstPad * pad,
  * @chain: the #GstPadChainFunction to set.
  *
  * Sets the given chain function for the pad. The chain function is called to
- * process a #GstBuffer input buffer.
+ * process a #GstBuffer input buffer. see #GstPadChainFunction for more details.
  */
 void
 gst_pad_set_chain_function (GstPad * pad, GstPadChainFunction chain)
@@ -1086,8 +1086,8 @@ gst_pad_set_chain_function (GstPad * pad, GstPadChainFunction chain)
  * @get: the #GstPadGetRangeFunction to set.
  *
  * Sets the given getrange function for the pad. The getrange function is called to
- * produce a new #GstBuffer to start the processing pipeline. Getrange functions cannot
+ * produce a new #GstBuffer to start the processing pipeline. see
- * return %NULL.
+ * #GstPadGetRangeFunction for a description of the getrange function.
  */
 void
 gst_pad_set_getrange_function (GstPad * pad, GstPadGetRangeFunction get)
@@ -2628,13 +2628,12 @@ peer_error:
  * Allocates a new, empty buffer optimized to push to pad @pad.  This
  * function only works if @pad is a source pad and has a peer.
  *
+ * A new, empty #GstBuffer will be put in the @buf argument.
  * You need to check the caps of the buffer after performing this
  * function and renegotiate to the format if needed.
  *
- * A new, empty #GstBuffer will be put in the @buf argument.
- *
  * Returns: a result code indicating success of the operation. Any
- * result code other than GST_FLOW_OK is an error and @buf should
+ * result code other than #GST_FLOW_OK is an error and @buf should
  * not be used.
  * An error can occur if the pad is not connected or when the downstream
  * peer elements cannot provide an acceptable buffer.
@@ -2661,7 +2660,7 @@ gst_pad_alloc_buffer (GstPad * pad, guint64 offset, gint size, GstCaps * caps,
  * newly allocated buffer are different from the @pad caps.
  *
  * Returns: a result code indicating success of the operation. Any
- * result code other than GST_FLOW_OK is an error and @buf should
+ * result code other than #GST_FLOW_OK is an error and @buf should
  * not be used.
  * An error can occur if the pad is not connected or when the downstream
  * peer elements cannot provide an acceptable buffer.
@@ -3225,6 +3224,9 @@ gst_pad_emit_have_data_signal (GstPad * pad, GstMiniObject * obj)
   return res;
 }
 
+/* this is the chain function that does not perform the additional argument
+ * checking for that little extra speed.
+ */
 static inline GstFlowReturn
 gst_pad_chain_unchecked (GstPad * pad, GstBuffer * buffer)
 {
@@ -3317,17 +3319,32 @@ no_function:
         ("push on pad %s:%s but it has no chainfunction",
             GST_DEBUG_PAD_NAME (pad)));
     GST_PAD_STREAM_UNLOCK (pad);
-    return GST_FLOW_ERROR;
+    return GST_FLOW_NOT_SUPPORTED;
   }
 }
 
 /**
  * gst_pad_chain:
- * @pad: a sink #GstPad.
+ * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
- * @buffer: the #GstBuffer to send.
+ * @buffer: the #GstBuffer to send, return GST_FLOW_ERROR if not.
  *
  * Chain a buffer to @pad.
  *
+ * The function returns #GST_FLOW_WRONG_STATE if the pad was flushing.
+ *
+ * If the caps on @buffer are different from the current caps on @pad, this
+ * function will call any setcaps function (see gst_pad_set_setcaps_function())
+ * installed on @pad. If the new caps are not acceptable for @pad, this function
+ * returns #GST_FLOW_NOT_NEGOTIATED.
+ *
+ * The function proceeds calling the chain function installed on @pad (see
+ * gst_pad_set_chain_function()) and the return value of that function is
+ * returned to the caller. #GST_FLOW_NOT_SUPPORTED is returned if @pad has no
+ * chain function.
+ *
+ * In all cases, success or failure, the caller loses its reference to @buffer
+ * after calling this function.
+ *
  * Returns: a #GstFlowReturn from the pad.
  *
  * MT safe.
@@ -3338,7 +3355,6 @@ gst_pad_chain (GstPad * pad, GstBuffer * buffer)
   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SINK,
       GST_FLOW_ERROR);
-  g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
   g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
 
   return gst_pad_chain_unchecked (pad, buffer);
@@ -3346,12 +3362,25 @@ gst_pad_chain (GstPad * pad, GstBuffer * buffer)
 
 /**
  * gst_pad_push:
- * @pad: a source #GstPad.
+ * @pad: a source #GstPad, returns #GST_FLOW_ERROR if not.
- * @buffer: the #GstBuffer to push.
+ * @buffer: the #GstBuffer to push returns GST_FLOW_ERROR if not.
  *
- * Pushes a buffer to the peer of @pad.  This gives away your reference to
+ * Pushes a buffer to the peer of @pad.
- * the buffer.
+ *
- * Buffer probes will be triggered before the buffer gets pushed.
+ * This function will call an installed pad block before triggering any
+ * installed pad probes.
+ *
+ * If the caps on @buffer are different from the currently configured caps on
+ * @pad, this function will call any installed setcaps function on @pad (see
+ * gst_pad_set_setcaps_function()). In case of failure to renegotiate the new
+ * format, this function returns #GST_FLOW_NOT_NEGOTIATED.
+ *
+ * The function proceeds calling gst_pad_chain() on the peer pad and returns the
+ * value from that function. If @pad has no peer, #GST_FLOW_NOT_LINKED will be
+ * returned.
+ *
+ * In all cases, success or failure, the caller loses its reference to @buffer
+ * after calling this function.
  *
  * Returns: a #GstFlowReturn from the peer pad.
  *
@@ -3368,13 +3397,12 @@ gst_pad_push (GstPad * pad, GstBuffer * buffer)
 
   g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SRC, GST_FLOW_ERROR);
-  g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
   g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
 
   GST_OBJECT_LOCK (pad);
 
   /* FIXME: this check can go away; pad_set_blocked could be implemented with
-   * probes completely */
+   * probes completely or probes with an extended pad block. */
   while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
     if ((ret = handle_pad_block (pad)) != GST_FLOW_OK)
       goto flushed;
@@ -3395,6 +3423,8 @@ gst_pad_push (GstPad * pad, GstBuffer * buffer)
 
   if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
     goto not_linked;
+
+  /* take ref to peer pad before releasing the lock */
   gst_object_ref (peer);
 
   /* Before pushing the buffer to the peer pad, ensure that caps 
@@ -3503,6 +3533,8 @@ gst_pad_check_pull_range (GstPad * pad)
   /* ERROR recovery here */
 wrong_direction:
   {
+    GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
+        "checking pull range, but pad must be a sinkpad");
     GST_OBJECT_UNLOCK (pad);
     return FALSE;
   }
@@ -3517,12 +3549,18 @@ not_connected:
 
 /**
  * gst_pad_get_range:
- * @pad: a src #GstPad.
+ * @pad: a src #GstPad, returns #GST_FLOW_ERROR if not.
  * @offset: The start offset of the buffer
  * @size: The length of the buffer
- * @buffer: a pointer to hold the #GstBuffer.
+ * @buffer: a pointer to hold the #GstBuffer, returns #GST_FLOW_ERROR if %NULL.
  *
- * Calls the getrange function of @pad.
+ * When @pad is flushing this function returns #GST_FLOW_WRONG_STATE
+ * immediatly.
+ *
+ * Calls the getrange function of @pad, see #GstPadGetRangeFunction for a
+ * description of a getrange function. If @pad has no getrange function
+ * installed (see gst_pad_set_getrange_function()) this function returns
+ * #GST_FLOW_NOT_SUPPORTED.
  *
  * Returns: a #GstFlowReturn from the pad.
  *
@@ -3585,11 +3623,12 @@ no_function:
         ("pullrange on pad %s:%s but it has no getrangefunction",
             GST_DEBUG_PAD_NAME (pad)));
     GST_PAD_STREAM_UNLOCK (pad);
-    return GST_FLOW_ERROR;
+    return GST_FLOW_NOT_SUPPORTED;
   }
 dropping:
   {
-    GST_DEBUG ("Dropping data after FALSE probe return");
+    GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
+        "Dropping data after FALSE probe return");
     GST_PAD_STREAM_UNLOCK (pad);
     gst_buffer_unref (*buffer);
     *buffer = NULL;
@@ -3600,15 +3639,26 @@ dropping:
 
 /**
  * gst_pad_pull_range:
- * @pad: a sink #GstPad.
+ * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
  * @offset: The start offset of the buffer
  * @size: The length of the buffer
- * @buffer: a pointer to hold the #GstBuffer.
+ * @buffer: a pointer to hold the #GstBuffer, returns GST_FLOW_ERROR if %NULL.
  *
- * Pulls a buffer from the peer pad. @pad must be a linked
+ * Pulls a buffer from the peer pad. 
- * sinkpad.
+ *
+ * This function will first trigger the pad block signal if it was 
+ * installed.
+ *
+ * When @pad is not linked #GST_FLOW_NOT_LINKED is returned else this
+ * function returns the result of gst_pad_get_range() on the peer pad.
+ * See gst_pad_get_range() for a list of return values and for the
+ * semantics of the arguments of this function.
  *
  * Returns: a #GstFlowReturn from the peer pad.
+ * When this function returns #GST_FLOW_OK, @buffer will contain a valid
+ * #GstBuffer that should be freed with gst_buffer_unref() after usage.
+ * @buffer may not be used or freed when any other return value than 
+ * #GST_FLOW_OK is returned.
  *
  * MT safe.
  */
@@ -3661,7 +3711,8 @@ not_connected:
   }
 dropping:
   {
-    GST_DEBUG ("Dropping data after FALSE probe return");
+    GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
+        "Dropping data after FALSE probe return");
     gst_buffer_unref (*buffer);
     *buffer = NULL;
     return GST_FLOW_UNEXPECTED;

gst/gstpad.h

@@ -211,27 +211,62 @@ typedef gboolean		(*GstPadActivateModeFunction)	(GstPad *pad, gboolean active);
 /* data passing */
 /**
  * GstPadChainFunction:
- * @pad: the #GstPad that performed the chain.
+ * @pad: the sink #GstPad that performed the chain.
- * @buffer: the #GstBuffer that is chained.
+ * @buffer: the #GstBuffer that is chained, not %NULL.
  *
  * A function that will be called on sinkpads when chaining buffers.
+ * The function typically processes the data contained in the buffer and 
+ * either consumes the data or passes it on to the internally linked pad(s).
  *
- * Returns: GST_FLOW_OK for success
+ * The implementer of this function receives a refcount to @buffer and should
+ * gst_buffer_unref() when the buffer is no longer needed.
+ *
+ * When a chain function detects an error in the data stream, it must post an
+ * error on the buffer and return an appropriate #GstFlowReturn value.
+ *
+ * Returns: #GST_FLOW_OK for success
  */
 typedef GstFlowReturn		(*GstPadChainFunction)		(GstPad *pad, GstBuffer *buffer);
 /**
  * GstPadGetRangeFunction:
- * @pad: the #GstPad to perform the getrange on.
+ * @pad: the src #GstPad to perform the getrange on.
  * @offset: the offset of the range
  * @length: the length of the range
- * @buffer: a memory location to hold the result buffer
+ * @buffer: a memory location to hold the result buffer, cannot be NULL.
  *
- * This function will be called on sourcepads when a peer element
+ * This function will be called on source pads when a peer element
- * request a buffer at the specified offset and length. If this function
+ * request a buffer at the specified @offset and @length. If this function
- * returns GST_FLOW_OK, the result buffer will be stored in @buffer. The 
+ * returns #GST_FLOW_OK, the result buffer will be stored in @buffer. The 
  * contents of @buffer is invalid for any other return value.
  *
- * Returns: GST_FLOW_OK for success
+ * This function is installed on a source pad with
+ * gst_pad_set_getrange_function() and can only be called on source pads after 
+ * they are successfully activated with gst_pad_activate_pull().
+ *
+ * @offset and @length are always given in byte units. @offset must normally be a value
+ * between 0 and the length in bytes of the data available on @pad. The
+ * length (duration in bytes) can be retrieved with a #GST_QUERY_DURATION or with a
+ * #GST_QUERY_SEEKING. 
+ *
+ * Any @offset larger or equal than the length will make the function return
+ * #GST_FLOW_UNEXPECTED, which corresponds to EOS. In this case @buffer does not
+ * contain a valid buffer.
+ *
+ * The buffer size of @buffer might be smaller than @length when @offset is near
+ * the end of the stream.
+ *
+ * It is allowed to call this function with a 0 @length and valid @offset, in 
+ * which case @buffer will contain a 0-sized buffer and the function returns
+ * #GST_FLOW_OK.
+ *
+ * When this function is called with a -1 @offset, the sequentially next buffer
+ * of length @length in the stream is returned. 
+ *
+ * When this function is called with a -1 @length, a buffer with a default
+ * optimal length is returned in @buffer. The length might depend on the value
+ * of @offset.
+ *
+ * Returns: #GST_FLOW_OK for success
  */
 typedef GstFlowReturn		(*GstPadGetRangeFunction)	(GstPad *pad, guint64 offset,
 		                                                 guint length, GstBuffer **buffer);
@@ -383,15 +418,18 @@ typedef void			(*GstPadFixateCapsFunction)	(GstPad *pad, GstCaps *caps);
  * provide a hardware buffer in order to avoid additional memcpy operations.
  *
  * The function can return a buffer that does not have @caps, in which case the
- * upstream element requests a format change. 
+ * upstream element requests a format change. If a format change was requested,
+ * the returned buffer will be one to hold the data of said new caps, so its
+ * size might be different from @size.
  *
- * When this function returns anything else than GST_FLOW_OK, the buffer allocation
+ * When this function returns anything else than #GST_FLOW_OK, the buffer allocation
  * failed and @buf does not contain valid data.
  *
  * By default this function returns a new buffer of @size and with @caps containing
- * purely malloced data.
+ * purely malloced data. The buffer should be freed with gst_buffer_unref()
+ * after usage.
  *
- * Returns: GST_FLOW_OK if @buf contains a valid buffer, any other return
+ * Returns: #GST_FLOW_OK if @buf contains a valid buffer, any other return
  *  value means @buf does not hold a valid buffer.
  */
 typedef GstFlowReturn		(*GstPadBufferAllocFunction)	(GstPad *pad, guint64 offset, guint size,