Commit d9904122 authored by Wim Taymans's avatar Wim Taymans
Browse files

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.
parent 15d8500f
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> 2006-07-06 Wim Taymans <wim@fluendo.com>
   
* gst/gstbus.h: * gst/gstbus.h:
......
...@@ -54,10 +54,10 @@ ...@@ -54,10 +54,10 @@
* GstElements will use gst_pad_push() and gst_pad_pull_range() to push out * GstElements will use gst_pad_push() and gst_pad_pull_range() to push out
* or pull in a buffer. * 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" #include "gst_private.h"
...@@ -1003,12 +1003,12 @@ gst_pad_is_blocked (GstPad * pad) ...@@ -1003,12 +1003,12 @@ gst_pad_is_blocked (GstPad * pad)
/** /**
* gst_pad_set_activate_function: * gst_pad_set_activate_function:
* @pad: a sink #GstPad. * @pad: a #GstPad.
* @activate: the #GstPadActivateFunction to set. * @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. * 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) ...@@ -1024,7 +1024,7 @@ gst_pad_set_activate_function (GstPad * pad, GstPadActivateFunction activate)
/** /**
* gst_pad_set_activatepull_function: * gst_pad_set_activatepull_function:
* @pad: a sink #GstPad. * @pad: a #GstPad.
* @activatepull: the #GstPadActivateModeFunction to set. * @activatepull: the #GstPadActivateModeFunction to set.
* *
* Sets the given activate_pull function for the pad. An activate_pull function * Sets the given activate_pull function for the pad. An activate_pull function
...@@ -1044,7 +1044,7 @@ gst_pad_set_activatepull_function (GstPad * pad, ...@@ -1044,7 +1044,7 @@ gst_pad_set_activatepull_function (GstPad * pad,
/** /**
* gst_pad_set_activatepush_function: * gst_pad_set_activatepush_function:
* @pad: a sink #GstPad. * @pad: a #GstPad.
* @activatepush: the #GstPadActivateModeFunction to set. * @activatepush: the #GstPadActivateModeFunction to set.
* *
* Sets the given activate_push function for the pad. An activate_push function * Sets the given activate_push function for the pad. An activate_push function
...@@ -1067,7 +1067,7 @@ gst_pad_set_activatepush_function (GstPad * pad, ...@@ -1067,7 +1067,7 @@ gst_pad_set_activatepush_function (GstPad * pad,
* @chain: the #GstPadChainFunction to set. * @chain: the #GstPadChainFunction to set.
* *
* Sets the given chain function for the pad. The chain function is called to * 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 void
gst_pad_set_chain_function (GstPad * pad, GstPadChainFunction chain) gst_pad_set_chain_function (GstPad * pad, GstPadChainFunction chain)
...@@ -1086,8 +1086,8 @@ 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. * @get: the #GstPadGetRangeFunction to set.
* *
* Sets the given getrange function for the pad. The getrange function is called to * 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 void
gst_pad_set_getrange_function (GstPad * pad, GstPadGetRangeFunction get) gst_pad_set_getrange_function (GstPad * pad, GstPadGetRangeFunction get)
...@@ -2628,13 +2628,12 @@ peer_error: ...@@ -2628,13 +2628,12 @@ peer_error:
* Allocates a new, empty buffer optimized to push to pad @pad. This * 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. * 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 * You need to check the caps of the buffer after performing this
* function and renegotiate to the format if needed. * 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 * 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. * not be used.
* An error can occur if the pad is not connected or when the downstream * An error can occur if the pad is not connected or when the downstream
* peer elements cannot provide an acceptable buffer. * peer elements cannot provide an acceptable buffer.
...@@ -2661,7 +2660,7 @@ gst_pad_alloc_buffer (GstPad * pad, guint64 offset, gint size, GstCaps * caps, ...@@ -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. * newly allocated buffer are different from the @pad caps.
* *
* Returns: a result code indicating success of the operation. Any * 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. * not be used.
* An error can occur if the pad is not connected or when the downstream * An error can occur if the pad is not connected or when the downstream
* peer elements cannot provide an acceptable buffer. * peer elements cannot provide an acceptable buffer.
...@@ -3225,6 +3224,9 @@ gst_pad_emit_have_data_signal (GstPad * pad, GstMiniObject * obj) ...@@ -3225,6 +3224,9 @@ gst_pad_emit_have_data_signal (GstPad * pad, GstMiniObject * obj)
return res; return res;
} }
/* this is the chain function that does not perform the additional argument
* checking for that little extra speed.
*/
static inline GstFlowReturn static inline GstFlowReturn
gst_pad_chain_unchecked (GstPad * pad, GstBuffer * buffer) gst_pad_chain_unchecked (GstPad * pad, GstBuffer * buffer)
{ {
...@@ -3317,17 +3319,32 @@ no_function: ...@@ -3317,17 +3319,32 @@ no_function:
("push on pad %s:%s but it has no chainfunction", ("push on pad %s:%s but it has no chainfunction",
GST_DEBUG_PAD_NAME (pad))); GST_DEBUG_PAD_NAME (pad)));
GST_PAD_STREAM_UNLOCK (pad); GST_PAD_STREAM_UNLOCK (pad);
return GST_FLOW_ERROR; return GST_FLOW_NOT_SUPPORTED;
} }
} }
/** /**
* gst_pad_chain: * 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. * 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. * Returns: a #GstFlowReturn from the pad.
* *
* MT safe. * MT safe.
...@@ -3338,7 +3355,6 @@ gst_pad_chain (GstPad * pad, GstBuffer * buffer) ...@@ -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_IS_PAD (pad), GST_FLOW_ERROR);
g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SINK, g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SINK,
GST_FLOW_ERROR); 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); g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
return gst_pad_chain_unchecked (pad, buffer); return gst_pad_chain_unchecked (pad, buffer);
...@@ -3346,12 +3362,25 @@ gst_pad_chain (GstPad * pad, GstBuffer * buffer) ...@@ -3346,12 +3362,25 @@ gst_pad_chain (GstPad * pad, GstBuffer * buffer)
/** /**
* gst_pad_push: * 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 function will call an installed pad block before triggering any
* installed pad probes.
* *
* Pushes a buffer to the peer of @pad. This gives away your reference to * If the caps on @buffer are different from the currently configured caps on
* the buffer. * @pad, this function will call any installed setcaps function on @pad (see
* Buffer probes will be triggered before the buffer gets pushed. * 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. * Returns: a #GstFlowReturn from the peer pad.
* *
...@@ -3368,13 +3397,12 @@ gst_pad_push (GstPad * pad, GstBuffer * buffer) ...@@ -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_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 (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); g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
GST_OBJECT_LOCK (pad); GST_OBJECT_LOCK (pad);
/* FIXME: this check can go away; pad_set_blocked could be implemented with /* 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))) while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
if ((ret = handle_pad_block (pad)) != GST_FLOW_OK) if ((ret = handle_pad_block (pad)) != GST_FLOW_OK)
goto flushed; goto flushed;
...@@ -3395,6 +3423,8 @@ gst_pad_push (GstPad * pad, GstBuffer * buffer) ...@@ -3395,6 +3423,8 @@ gst_pad_push (GstPad * pad, GstBuffer * buffer)
if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL)) if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
goto not_linked; goto not_linked;
/* take ref to peer pad before releasing the lock */
gst_object_ref (peer); gst_object_ref (peer);
/* Before pushing the buffer to the peer pad, ensure that caps /* Before pushing the buffer to the peer pad, ensure that caps
...@@ -3503,6 +3533,8 @@ gst_pad_check_pull_range (GstPad * pad) ...@@ -3503,6 +3533,8 @@ gst_pad_check_pull_range (GstPad * pad)
/* ERROR recovery here */ /* ERROR recovery here */
wrong_direction: wrong_direction:
{ {
GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
"checking pull range, but pad must be a sinkpad");
GST_OBJECT_UNLOCK (pad); GST_OBJECT_UNLOCK (pad);
return FALSE; return FALSE;
} }
...@@ -3517,12 +3549,18 @@ not_connected: ...@@ -3517,12 +3549,18 @@ not_connected:
/** /**
* gst_pad_get_range: * 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 * @offset: The start offset of the buffer
* @size: The length 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.
*
* When @pad is flushing this function returns #GST_FLOW_WRONG_STATE
* immediatly.
* *
* Calls the getrange function of @pad. * 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. * Returns: a #GstFlowReturn from the pad.
* *
...@@ -3585,11 +3623,12 @@ no_function: ...@@ -3585,11 +3623,12 @@ no_function:
("pullrange on pad %s:%s but it has no getrangefunction", ("pullrange on pad %s:%s but it has no getrangefunction",
GST_DEBUG_PAD_NAME (pad))); GST_DEBUG_PAD_NAME (pad)));
GST_PAD_STREAM_UNLOCK (pad); GST_PAD_STREAM_UNLOCK (pad);
return GST_FLOW_ERROR; return GST_FLOW_NOT_SUPPORTED;
} }
dropping: 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_PAD_STREAM_UNLOCK (pad);
gst_buffer_unref (*buffer); gst_buffer_unref (*buffer);
*buffer = NULL; *buffer = NULL;
...@@ -3600,15 +3639,26 @@ dropping: ...@@ -3600,15 +3639,26 @@ dropping:
/** /**
* gst_pad_pull_range: * 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 * @offset: The start offset of the buffer
* @size: The length 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. * 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. * MT safe.
*/ */
...@@ -3661,7 +3711,8 @@ not_connected: ...@@ -3661,7 +3711,8 @@ not_connected:
} }
dropping: 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); gst_buffer_unref (*buffer);
*buffer = NULL; *buffer = NULL;
return GST_FLOW_UNEXPECTED; return GST_FLOW_UNEXPECTED;
......
...@@ -211,27 +211,62 @@ typedef gboolean (*GstPadActivateModeFunction) (GstPad *pad, gboolean active); ...@@ -211,27 +211,62 @@ typedef gboolean (*GstPadActivateModeFunction) (GstPad *pad, gboolean active);
/* data passing */ /* data passing */
/** /**
* GstPadChainFunction: * 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. * 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); typedef GstFlowReturn (*GstPadChainFunction) (GstPad *pad, GstBuffer *buffer);
/** /**
* GstPadGetRangeFunction: * GstPadGetRangeFunction:
* @pad: the #GstPad to perform the getrange on. * @pad: the src #GstPad to perform the getrange on.
* @offset: the offset of the range * @offset: the offset of the range
* @length: the length 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. * 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, typedef GstFlowReturn (*GstPadGetRangeFunction) (GstPad *pad, guint64 offset,
guint length, GstBuffer **buffer); guint length, GstBuffer **buffer);
...@@ -383,15 +418,18 @@ typedef void (*GstPadFixateCapsFunction) (GstPad *pad, GstCaps *caps); ...@@ -383,15 +418,18 @@ typedef void (*GstPadFixateCapsFunction) (GstPad *pad, GstCaps *caps);
* provide a hardware buffer in order to avoid additional memcpy operations. * 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 * 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. * failed and @buf does not contain valid data.
* *
* By default this function returns a new buffer of @size and with @caps containing * 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. * value means @buf does not hold a valid buffer.
*/ */
typedef GstFlowReturn (*GstPadBufferAllocFunction) (GstPad *pad, guint64 offset, guint size, typedef GstFlowReturn (*GstPadBufferAllocFunction) (GstPad *pad, guint64 offset, guint size,
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment