lavfi: add comments to explain the negotiation loop.

1 files changed, 19 insertions, 2 deletions

diff --git a/libavfilter/avfiltergraph.c b/libavfilter/avfiltergraph.c
index 860f1d892b..c5a9e3b59d 100644
--- a/libavfilter/avfiltergraph.c
+++ b/libavfilter/avfiltergraph.c
@@ -316,12 +316,24 @@ static int formats_declared(AVFilterContext *f)
     return 1;
 }
 
+/**
+ * Perform one round of query_formats() and merging formats lists on the
+ * filter graph.
+ * @return  >=0 if all links formats lists could be queried and merged;
+ *          AVERROR(EAGAIN) some progress was made in the queries or merging
+ *          and a later call may succeed;
+ *          AVERROR(EIO) (may be changed) plus a log message if no progress
+ *          was made and the negotiation is stuck;
+ *          a negative error code if some other error happened
+ */
 static int query_formats(AVFilterGraph *graph, AVClass *log_ctx)
 {
     int i, j, ret;
     int scaler_count = 0, resampler_count = 0;
-    int count_queried = 0, count_merged = 0, count_already_merged = 0,
-        count_delayed = 0;
+    int count_queried = 0;        /* successful calls to query_formats() */
+    int count_merged = 0;         /* successful merge of formats lists */
+    int count_already_merged = 0; /* lists already merged */
+    int count_delayed = 0;        /* lists that need to be merged later */
 
     for (i = 0; i < graph->nb_filters; i++) {
         AVFilterContext *f = graph->filters[i];
@@ -464,6 +476,11 @@ static int query_formats(AVFilterGraph *graph, AVClass *log_ctx)
     if (count_delayed) {
         AVBPrint bp;
 
+        /* if count_queried > 0, one filter at least did set its formats,
+           that will give additional information to its neighbour;
+           if count_merged > 0, one pair of formats lists at least was merged,
+           that will give additional information to all connected filters;
+           in both cases, progress was made and a new round must be done */
         if (count_queried || count_merged)
             return AVERROR(EAGAIN);
         av_bprint_init(&bp, 0, AV_BPRINT_SIZE_AUTOMATIC);