@@ -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);