mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2025-01-22 15:18:21 +00:00
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.
This commit is contained in:
Wim Taymans
parent
15d8500f57
commit
d990412218
3 changed files with 148 additions and 50 deletions
|
|
@ -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:
|
||||
|
|
|
|||
125
gst/gstpad.c
125
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 gives away your reference to
|
||||
* the buffer.
|
||||
* Buffer probes will be triggered before the buffer gets pushed.
|
||||
* Pushes a buffer to the peer of @pad.
|
||||
*
|
||||
* 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
|
||||
* 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;
|
||||
|
|
|
|||
62
gst/gstpad.h
62
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 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
|
||||
* 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,
|
||||
|
|
|
|||
Loading…
Reference in a new issue