From d99041221827d145ee7423b1043cdcd40b549ef0 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Thu, 6 Jul 2006 15:21:46 +0000 Subject: [PATCH] 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 | 9 +++++ gst/gstpad.c | 125 +++++++++++++++++++++++++++++++++++++++++------------------ gst/gstpad.h | 64 +++++++++++++++++++++++------- 3 files changed, 148 insertions(+), 50 deletions(-) diff --git a/ChangeLog b/ChangeLog index fe94638..40082cd 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,14 @@ 2006-07-06 Wim Taymans + * 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 + * gst/gstbus.h: * gst/gstclock.h: * gst/gstevent.h: diff --git a/gst/gstpad.c b/gst/gstpad.c index f01e9c0..fcfbeb9 100644 --- a/gst/gstpad.c +++ b/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(). - * - * Last reviewed on 2005-11-23 (0.9.5) + * To send a #GstEvent on a pad, use gst_pad_send_event() and + * gst_pad_push_event(). * + * 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 - * dispatch to activate_push or activate_pull to perform the actual activation. - * Only makes sense to set on sink pads. + * Sets the given activate function for @pad. The activate function will + * dispatch to gst_pad_activate_push() or gst_pad_activate_pull() to perform + * 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 - * return %NULL. + * produce a new #GstBuffer to start the processing pipeline. see + * #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. - * @buffer: the #GstBuffer to send. + * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not. + * @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. - * @buffer: the #GstBuffer to push. + * @pad: a source #GstPad, returns #GST_FLOW_ERROR if not. + * @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 - * the buffer. - * Buffer probes will be triggered before the buffer gets pushed. + * 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. + * + * 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. * @@ -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 - * sinkpad. + * Pulls a buffer from the peer pad. + * + * 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; diff --git a/gst/gstpad.h b/gst/gstpad.h index 1005ef0..8079ee6 100644 --- a/gst/gstpad.h +++ b/gst/gstpad.h @@ -211,27 +211,62 @@ typedef gboolean (*GstPadActivateModeFunction) (GstPad *pad, gboolean active); /* data passing */ /** * GstPadChainFunction: - * @pad: the #GstPad that performed the chain. - * @buffer: the #GstBuffer that is chained. + * @pad: the sink #GstPad that performed the chain. + * @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 - * 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 + * This function will be called on source pads when a peer element + * 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 * 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, -- 2.7.4