[FFmpeg-devel] [PATCH] avfilter/internal: Improve docs about ff_request_frame()

[Michael Niedermayer]

On Tue, Jul 14, 2015 at 08:42:40PM +0200, James Darnley wrote:
> On 2015-07-14 19:50, Michael Niedermayer wrote:
> > From: Michael Niedermayer <michael at niedermayer.cc>
> > 
> > Signed-off-by: Michael Niedermayer <michael at niedermayer.cc>
> > ---
> >  libavfilter/internal.h |   17 +++++++++++++++++
> >  1 file changed, 17 insertions(+)
> > 
> > diff --git a/libavfilter/internal.h b/libavfilter/internal.h
> > index a7ec751..fcd1a5a 100644
> > --- a/libavfilter/internal.h
> > +++ b/libavfilter/internal.h
> > @@ -305,8 +305,25 @@ int ff_poll_frame(AVFilterLink *link);
> >  /**
> >   * Request an input frame from the filter at the other end of the link.
> >   *
> > + * The source filter may pass the request on to its sources, fullfill the
> > + * request from an internal buffer or any other means specific to its function.
> 
> fulfill (US) or fulfil (UK).
> 
> I don't think "source filter" is very clear here.  You mean the filter
> you send a request to, right?  Not the "source filter" (if that is the
> term used in lavfi) that puts frames into the filter chain.

yes, reworded


> 
> > + * One example of a source returning AVERROR(EAGAIN) is a buffer into which the
> > + * user application pushes new data, it cannot fullfill a request
> > + * or know its at EOF until the user application has given it this
> > + * information
> 
> I don't find this clear.

ok
so please help me reword this in a way that is clear

you have a filter A which can contain a frame, or no frame
it has a single buffer (it could have more but single is simpler as an
example)
if it has a frame in its buffer and the next filter does a
ff_request_frame() on it it returns that frame and returns success
(0) from the ff_request_frame() call
if it does not have a frame in its buffer its screwed and has to
return AVERROR(EAGAIN)
until the user application gives it a frame by external means or
tells it that EOF has been reached


> This is internal, isn't it?

yes, it is, it should be public API though its required for
implementing filters


> What does a "user
> application" matter to a filter, or someone writing a filter?

Derek complained on IRC that the "why" isnt documented, so
i tried to document it.


> 
> Perhaps something about filters rather than applications?
> 
> One example of a source returning AVERROR(EAGAIN) is a filter which
> buffers frames and cannot fulfil a request until "some event happens" or
> the filter cannot know it is as EOF until "some other event happens".

This misses the main point and it is possibly why derek was confused
about the API

EAGAIN here means "please return all the way back to the user
application so it can perform the next transcode step and refill
the filter graphs source _IF_ that is how the application interfaces
to the filergraph"

new patch:
commit 6628dd2aa001ec23de306840a41f05947abdf326
Author: Michael Niedermayer <michael at niedermayer.cc>
Date:   Tue Jul 14 19:44:59 2015 +0200

    avfilter/internal: Improve docs about ff_request_frame()

    Signed-off-by: Michael Niedermayer <michael at niedermayer.cc>

diff --git a/libavfilter/internal.h b/libavfilter/internal.h
index a7ec751..f1938f9 100644
--- a/libavfilter/internal.h
+++ b/libavfilter/internal.h
@@ -305,8 +305,24 @@ int ff_poll_frame(AVFilterLink *link);
 /**
  * Request an input frame from the filter at the other end of the link.
  *
+ * The input filter may pass the request on to its inputs, fulfill the
+ * request from an internal buffer or any other means specific to its function.
+ * When the end of a stream is reached AVERROR_EOF is returned and no further frames.
+ * When a filter is unable to output a frame for example due to its sources
+ * being unable to do so or because it depends on external means pushing data
+ * into it then AVERROR(EAGAIN) is returned.
+ * It is important that a AVERROR(EAGAIN) return is returned all the way to the
+ * caller (generally eventually a user application) as this step may (but does
+ * not have to be) neccessary to provide the input with the next frame.
+ *
+ * If a request is successful then the filter_frame() function will be called
+ * at least once before ff_request_frame() returns
+ *
  * @param link the input link
  * @return     zero on success
+ *             AVERROR_EOF on end of file
+ *             AVERROR(EAGAIN) if the previous filter cannot output a frame
+ *             currently and can neither guarantee that EOF has been reached.
  */
 int ff_request_frame(AVFilterLink *link);



[...]

-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

When you are offended at any man's fault, turn to yourself and study your
own failings. Then you will forget your anger. -- Epictetus
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 181 bytes
Desc: Digital signature
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20150714/fb2b7db9/attachment.sig>