From 6e4fde7195ec12495494c8270aa475b5ce824967 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Wed, 5 May 2010 12:01:50 +0200 Subject: [PATCH] docs: clarify the pull_range functions Clarify the gst_pad_pull_range(), GstBaseSrc::create(), gst_pad_get_range() and GstPadGetRange functions a little. Fixes #617733 --- gst/gstpad.c | 2 +- gst/gstpad.h | 8 +++++--- libs/gst/base/gstbasesrc.h | 10 +++++++++- 3 files changed, 15 insertions(+), 5 deletions(-) diff --git a/gst/gstpad.c b/gst/gstpad.c index 17fc0cc..00dca74 100644 --- a/gst/gstpad.c +++ b/gst/gstpad.c @@ -4588,7 +4588,7 @@ not_connected: * @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. + * immediatly and @buffer is %NULL. * * Calls the getrange function of @pad, see #GstPadGetRangeFunction for a * description of a getrange function. If @pad has no getrange function diff --git a/gst/gstpad.h b/gst/gstpad.h index 9fc5568..56e4320 100644 --- a/gst/gstpad.h +++ b/gst/gstpad.h @@ -291,8 +291,9 @@ typedef GstFlowReturn (*GstPadChainListFunction) (GstPad *pad, GstBufferList *l * #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. + * The buffer size of @buffer will only be smaller than @length when @offset is + * near the end of the stream. In all other cases, the size of @buffer must be + * exactly the requested size. * * 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 @@ -305,7 +306,8 @@ typedef GstFlowReturn (*GstPadChainListFunction) (GstPad *pad, GstBufferList *l * optimal length is returned in @buffer. The length might depend on the value * of @offset. * - * Returns: #GST_FLOW_OK for success + * Returns: #GST_FLOW_OK for success and a valid buffer in @buffer. Any other + * return value leaves @buffer undefined. */ typedef GstFlowReturn (*GstPadGetRangeFunction) (GstPad *pad, guint64 offset, guint length, GstBuffer **buffer); diff --git a/libs/gst/base/gstbasesrc.h b/libs/gst/base/gstbasesrc.h index d9f39d9..854cf6b 100644 --- a/libs/gst/base/gstbasesrc.h +++ b/libs/gst/base/gstbasesrc.h @@ -132,11 +132,19 @@ struct _GstBaseSrc { * @get_size: Return the total size of the resource, in the configured format. * @is_seekable: Check if the source can seek * @unlock: Unlock any pending access to the resource. Subclasses should - * unblock any blocked function ASAP + * unblock any blocked function ASAP. In particular, any create() function in + * progress should be unblocked and should return GST_FLOW_WRONG_STATE. Any + * future create() function call should also return GST_FLOW_WRONG_STATE + * until the unlock_stop() function has been called. * @unlock_stop: Clear the previous unlock request. Subclasses should clear * any state they set during unlock(), such as clearing command queues. * @event: Override this to implement custom event handling. * @create: Ask the subclass to create a buffer with offset and size. + * When the subclass returns GST_FLOW_OK, it MUST return a buffer of the + * requested size unless fewer bytes are available because an EOS condition + * is near. No buffer should be returned when the return value is different + * from GST_FLOW_OK. A return value of GST_FLOW_UNEXPECTED signifies that the + * end of stream is reached. * @do_seek: Perform seeking on the resource to the indicated segment. * @prepare_seek_segment: Prepare the GstSegment that will be passed to the * do_seek vmethod for executing a seek request. Sub-classes should override -- 2.7.4