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

[Michael Niedermayer]

ffmpeg | branch: master | Michael Niedermayer <michael at niedermayer.cc> | Tue Jul 14 19:44:59 2015 +0200| [522256b374fe3b8edfea0040bdd5878ea8c8e37c] | committer: Michael Niedermayer

avfilter/internal: Improve docs about ff_request_frame()

Reviewed-by: James Darnley <james.darnley at gmail.com>
Signed-off-by: Michael Niedermayer <michael at niedermayer.cc>

> http://git.videolan.org/gitweb.cgi/ffmpeg.git/?a=commit;h=522256b374fe3b8edfea0040bdd5878ea8c8e37c
---

 libavfilter/internal.h |   19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/libavfilter/internal.h b/libavfilter/internal.h
index a7ec751..9dded84 100644
--- a/libavfilter/internal.h
+++ b/libavfilter/internal.h
@@ -305,8 +305,27 @@ 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) necessary 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);