[FFmpeg-devel] [PATCH] avfilter/internal: Improve docs about ff_request_frame()
michael at niedermayer.cc
Tue Jul 14 21:47:45 CEST 2015
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.
> > + * 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.
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
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
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
> 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"
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
@@ -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...
Size: 181 bytes
Desc: Digital signature
More information about the ffmpeg-devel